Sending your first campaign safely

Send one message to many people without hurting your number: test, vary the text, choose the speed, watch progress by webhook.

A campaign is the safe way to message many people: the Number Shield paces it, respects quiet hours, skips invalid and opted-out numbers and pauses on bad signals. Sending the same people one POST /v2/messages at a time gets paced anyway — and is easier to get wrong.

Before you send

Message only people who agreed to hear from you. optInConfirmed: true is your written confirmation and is required.
Check the number’s health and warm-up stage with GET /v2/numbers/{numberId}/health. A young number has low daily caps for new contacts (20 a day in its first days).
Vary the text: more than 50 new contacts in 24 h need a {variable} or [[spin|tax]] — identical texts to many new contacts are refused (IDENTICAL_MESSAGE_TEXT).
No URL shorteners, and no links to new contacts from numbers younger than 7 days.

GETHealth/v2/numbers/{numberId}/health

1. Create it as a draft and test on yourself

Create the campaign with start: false and two or three of your own numbers as recipients. Check what arrives on the phones, then create the real one.

POST /v2/campaigns

curl -X POST "https://mursilat.com/api/v2/campaigns" \
  -H "Authorization: Bearer $WASLA_API_KEY" \
  -H "Idempotency-Key: order-1042-confirm" \
  -H "Content-Type: application/json" \
  -d '{
  "numberId": "cm1abcd2345efgh6789ijkl",
  "name": "عرض الجمعة",
  "content": {
    "type": "cta_url",
    "body": {
      "text": "أهلاً {name|عميلنا} 👋 خصم 20% لحد الجمعة"
    },
    "cta": {
      "title": "شوف العرض",
      "url": "https://example.com/offer?ref={name}"
    }
  },
  "recipients": [
    {
      "phone": "201001234567",
      "variables": {
        "name": "منى"
      }
    },
    {
      "phone": "966501234567"
    }
  ],
  "optInConfirmed": true,
  "speed": "SAFE"
}'

const res = await fetch('https://mursilat.com/api/v2/campaigns', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WASLA_API_KEY}`,
    'Idempotency-Key': 'order-1042-confirm',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "numberId": "cm1abcd2345efgh6789ijkl",
    "name": "عرض الجمعة",
    "content": {
      "type": "cta_url",
      "body": {
        "text": "أهلاً {name|عميلنا} 👋 خصم 20% لحد الجمعة"
      },
      "cta": {
        "title": "شوف العرض",
        "url": "https://example.com/offer?ref={name}"
      }
    },
    "recipients": [
      {
        "phone": "201001234567",
        "variables": {
          "name": "منى"
        }
      },
      {
        "phone": "966501234567"
      }
    ],
    "optInConfirmed": true,
    "speed": "SAFE"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['WASLA_API_KEY']}", "Idempotency-Key": "order-1042-confirm"}
res = requests.post(
    "https://mursilat.com/api/v2/campaigns",
    headers=headers,
    json={
        "numberId": "cm1abcd2345efgh6789ijkl",
        "name": "عرض الجمعة",
        "content": {
            "type": "cta_url",
            "body": {
                "text": "أهلاً {name|عميلنا} 👋 خصم 20% لحد الجمعة"
            },
            "cta": {
                "title": "شوف العرض",
                "url": "https://example.com/offer?ref={name}"
            }
        },
        "recipients": [
            {
                "phone": "201001234567",
                "variables": {
                    "name": "منى"
                }
            },
            {
                "phone": "966501234567"
            }
        ],
        "optInConfirmed": True,
        "speed": "SAFE"
    },
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

<?php
$ch = curl_init('https://mursilat.com/api/v2/campaigns');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WASLA_API_KEY'),
        'Idempotency-Key: order-1042-confirm',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'numberId' => 'cm1abcd2345efgh6789ijkl',
        'name' => 'عرض الجمعة',
        'content' => [
            'type' => 'cta_url',
            'body' => [
                'text' => 'أهلاً {name|عميلنا} 👋 خصم 20% لحد الجمعة'
            ],
            'cta' => [
                'title' => 'شوف العرض',
                'url' => 'https://example.com/offer?ref={name}'
            ]
        ],
        'recipients' => [
            [
                'phone' => '201001234567',
                'variables' => [
                    'name' => 'منى'
                ]
            ],
            [
                'phone' => '966501234567'
            ]
        ],
        'optInConfirmed' => true,
        'speed' => 'SAFE'
    ], JSON_UNESCAPED_UNICODE),
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) { throw new Exception($data['error']['code'] . ': ' . $data['error']['message']); }
print_r($data);

2. Choose the speed

`speed`	When
`SAFE`	WhenYoung numbers, cold lists, first campaigns. The slowest.
`NORMAL`	WhenThe default. Established numbers with good health.
`FAST`	WhenWarm audiences that know you. Still inside the Shield caps.

Quiet hours apply to campaigns (default 22:00–09:00 in your time zone): sending waits and continues in the morning. Cold campaign messages get your opt-out line (default «للإلغاء أرسل: إلغاء»).

3. Watch it

Subscribe to campaign.status and read progress with GET /v2/campaigns/{campaignId} (counts, pause reason, ETA). The Shield pauses a campaign by itself when delivery drops below 80 % over the last hour, when more than 3 in 100 people opt out, or when WhatsApp rate-limits the number — first for 1 hour, then 24 hours. Fix the cause before resuming.

4. After it ends

Within 24 hours of the end, the campaign’s text, media link, buttons and every recipient row are deleted. The totals stay (purged: true); recipients answer 410 CAMPAIGN_PURGED. Export what you need before that.