Skip to Content
Developer docsBeta

Quickstart

From a new key to a delivered message and your first webhook, in about five minutes.

You'll need a Mawgood workspace on a paid plan with a connected WhatsApp number and at least one approved template. You can see your templates in Mawgood › WhatsApp templates.

Create a key

Open Mawgood › Settings › Developers and create a key (owners and admins can). Keep the scopes it starts with (campaigns:send, campaigns:read, templates:read, numbers:read): they cover every call below. Copy it now: it's shown once. Keep it on your server, never in a browser or mobile app.

export MAWGOOD_API_KEY="mwg_sk_live_..."

Use a live key (mwg_sk_live_) to send. A test key (mwg_sk_test_) checks every request fully, then answers 403 test_key_cannot_send instead of sending.

Check it works:

curl https://api.mawgood.ai/v1/me \
  -H "Authorization: Bearer $MAWGOOD_API_KEY"

Pick a template

List your approved templates. Each one says which numbers can send it and which variables it needs.

curl "https://api.mawgood.ai/v1/templates?status=approved" \
  -H "Authorization: Bearer $MAWGOOD_API_KEY"
Response (shortened)
{
  "data": [
    {
      "id": "tpl_8Kq2mZ",
      "name": "order_shipped",
      "language": "ar",
      "category": "utility",
      "status": "approved",
      "numbers": ["num_3Fh7Ws"],
      "variables": {
        "body": [
          { "index": 1, "name": "customer.name", "example": "Mona" },
          { "index": 2, "name": "order.id", "example": "#1042" }
        ],
        "buttons": []
      }
    }
  ]
}

Send to one number

Send the template to your own phone first. Put the body values in order: they're sent exactly as you give them. The Idempotency-Key header is required: a retry with the same key never sends twice.

curl https://api.mawgood.ai/v1/campaigns \
  -H "Authorization: Bearer $MAWGOOD_API_KEY" \
  -H "Idempotency-Key: quickstart-1" \
  -H "Content-Type: application/json" \
  -d '{
    "template": { "name": "order_shipped", "language": "ar" },
    "recipients": [
      { "phone": "+201001234567", "variables": { "body": ["Mona", "#1042"] } }
    ]
  }'

You get 202 Accepted and the campaign:

{
  "id": "cmp_9Xa4Lr",
  "status": "preparing",
  "total": 1,
  "pacing": { "mode": "all_at_once" },
  "pacingAdjusted": false,
  "estimatedCredits": 1,
  "skipped": []
}

The message arrives on your phone a few seconds later. You can also check it with GET /campaigns/cmp_9Xa4Lr.

Receive a webhook

In Settings › Developers, set your webhook URL, pick its events and copy its signing secret. For a first test, a temporary public HTTPS URL is enough (a request bin, or a tunnel to your laptop); Send test event posts a ping to it. Send another message and you'll receive a POST like this for each status change:

message.status (shortened)
{
  "id": "evt_4Rt9Kp",
  "type": "message.status",
  "createdAt": "2026-11-20T10:15:04Z",
  "data": {
    "campaignId": "cmp_9Xa4Lr",
    "campaignName": "order_shipped",
    "source": "api",
    "at": "2026-11-20T10:15:04Z",
    "recipient": {
      "phone": "+201001234567",
      "status": "delivered",
      "deliveredAt": "2026-11-20T10:15:03Z"
    }
  }
}

Before trusting it in production, verify the signature.

Next

On this page