الإرسال والاستقبال

القنوات

القناة رقم ترسل منه، والمزوّد خلفها هو الفارق الوحيد بينها وبين غيرها. اختيار القناة أول قرار حقيقي في أي تكامل، ولذلك تذكر هذه الصفحة بوضوح ما يفعله كل مزوّد، وما يكلّفك من مخاطرة، وما لم يُبنَ بعد.

ثلاثة مزوّدين

واجهة الإرسال واحدة في الثلاثة. والذي يختلف هو كيف تحصل على الرقم، وما يستطيعه الرقم، وما يجري له مع الوقت.

المزوّد	التوفّر	الوصف
sandbox	متاح	رقم اختبار مشترك تملكه المنصة. فوري ومجاني، ومحصور بمستلمين أثبتوا ملكيتهم لأرقامهم.
qr	متاح	حساب واتساب الخاص بالعميل، يُربط بمسح رمز QR. فوري، وغير رسمي — راجع ملاحظة السياسة أدناه.
meta	غير متاح بعد	منصة واتساب للأعمال الرسمية. لا محوّل منشور، فإنشاء قناة بهذا المزوّد يُرفض بخطأ تحقق يسمّي المزوّدين الذين تدعمهم هذه البيئة.

النقاط

GET/v1/channelsPOST/v1/channelsGET/v1/channels/{channelId}GET/v1/channels/{channelId}/capabilitiesPATCH/v1/channels/{channelId}DELETE/v1/channels/{channelId}

حذف قناة يؤرشفها ولا يمحوها: تبقى الرسائل المرسلة عبرها قابلة للقراءة، والعملية قابلة للتكرار.

curl

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

# 200 OK
# {
#   "data": [{
#     "id": "ch_...",
#     "name": "Sandbox",
#     "provider": "sandbox",
#     "status": "connected",
#     "phone_number": "+999...",
#     "is_default": true,
#     "capabilities": {
#       "send_text": true,
#       "send_media": false,
#       "send_local_template": true,
#       "send_meta_template": false,
#       "campaigns": false,
#       "max_throughput_mps": 2
#     },
#     "capabilities_refreshed_at": "2026-08-13T10:00:00.000Z"
#   }],
#   "page": { "next_cursor": null, "has_more": false }
# }

حالة القناة

لا يُقبل الإرسال إلا من قناة connected؛ وكل حالة أخرى تُرفض بـ CHANNEL_NOT_CONNECTED.

الحالة	الوصف
pending	أُنشئت ولم تتصل بشيء بعد.
connecting	جارٍ الاتصال بالمزوّد.
awaiting_scan	رمز QR بانتظار المسح.
connected	جاهزة. وهي الحالة الوحيدة التي يُقبل منها الإرسال.
degraded	متصلة لكن غير سليمة — المزوّد متعذّر أو مخفق. قد يُقبل الإرسال وقد يخفق.
disconnected	لم تعد مرتبطة. تصل إليها قناة QR بعد تسجيل الخروج.
suspended	أوقفتها المنصة.
archived	أحالتها مساحة العمل إلى الأرشيف. ويبقى سجلها مقروءا.

القدرات

كل قناة تنشر ما يستطيعه مزوّدها فعلا. اقرأها ولا تفترضها — فقيمة send_media اليوم false في كل مكان، والقدرة الغائبة تعطي 409 لا تجاهلا صامتا.

القدرة	sandbox	qr
send_text	true	true
send_media	false	false
send_local_template	true	true
send_meta_template	false	false
campaigns	false	false
official_meta	true	false
business_initiated_templates	false	false
message_status	true	true
read_receipts	true	true
coexistence	false	false

ومعها يُنشر معدل التمرير: 2 رسالة في الثانية على قناة Sandbox و0.5 على قناة QR.

لقطة لا استعلام حي

القدرات تأتي من لقطة مخزّنة. وقبل أخذ أول لقطة تجيب نقطة القدرات بـ 409 مع details.reason = "capabilities_not_refreshed" بدل التخمين.

الـ Sandbox

الـ Sandbox مجموعة أرقام اختبار تملكها المنصة وتتشاركها مساحات العمل. حجز رقم ينشئ قناة وجلسة؛ والجلسة هي التي تحمل التوثيق ومدة الصلاحية.

