إرسال الرسائل

إرسال رسالة

رد 201 يعني القبول لا التسليم. تُوضع الرسالة في طابور ويوزّعها عامل مستقل؛ تابعها عبر نقاط الرسائل أو عبر الـ 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"
# }

جسم الطلب

المطلوب دائما هو to وحده. وtext مطلوب حين يكون النوع نصا، وtemplate.slug حين يكون قالبا.

قائمة الأنواع هي بالضبط "text", "template". وإرسال صورة أو مستند أو صوت أو فيديو غير متاح بعد على هذه النقطة؛ أما الوسائط الواردة فتصل وتُسجّل على الرسالة.

الاستجابة

استجابة الإرسال صغيرة عمدا. اقرأ الرسالة إن احتجت conversation_id أو معرّف المزوّد أو خط الزمن — فلا شيء من ذلك موجود لحظة القبول.

إرسال قالب

اجعل النوع template وسمّ الـ slug واللغة. راجع القوالب لمعرفة كيف يُعرَّف المحتوى ومتغيراته.

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": "سارة" }
    }
  }'

الفئات والأولوية

تصف الفئة الغرض من الرسالة، وتستخدمها المنصة لتقرر ما يتقدم حين تمتلئ القناة.

إغفال الفئة يصنّف الرسالة على أنها utility.

الحماية من التكرار

أرسل header باسم Idempotency-Key مع كل إرسال. هو اختياري، وهو الفرق بين انقطاع شبكة لا يكلّفك شيئا وانقطاع يكلّفك رسالة مكررة.

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", ... } }

• تُقارن الأجسام بتجزئة صورتها القياسية، فترتيب المفاتيح والمسافات لا يهم — القيم وحدها هي التي تهم.
• المفاتيح محصورة بمساحة عملك. وعميلان يمكن أن يستعملا القيمة نفسها دون تصادم.
• يُحفظ المفتاح 24 ساعة ثم يُنسى. وإعادة استعماله بعدها ترسل رسالة جديدة.
• طول المفتاح 255 حرفا بحد أقصى. والـ UUID اختيار جيد.

الحالات وخط الزمن

docs.pages.messages.lifecycle.body

أربع حالات نهائية لا يتبعها شيء: read, failed_permanent, cancelled, expired.

قراءة الرسائل

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", ... }
#   ]
# }

ما قد يخفق

كل هذه تتبع الغلاف الموصوف في الأخطاء والحدود. أما الإخفاق بعد القبول فليس خطأ HTTP أصلا — بل يصل تغيّرَ حالة وwebhook.