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"{
"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:
{
"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
- Sending to many numbers: CSVs, idempotency and the 10,000 limit.
- Template variables: body values, media headers and buttons.
- Statuses & errors: what every status means.