Sending messages

Send a message

A 201 means accepted, not delivered. The message is queued and dispatched by a worker; watch it with the message endpoints or with webhooks.

curl -X POST https://whats.azzamkh.sa/api/v1/messages \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "ch_...",
    "to": "+9665XXXXXXXX",
    "type": "text",
    "text": { "body": "Your code is 481902" }
  }'

# 201 Created
# {
#   "id": "msg_...",
#   "status": "queued",
#   "channel_id": "ch_...",
#   "to": "+9665XXXXXXXX",
#   "type": "text",
#   "category": "utility",
#   "created_at": "2026-08-13T10:00:00.000Z"
# }

Request body

Only to is unconditionally required. text is required when the type is text, and template.slug when it is template.

The type enum is exactly "text", "template". Sending an image, a document, audio or video is not yet available on this endpoint; inbound media still arrives and is recorded on the message.

Response

The send response is deliberately small. Read the message back if you need its conversation_id, its provider id, or its timeline — none of those exist yet at acceptance time.

Sending a template

Set the type to template and name the slug and language. See templates for how the content and its variables are defined.

curl -X POST https://whats.azzamkh.sa/api/v1/messages \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "ch_...",
    "to": "+9665XXXXXXXX",
    "type": "template",
    "category": "utility",
    "template": {
      "slug": "order_confirmation",
      "language": "ar",
      "variables": { "order_id": "A-10428", "name": "سارة" }
    }
  }'

Categories and priority

The category describes what a message is for, and the platform uses it to decide what goes first when a channel is saturated.

Omitting the category classifies the message as utility.

Idempotency

Send an Idempotency-Key header on every send. It is optional, and it is the difference between a network timeout costing you nothing and costing you a duplicate message.

KEY=$(uuidgen)

# First call: the message is created.
curl -X POST https://whats.azzamkh.sa/api/v1/messages \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "Idempotency-Key: $KEY" \
  -d '{ "to": "+9665XXXXXXXX", "type": "text", "text": { "body": "Hello" } }'
# 201 Created   { "id": "msg_A", "status": "queued", ... }

# Same key, IDENTICAL body: the stored response is replayed byte for byte.
# No second message is created.
# 201 Created
# idempotent-replay: true
# { "id": "msg_A", "status": "queued", ... }

# Same key, DIFFERENT body:
# 409 Conflict
# { "error": { "code": "IDEMPOTENCY_CONFLICT", ... } }

• Bodies are compared by a hash of their canonical form, so key order and whitespace do not matter — only the values do.
• Keys are scoped to your workspace. Two customers can use the same key value without colliding.
• A key is remembered for 24 hours, then forgotten. Reusing it after that sends a new message.
• A key is at most 255 characters. A UUID is a good choice.

States and the timeline

docs.pages.messages.lifecycle.body

Four states are terminal, and nothing follows them: read, failed_permanent, cancelled, expired.

Reading messages back

curl https://whats.azzamkh.sa/api/v1/messages/msg_... \
  -H "Authorization: Bearer $WA_API_KEY"

# 200 OK
# {
#   "id": "msg_...",
#   "status": "delivered",
#   "direction": "outbound",
#   "attempts": 1,
#   "queued_at": "2026-08-13T10:00:00.000Z",
#   "sent_at": "2026-08-13T10:00:01.140Z",
#   "delivered_at": "2026-08-13T10:00:02.980Z",
#   "read_at": null,
#   "events": [
#     { "id": "mev_...", "from_status": null, "status": "created", ... },
#     { "id": "mev_...", "from_status": "created", "status": "queued", ... },
#     { "id": "mev_...", "from_status": "queued", "status": "dispatching", ... },
#     { "id": "mev_...", "from_status": "dispatching", "status": "sent", ... },
#     { "id": "mev_...", "from_status": "sent", "status": "delivered", ... }
#   ]
# }

What can go wrong

All of these follow the envelope in errors and limits. A failure after acceptance is not an HTTP error at all — it arrives as a state change and a webhook.