POST/v1/sandbox/sessionsPOST/v1/sandbox/sessions/{sessionId}/verifyGET/v1/sandbox/sessions/{sessionId}DELETE/v1/sandbox/sessions/{sessionId}

القواعد التي ستفاجئك

كل عملية Sandbox تتطلب API key بوضع test. ومفتاح live يعطي 403.
لا يمكنك مراسلة إلا مستلما أثبت ملكيته بإرسال رمز التحقق من جهازه. وأي مستلم آخر يُرفض.
ينتهي الحجز بعد 24 ساعة، وبعدها تُرفض عمليات الإرسال وتحجز من جديد.
المجموعة محدودة. وحين تبلغ كل الأرقام السليمة سعتها يكون الحجز 503، لا انتظارا في طابور.
لا يمكنك اختيار رقم. الحجز يختار لك، ولا يختار رقما يخدم المستلم نفسه لجهة أخرى.

تمشي البداية السريعة على المسار كاملا من أوله إلى آخره.

QR — رقم العميل نفسه

هذا ليس المسار الرسمي لواتساب

ربط QR يقود بروتوكول تعدد الأجهزة الخاص بواتساب بوصفه عميلا غير رسمي. وسياسات واتساب تقيّد العملاء غير المصرّح بهم والإرسال الجماعي والمراسلة الآلية، والحساب الموصول بهذه الطريقة قد يُقيَّد أو يُحظر. ولا حدّ تقني يجعله آمنا — ولن تصف المنصة أبدا الـ QR بأنه تكامل Meta رسمي، ولن تدّعي أن حسابا لا يمكن حظره.

الحد الأمني أدناه سياسة اختارتها المنصة لتكون متحفظة. وهو ليس ضمانا من واتساب، والبقاء تحته لا يضمن شيئا.

تُنشأ قناة QR من النقطة المعتادة، ثم تُربط بمسح رمز من الهاتف المالك للحساب.

curl

curl -X POST https://whats.azzamkh.sa/api/v1/channels \
  -H "Authorization: Bearer <access token>" \
  -H "X-Workspace-Id: ws_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support line", "provider": "qr" }'

# 201 Created  { "id": "ch_...", "provider": "qr", "status": "pending", ... }

# Pairing itself is a browser flow: POST .../qr/start, then read the codes
# from the SSE stream. Those four routes do NOT accept an API key.

مسار الربط

الربط مسار متصفح، ومساراته الأربعة تقبل access token فقط — والـ API key مرفوض. تسجّل الـ API النية؛ ويمسك عامل مستقل المقبس ويولّد الرموز، وهي تصل عبر بث الأحداث لا في رد الاستعلام.

POST/v1/channels/{channelId}/qr/startGET/v1/channels/{channelId}/qr/statusGET/v1/channels/{channelId}/qr/streamPOST/v1/channels/{channelId}/qr/logout

حدود قناة الـ QR

الحد	القيمة	الوصف
الحد الأمني	200 / 24h	رسائل صادرة لكل نافذة متحركة لكل قناة. وتجاوزه يعطي 429 برمز QR_SAFETY_LIMIT_REACHED.
معدل المستلم الواحد	6 / min	رسائل في الدقيقة إلى مستلم بعينه.
معدل التمرير	0.5 msg/s	السرعة التي يسلّم بها الموزّع الرسائل إلى المزوّد.
صلاحية الرمز	60s	كم يبقى رمز QR المعروض صالحا قبل أن يُستبدل.

Meta Cloud API

غير متاح بعد

لا محوّل Meta منشور. وإنشاء قناة بهذا المزوّد يُرفض بـ 422 يسرد في details.available المزوّدين الذين تدعمهم هذه البيئة. ولا يوجد endpoint للتسجيل ولا endpoint لتقديم القوالب.

صُممت الـ API لتجعل هذا تبديل قناة لا إعادة كتابة: طلب الإرسال وشكل الرسالة وأحداث الـ webhook ورموز الأخطاء كلها مستقلة عن المزوّد. وحين تصل Meta، فإن تكاملا كُتب على الـ Sandbox أو على الـ QR يغيّر القناة التي يسمّيها ولا يغيّر شيئا آخر.