الاتصال عبر Meta Graph API
هناك طريقتان لإرسال رسائل واتساب عبر WizMessage. وتعد WizMessage API الخيار الأنسب إذا كنت تبدأ من الصفر — فهي تمنحك متغيرات قوالب مسماة، وواجهة مستخدم لربط الحقول، وحقل reference يمكنك ربط سجلاتك به.
توثق هذه الصفحة الطريقة الأخرى. فهي تحاكي WhatsApp Cloud API التابعة لـ Meta بدقة تكفي لأن يعمل الكود المكتوب مسبقاً لـ Meta هنا بعد تغيير أمرين اثنين: عنوان URL الأساسي والرمز المميز (token). المسارات نفسها، ونصوص الطلبات نفسها، ونصوص الاستجابات نفسها، وغلاف الأخطاء نفسه. وإذا كان لديك تكامل حالي، أو مكتبة برمجية، أو مطور يعرف بالفعل Cloud API، فهذا هو الطريق الأقصر.
وهي ليست مجرد واجهة للإرسال؛ فإلى جانب المراسلة، توفر نقاط نهاية إدارة الحساب — إنشاء القوالب وحذفها، وقراءة الملف التجاري وإعادة كتابته، ورموز QR، وإعدادات التجارة، وقائمة الحظر، وإعدادات الهاتف والتدفقات — وكلها عبر مسارات Meta نفسها. إدارة الحساب هي الفهرس الشامل، وما لا يتوفر هنا هو النصف الآخر الذي لا يقل أهمية.
تستخدم كلتا الواجهتين مفاتيح API نفسها، والأذونات نفسها، وحدود المعدل نفسها. لا شيء متوقف أو مهمل — اختر ما يناسب كل تكامل، ويمكنك استخدام كلتيهما معاً في الوقت ذاته.
أيهما تريد
الأساسيات
عنوان URL الأساسي، والإصدار في المسار
https://wizmessage.com/v26.0/{phone-number-id}/messages
جزء الإصدار حقيقي ومطلوب، ولكن قيمته لا تُغيّر أي شيء. فنحن نطابقه بصيغة v{major}.{minor} ثم نتجاهله — فالمنصة هي التي تحدد إصدار Graph الذي تتواصل معه في المراحل العليا.
نتيجتان يجدر بك معرفتهما:
- تثبيت إصدار قديم يستمر في العمل. عندما توقف Meta الإصدار المضمّن في شيفرتك البرمجية، تواصل الاستدعاءات هنا عملها. لا شيء يتطلب الجدولة.
v26بمفرده يُرفَض. الرقم الفرعي ليس اختيارياً. فـv26.0مقبول، أماv26فيعطي خطأ 404.
يجب أن يكون {phone-number-id} هو رقم واتساب التابع لمفتاح API الذي تستخدمه. وأي شيء آخر يُرفَض — راجع عندما لا يكون المعرّف لك.
المصادقة
أرسل مفتاح API الخاص بك كرمز حامل (bearer token)، تماماً كما ترسل رمز الوصول إلى Meta.
| الترويسة | القيمة |
|---|---|
Authorization | Bearer pk_live_… — مفتاح API الكامل الخاص بك، وليس البادئة المعروضة في لوحة التحكم. |
يُقبل X-API-Key هنا أيضاً، لذا فإن المفتاح الذي يعمل بالفعل مع WizMessage API لا يحتاج إلى تغيير في الترويسة. ويُفضَّل استخدام صيغة Bearer: فهي ما ترسله حزمة SDK الأصلية من Meta دون تعديل، وهذا هو الهدف الأساسي من هذه الواجهة.
ملاحظة: يجب إيقاف خيار «Require signature» في المفتاح. فالأمر هنا ليس مسألة تفضيل شخصي. فالمفتاح الذي يُفعَّل فيه هذا الخيار لا يمكنه حفظ خطاف ويب لـ Meta Graph — إذ ترفض لوحة التحكم ذلك برسالة: «إنفاذ الطلب الموقّع غير متوافق مع تنسيق Graph — عطلّه في هذا المفتاح أولاً» — ويُرفَض كل استدعاء غير موقّع يجريه عبر هذه الواجهة بالرمز
code 190مع خطأ401. ولا يستطيع أي عميل Cloud API جاهز توليد توقيع الطلب الخاص بنا، لذا فهما مانعان لبعضهما بحكم التصميم.
اشتراكك
تتطلب وحدة API اشتراكاً نشطاً في Wiz Bot أو Wiz Pro. وينطبق هذا على كلتا الواجهتين — WizMessage API وهذه الواجهة — ويجري التحقق من ذلك عند كل استدعاء، وليس فقط عند إنشاء المفتاح.
إذا انتهت صلاحية الاشتراك، فلن يتوقف API في تلك اللحظة. بل إن أول استدعاء بعد انتهاء الصلاحية يبدأ مهلة مدتها سبعة أيام ويُسمح بمروره، وتتضمن كل استجابة خلال تلك المهلة ترويسة:
| الترويسة | القيمة |
|---|---|
X-Subscription-Warning | Subscription inactive. API access ends in 5 day(s). |
وبعد انتهاء المهلة، تُرفَض الاستدعاءات برمز Graph code 10 مع خطأ 403:
{
"error": {
"message": "(#10) Access denied. The API module requires an active Wiz Bot or Wiz Pro subscription. Renew at /subscriptions to restore access.",
"type": "OAuthException",
"code": 10,
"fbtrace_id": "AKnBaXsYl7FlmMVw3ql5Ywo"
}
}
ثلاثة تفاصيل تحدد ما إذا كنت ستنتبه في الوقت المناسب:
- يبدأ احتساب الوقت عند أول استدعاء تجريه، وليس في تاريخ الفاتورة. فالمفتاح الذي يظل خاملاً لمدة أسبوعين بعد انتهاء الصلاحية يحصل على أيامه السبعة كاملة، بدءاً من موعد استدعائه التالي.
- المهلة لكل مفتاح API، وليست للحساب ككل. فكل مفتاح يدير وقته الخاص انطلاقاً من أول استدعاء له، ولذا فإن مفتاحاً تختبر به ومفتاحاً يشغّل بيئة الإنتاج ستنتهي صلاحيتهما في يومين مختلفين. فتحقق من الترويسة في المفتاح الذي يهمك.
- يأتي الرفض دون أي تحذير في الطلب الذي يتسبب فيه. تُعدّ
X-Subscription-Warningهي الإشعار المسبق الوحيد — فسجّلها في السجلات، وإلا فسيكون أول ما تكتشفه هو403.
ملاحظة: يستغرق التجديد بضع دقائق حتى يسري مفعوله، وليس ثواني. إذ تُخزَّن استجابة الاستحقاق مؤقتاً لمدة خمس دقائق وحالة الاشتراك التي تستند إليها لخمس دقائق أخرى، ولذا فإن التجديد الذي يُجرى أثناء تعثر التكامل لن يحل المشكلة في إعادة المحاولة التالية مباشرة. انتظر بضع دقائق قبل أن تستنتج أنه لم ينجح.
إرسال رسالة
استخدم POST /{version}/{phone-number-id}/messages مع جسم الطلب الخاص بـ Meta. فنحن لا نتحقق منه إلا للتأكد من أنه رسالة واتساب — إذ إن Meta هي المرجع في تحديد شكل الرسالة الصالحة، وأخطاؤها أفضل من أي أخطاء يمكننا ابتداعها.
POST https://wizmessage.com/v26.0/106540352242922/messages
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "919876543210",
"type": "text",
"text": { "preview_url": false, "body": "Your order has shipped." }
}
ملاحظة: يأخذ الحقل
toأرقاماً مجردة هنا —919876543210، دون علامة+. هذا هو تنسيق Meta، وهو أكثر الأخطاء شيوعاً عند الانتقال بين الواجهتين: إذ يتطلب WizMessage API صيغة+E.164ويرفض أي صيغة أخرى، بينما تمرر هذه الواجهة قيمتك مباشرة إلى Meta. والاستثناء الوحيد هوPOST /messages/contacts، الذي يقبل أيّاً من الصيغتين تحديداً حتى ينتقل جسم طلب Graph دون أي تعديل.
وإرسال القالب يأخذ بنية Meta أيضاً — مكونات موضعية، لا متغيرات مسمّاة. فلا توجد طبقة تعيين على هذه الواجهة، وهي المقايضة التي تقدمها مقابل التوافق.
{
"messaging_product": "whatsapp",
"to": "919876543210",
"type": "template",
"template": {
"name": "payment_failed_alert",
"language": { "code": "en" },
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Priya Sharma" },
{ "type": "text", "text": "12 Aug 2026" },
{ "type": "text", "text": "Wiz Pro" }
]
}
]
}
}
إرسال بطاقة جهة اتصال
النوع type: "contacts" هو vCard — اسم، وأي بيانات أخرى ترفقها. وقد ظل يعمل دائماً على هذه الواجهة ولا يزال، مع بقاء جسم طلب Meta دون تغيير.
POST https://wizmessage.com/v26.0/106540352242922/messages
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "919876543210",
"type": "contacts",
"contacts": [
{
"name": {
"formatted_name": "Priya Sharma",
"first_name": "Priya",
"last_name": "Sharma"
},
"phones": [
{ "phone": "+911122334455", "type": "WORK", "wa_id": "911122334455" }
],
"emails": [
{ "email": "[email protected]", "type": "WORK" }
],
"org": { "company": "Acme Retail", "department": "Support", "title": "Account Manager" }
}
]
}
حقل name.formatted_name هو الحقل الوحيد الذي يتطلبه واتساب. ومع ذلك يجدر بك دائماً إضافة phones[].wa_id: فمعه تتضمن البطاقة زر Message الذي يفتح محادثة مع ذلك الشخص، وبدونه لا يمكن سوى حفظ البطاقة.
يمكن أيضاً إرسال جسم الطلب نفسه تماماً إلى POST /messages/contacts في WizMessage API — بمفاتيح الغلاف، وقيمة to المكونة من أرقام مجردة، وكل شيء. وهي نقطة النهاية الوحيدة في تلك الواجهة التي تقبل هذا الشكل، ووجودها يرجع إلى أن الأمرين اللذين لا يمكن لهذا المسار توفيرهما جديران بالاهتمام: فالإرسال هنا لا يُصنَّف تحت message_id، ومن ثم لا توجد حالة للبحث عنها ولا خطاف ويب message.sent لمطابقته، كما أن جسم الطلب بالكاد يخضع للفحص قبل وصوله إلى Meta. وتغيير عنوان URL هو كل ما تتطلبه عملية الانتقال.
ملاحظة: إرسال عدة بطاقات في رسالة واحدة يعتمد على مصفوفة
contactsالخاصة بـ Meta، وتقبل Meta ما يصل إلى 257 بطاقة منها. أما نقطة نهاية WizMessage فتحدد الحد الأقصى بعشر بطاقات — ولذا فإن إرسال بطاقات متعددة الذي يعمل هنا يُعدّ واحداً من أجسام الطلبات القليلة التي لن تنتقل دون تغيير.
تعيين الرسالة كمقروءة
تُرسَل إشعارات القراءة ومؤشرات الكتابة إلى نقطة النهاية نفسها، بجسم طلب لا يتضمن to ولا type. وتعتمد دالة markAsRead() في كل حزمة SDK خاصة بـ Cloud API على عمل هذه الميزة، ولذلك فهي مدعومة تماماً كما حددتها Meta.
POST https://wizmessage.com/v26.0/106540352242922/messages
{
"messaging_product": "whatsapp",
"status": "read",
"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…"
}
يكون الرد هو {"success": true} — وليس غلاف الإرسال الموضح أدناه. فرّع منطق شيفرتك استناداً إلى الاستدعاء الذي أجريته بدلاً من محاولة قراءة messages[0].id من كل استجابة.
ما يعود في الاستجابة
استجابة Meta، دون أي تعديل:
{
"messaging_product": "whatsapp",
"contacts": [{ "input": "919876543210", "wa_id": "919876543210" }],
"messages": [{ "id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…" }]
}
معرّف wamid هذا هو وسيلتك الوحيدة للتعامل مع الرسالة. فهذه الواجهة تتعمد عدم تضمين حقل reference ولا نقطة نهاية للبحث عن الحالة — فكلاهما إضافتان من WizMessage لا تتوافران في واجهة API الخاصة بـ Meta، ولذا فإن تضمينهما كان سيُخلّ بالتوافق الذي أُنشئت هذه الواجهة من أجله.
لتتبع مصير الرسالة، طابق wamid مع حالات التسليم الواردة على خطاف الويب الخاص بك. وإذا كنت تفضّل وجود حقل مخصص لك للاستناد إليه، فهذا هو الغرض من حقل reference في WizMessage API.
الأخطاء
ترد الأخطاء في مظروف Meta، لا في مظروفنا أبداً. ومصدر الخطأ هو ما يحدد مقدار ما يخصنا منه.
الأخطاء التي نثيرها
code | HTTP | متى |
|---|---|---|
190 | 401 | مفتاح مفقود أو غير معروف أو ملغى أو معلق أو منتهي الصلاحية — أو استدعاء غير موقّع لمفتاح يتطلب توقيعات. يُثار أيضاً عندما يفقد حساب واتساب نفسه اتصاله بـ Meta؛ راجع الملاحظة أدناه. |
10 | 403 | المفتاح يفتقر إلى الإذن الذي يتطلبه هذا الاستدعاء (راجع الأذونات)، أو أن اشتراك الحساب قد انتهت صلاحيته وتجاوز فترة السماح الخاصة به. |
4 | 429 | استُنفد الحد المسموح به للمفتاح في الدقيقة أو اليوم. |
100 | 400 | طلب مشوّه الصياغة، أو معرّف id في المسار لا يخصك، أو نقطة نهاية لا تخدمها هذه الواجهة. |
2 | 500 | حدث خطأ ما من جانبنا. أعد المحاولة. |
ملاحظة: أمران مختلفان يُرجِعان
190، ويتطلبان حلين متعاكسين. إذا كانت الرسالة تذكر المفتاح، فقم بتدوير المفتاح أو إعادة إدخاله. وإذا كانت تنص على «يجب تجديد الاتصال بحساب WhatsApp Business هذا»، فالمفتاح سليم والحساب هو الذي فقد اتصاله بـ Meta — أعِد توصيله من لوحة التحكم. وتدوير مفتاح يعمل استجابةً للحالة الثانية يُضيّع نصف يوم دون أن يغيّر شيئاً.
الأخطاء التي تثيرها Meta
تُمرَّر تماماً كما وردت، مع حالة HTTP الخاصة بـ Meta. ويبقى كل ما أرسلته Meta كما هو — error_subcode وerror_data.details ومعرّف fbtrace_id الخاص بـ Meta:
{
"error": {
"message": "Unsupported post request. Object with ID '106540352242922' does not exist, cannot be loaded due to missing permissions, or does not support this operation.",
"code": 100,
"type": "GraphMethodException",
"error_subcode": 33,
"fbtrace_id": "AKnBaXsYl7FlmMVw3ql5Ywo"
}
}
ملاحظة: لاحظ
typeفي ذلك المثال —GraphMethodException، وليسOAuthException. فـ Meta تستخدم عدة أنواع من الاستثناءات ونحن لا نوحدها. اعتمد في معالجة الحالات علىerror.code، فهو قيمة عددية وثابتة؛ وعاملtypeكتسمية للبشر.
عندما لا يخصك المعرّف
يتم فحص كل معرّف id في المسار — معرّف رقم الهاتف، ومعرّف WABA، ومعرّف الوسائط — ومطابقته مع الحساب المرتبط بمفتاحك قبل حدوث أي شيء آخر. ويُرجع عدم التطابق الرمز 100 مصاغاً بالطريقة التي تصيغ بها Meta كائناً لا يمكنك رؤيته:
طلب POST غير مدعوم. الكائن ذو المعرّف «…» غير موجود، أو لا يمكن تحميله بسبب أذونات مفقودة، أو لا يدعم هذه العملية.
تلك الصياغة مقصودة من جانب Meta ومستنسخة هنا عمداً: إذ يجب ألا يكون هناك أي تمييز بين معرّف موجود لكنه يخص شخصاً آخر ومعرّف غير موجود على الإطلاق، وإلا لأصبح الخطأ وسيلة لاكتشاف أرقام هواتف الآخرين.
الوسائط
أربع نقاط نهاية، مطابقة لنقاط نهاية Meta.
| الطريقة | المسار | ما تفعله |
|---|---|---|
POST | /{version}/{phone-number-id}/media | رفع ملف. متعدد الأجزاء (Multipart)، ويعيد {"id": "…"}. |
GET | /{version}/{media-id} | كائن البيانات الوصفية من Meta للملف. |
GET | /{version}/{media-id}/download | البايتات. |
DELETE | /{version}/{media-id} | حذفه، ويعيد {"success": true}. |
الفارق المقصود الوحيد
يعيد GET /{version}/{media-id} كائن البيانات الوصفية الخاص بـ Meta — messaging_product وmime_type وsha256 وfile_size وid — ولكن يشير url إلينا، لا إلى مضيف lookaside الخاص بـ Meta.
وكان لا بد من ذلك. فرابط URL لوسائط Meta لا يمكن جلبه إلا باستخدام رمز الأعمال المميز (business token) الخاص بحساب واتساب، والذي يستقر في جانبنا ولا يغادره أبداً. لذلك نمنحك رابط URL يمكنك جلبه: نقطة نهاية التنزيل الموضحة أعلاه، على المضيف ومقطع الإصدار نفسهما اللذين استدعيتهما، مع المصادقة باستخدام رمز bearer token نفسه الذي أرسلته بالفعل.
تتعامل تطبيقات العميل مع رابط URL هذا على أنه مبهم وتكتفي بإرسال طلب GET إليه باستخدام الرمز المميز الخاص بها، ولهذا السبب لا تلاحظ أي SDK غير معدلة ذلك. وإذا كانت شفرتك البرمجية تخصص معالجة استثنائية لاسم المضيف، فهذا هو الموضع الوحيد الذي سيحتاج إلى تعديل.
الأذونات
شرائح الأذونات نفسها المستخدمة في WizMessage API، على المفاتيح ذاتها. ويعتمد الموضع الذي يُقرأ منه الإذن على الاستدعاء: فنقطة نهاية الإرسال تشتقه من نص الطلب، لأن Meta تضع جميع أنواع الرسائل على مسار واحد؛ وفي كل مكان آخر يأتي من المسار والطريقة.
الإرسال والوسائط:
| الاستدعاء | الإذن |
|---|---|
POST /{v}/{pnid}/messages مع "type": "template" | send_template |
الأمر نفسه، مع type لكل من image أو video أو audio أو document أو sticker | send_media |
| الأمر نفسه، مع أي شيء آخر — text، أو interactive، أو reaction، أو location، أو contacts، وتحديد كمقروء (mark-as-read) | send_text |
POST /{v}/{pnid}/media — الرفع | send_media |
DELETE /{v}/{media-id} | send_media |
GET /{v}/{media-id} و/download | view_messages |
إدارة الحساب — راجع إدارة الحساب:
| الاستدعاء | الإذن |
|---|---|
GET /{v}/{waba-id}/message_templates | view_templates |
POST وDELETE /{v}/{waba-id}/message_templates | manage_templates |
GET /{v}/{waba-id}/template_analytics | view_analytics |
GET لملف النشاط التجاري، ورموز QR، وإعدادات التجارة، وقائمة الحظر، وإعدادات الهاتف، والتدفقات (flows) | view_templates |
POST لهذه العناصر الستة نفسها | manage_profile |
DELETE /{v}/{pnid}/message_qrdls/{code} وDELETE /{v}/{pnid}/block_users | manage_profile |
هذان هما طلبا DELETE الوحيدان في جانب الإدارة. فلا يوجد حذف لملف النشاط التجاري، أو إعدادات التجارة، أو إعدادات الهاتف، أو التدفقات — ويُرفض أي طلب DELETE موجه إلى أي منها بالرمز code 100، تماماً كنقطة نهاية غير موجودة.
ملاحظة: يتطلب رفع الوسائط إذن
send_mediaهنا. بينما لا يتطلب أي إذن على الإطلاق في WizMessage API، انطلاقاً من مبدأ أنsend_mediaيتحكم في إرسال ملف إلى عميل بدلاً من وضعه على خوادم Meta. وتتخذ هذه الواجهة المسار الأكثر صرامة. فإذا كنت تنقل مفتاحاً وبدأت عمليات الرفع تُرجع403، فهذا هو السبب.
ملاحظة: يتحكم
view_templatesفي أكثر بكثير من مجرد القوالب. فقراءة ملف النشاط التجاري، ورموز QR، وإعدادات التجارة، وقائمة الحظر، وإعدادات الهاتف، والتدفقات تقع جميعها خلفه. والتسمية تاريخية — إذ تسبق كل ما هو موجود في الجدول الثاني. وإذا ألغيت تحديده أثناء تضييق نطاق مفتاح، فستبدأ ست عمليات قراءة لا علاقة لها بالأمر بإرجاع403مصحوبة برسالة عن القوالب، وهو ليس تلميحاً مفيداً.
ملاحظة: ثلاث شرائح مخصصة لـ Meta Graph فقط. فـ
manage_templatesوmanage_profileوview_analyticsلا تحجب أي شيء على WizMessage API — بل هي موجودة لنقاط النهاية في هذه الصفحة. وقد مُنح كل مفتاح كان موجوداً بالفعل هذه الأذونات الثلاثة، لذا لم يتوقف أي شيء كان يعمل؛ والتضييق يتطلب إلغاء التحديد عمداً في نموذج تعديل المفتاح.
يأتي الرفض كرمز Graph code 10 مع 403 — وليس الرمز PERMISSION_DENIED الخاص بنا إطلاقاً. وبذلك يغطي معالج أخطاء واحد هذه الواجهة بالكامل.
يتم التحقق من الملكية قبل الإذن. فإذا لم يكن المعرّف id الموجود في المسار هو المعرّف المرتبط بمفتاحك، تكون الإجابة هي code 100 دون أن تكشف أبداً عن الإذن الذي كان ينقصك — وإلا لأصبح الخطأ نفسه وسيلة لاستكشاف حسابات الآخرين.
إدارة الحساب
إلى جانب الإرسال، تتضمن هذه الواجهة نقاط نهاية إدارة الحساب الخاصة بـ Meta في مسارات Meta نفسها. ثمانية موارد، ويعتمد الإذن الذي تحتاجه على ما إذا كنت تقرأ أو تكتب.
تنطبق ثلاثة أمور على كل نقطة نهاية في هذا القسم، وهي السبب الأساسي في إمكانية وجودها أصلاً:
- جسم الطلب خاص بـ Meta نفسها، ويُمرَّر دون تغيير ودون تحقق من صحته. نحن لا نعيد توثيق أجسام طلبات Meta هنا ولا نتحقق منها. ويُعد مرجع Meta هو المواصفة القياسية، وخطأ Meta هو ما يُعاد إليك إذا أخطأت في أحدها — وهو خطأ أفضل من أي خطأ قد نبتكره.
- يُرسَل جسم الطلب مع
POSTفقط. يتم إسقاط أي جسم مرفق بـDELETEقبل أن يغادر الطلب من عندنا. يتطلب حذف القوالب لدى Meta استخدام?name=أو?hsm_id=كمعلمات استعلام، وليس كجسم طلب، ولذا فهو يعمل كما هو موثق؛ أما أي شيء آخر يتوقع جسماً مع طلب الحذف فلن يعمل. - تُمرَّر سلسلة الاستعلام الخاصة بك، باستثناء
access_tokenوappsecret_proof. يتم تجريد هذين الاثنين، لأن Meta تعطي الأولوية لرمز سلسلة الاستعلام على ترويسةAuthorization، وتمريرهما سيجعل رمز bearer لديك اختيارياً. وأي عميل يقوم بالمصادقة عبر سلسلة الاستعلام سيجد أنها تُتجاهل بصمت — استخدم الترويسة.
ملاحظة: يجب أن يكون معرّف WABA ومعرّف رقم الهاتف في هذه المسارات هما المرتبطين بمفتاحك. يتم التحقق من ذلك قبل أن يغادر أي شيء شبكتنا، ويعيد عدم التطابق نفس
code 100الموضّح في عندما لا يكون المعرّف ملكاً لك.
ملاحظة: يشير
paging.nextإلى Meta، وليس إلينا. تُعاد الاستجابات تماماً كما أرسلتها Meta، لذا فإن رابطnextفي الاستجابة المقسمة إلى صفحات هو عنوان URL لـgraph.facebook.com— ومفتاح API الخاص بك لا يوثّق الهوية هناك. تنقّل بين الصفحات بأخذpaging.cursors.afterوإعادة إرسال الطلب إلى هذا المضيف مع?after=.
القوالب
GET https://wizmessage.com/v26.0/{waba-id}/message_templates?limit=25
POST https://wizmessage.com/v26.0/{waba-id}/message_templates
DELETE https://wizmessage.com/v26.0/{waba-id}/message_templates?name=order_shipped
| الطريقة | الإذن | ما يُعاد |
|---|---|---|
GET | view_templates | { data, paging } الخاصة بـ Meta |
POST | manage_templates | استجابة الإنشاء من Meta |
DELETE | manage_templates | استجابة الحذف من Meta |
يقبل GET المعلمة limit (1–100، القيمة الافتراضية 25) وafter للتقسيم إلى صفحات بالمؤشر.
ملاحظة: يقبل
GETالمعلمتينlimitوafterفقط. أما فلاتر Meta الأخرى على هذا المسار —nameوstatusوfieldsوlanguageوcategoryوname_or_content— فيتم تجاهلها بصمت دون رفضها. وأي طلب لـ?status=APPROVEDيعيد الرمز200حاملاً كل القوالب، سواء كانت معتمدة أم لا. قم بالتصفية من جانبك، أو استخدمafterللتنقل عبر القائمة الكاملة. هذا هو الموضع الوحيد في هذه الصفحة الذي يتلقى فيه العميل المنقول إجابة خاطئة بدلاً من ظهور خطأ، لذا يجدر بك مراجعة شفرتك البرمجية للتأكد من ذلك.
تحليلات القوالب
GET https://wizmessage.com/v26.0/{waba-id}/template_analytics
يتطلب view_analytics. تطلب Meta المعلمة start، وتعيد code 100 — «(#100) The parameter start is required» — بدونها. أما granularity وبقية المعلمات فهي خاصة بـ Meta؛ مررها وستصل كما هي دون تغيير.
الملف التعريفي التجاري
GET https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_business_profile?fields=about,address,description,email,profile_picture_url,websites,vertical
POST https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_business_profile
يتطلب GET الإذن view_templates ويعيد { data } الخاصة بـ Meta. ويتطلب POST الإذن manage_profile.
رموز QR
GET https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls
POST https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls
DELETE https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls/{code}
يتطلب GET الإذن view_templates ويعيد { data } الخاصة بـ Meta. ويتطلب كل من POST وDELETE الإذن manage_profile.
المسار /{code} مخصص لـ DELETE فقط. لا يوجد GET أو POST لرمز فردي — اقرأ المجموعة واختر منها.
إعدادات التجارة
GET https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_commerce_settings
POST https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_commerce_settings
يتطلب GET الإذن view_templates ويعيد { data } الخاصة بـ Meta. ويتطلب POST الإذن manage_profile.
العملاء المحظورون
GET https://wizmessage.com/v26.0/{phone-number-id}/block_users
POST https://wizmessage.com/v26.0/{phone-number-id}/block_users
DELETE https://wizmessage.com/v26.0/{phone-number-id}/block_users
يتطلب GET الإذن view_templates ويعيد { data } الخاصة بـ Meta. ويتطلب كل من POST وDELETE الإذن manage_profile. لاحظ أن إلغاء الحظر هو طلب DELETE للمجموعة نفسها، وليس لمسار خاص بكل عميل.
إعدادات رقم الهاتف
GET https://wizmessage.com/v26.0/{phone-number-id}/settings
POST https://wizmessage.com/v26.0/{phone-number-id}/settings
يتطلب GET الإذن view_templates ويعيد { calling, storage_configuration }. ويتطلب POST الإذن manage_profile.
ملاحظة: المسار هو
/settings. تسمي بعض مراجع API التابعة لجهات خارجية هذا المسارwhatsapp_calling_settings— هذا المسار غير موجود لدى Meta ويعيدcode 2500هنا، لأننا نمرره وترفضه Meta. راجع ما لا يتوفر هنا.
التدفقات
GET https://wizmessage.com/v26.0/{waba-id}/flows
POST https://wizmessage.com/v26.0/{waba-id}/flows
يتطلب GET الإذن view_templates ويعيد { data, paging } الخاصة بـ Meta. ويتطلب POST الإذن manage_profile.
ما لا يتوفر هنا
تم تأكيد كل ما سبق مقابل حساب واتساب مباشر. وكذلك كل ما يرد أدناه — ولهذا السبب يستطيع هذا القسم إخبارك لماذا تكون نقطة النهاية مفقودة، وهذا عادةً ما يحدد خطوتك التالية.
ما تُرجعه نقطة النهاية غير المتوفرة. أي شيء ليس في القائمة أعلاه يُجيب بصياغة Meta الخاصة لمسار لن تخدمه — code 100 عند 400:
طلب get غير مدعوم. الكائن ذو المعرّف '…' غير موجود، أو لا يمكن تحميله بسبب أذونات مفقودة، أو لا يدعم هذه العملية.
أما المسار المدعوم بالفعل ولكن يُستدعى بطريقة لا يوفرها، فيُرجع الرمز نفسه مع رسالة أقصر: «طلب delete غير مدعوم.» وكلاهما لا يمكن تمييزه عمداً عن كائن لا يمكنك ببساطة رؤيته — فالخطأ الذي يؤكد أي نقاط النهاية موجودة سيكون وسيلة لرسم خريطة لهذه الواجهة.
مرفوضة عمداً
تُحظر هذه المسارات مع كل طريقة، قبل إعادة توجيه أي شيء:
| المسار | السبب |
|---|---|
register, deregister, request_code, verify_code | يجب ألا يُسجَّل رقم التعايش على Cloud API على الإطلاق. فالقيام بذلك هو بالتحديد ما يجعل الحساب ينتهي به المطاف إلى الفشل في كل عملية إرسال مع الخطأ 133010، ولا يمكن التراجع عن ذلك من جانبك. |
subscribed_apps | كافة الطرق، بما في ذلك GET. سيؤدي طلب DELETE هنا إلى إلغاء اشتراك الخطافات (webhooks) الخاصة بنا من حساب واتساب الخاص بك وتعطيل تكاملك بصمت؛ كما أننا لا نوفر القراءة أيضاً، بدلاً من ترك مسار قد تتسبب فيه هفوة واحدة في حدوث ذلك. |
marketing_messages | تمر عمليات الإرسال التسويقية عبر أدوات الحملات في لوحة التحكم، والتي تفرض معدل الإرسال الخاص بكل حساب. |
/{template-id}/unpause | تُحدد Meta القالب بواسطة معرّف مجرد دون وجود حساب في المسار، لذا لا يمكننا إثبات أن القالب يخصك قبل التصرف بناءً عليه. ألغِ إيقافه المؤقت من لوحة التحكم. |
messages مع أي طريقة باستثناء POST | يحمل مسار الإرسال محدد المعدل ومعالجة تعليق الحساب. ويتم توجيه POST فقط. |
غير متوفرة على رقم تعايش
إجابات Meta نفسها، تم فحصها مقابل حساب مباشر في 10 أغسطس 2026:
| المسار | إجابة Meta |
|---|---|
/{phone-number-id}/conversational_automation | code 100 — «تمت محاولة الوصول إلى حقل غير موجود» |
/{phone-number-id}/calls | code 100 — «تمت محاولة الوصول إلى حقل غير موجود» |
/{phone-number-id}/groups | code 131000 عند 500 |
هذه قيود تفرضها Meta على الأرقام التي تعمل في وضع التعايش مع تطبيق WhatsApp Business، وليست قيوداً من طرفنا — فنحن نعيد توجيه الطلب وهذا ما يصلنا في الرد. وتُوسّع Meta نطاق التوفر من حين لآخر، لذا إذا كان أحد هذه المسارات يهمك، فيجدر بك إعادة اختباره بدلاً من الاعتماد على هذا الجدول إلى ما لا نهاية.
مسارات غير موجودة في أي مكان
يظهر كل مسار من هذه المسارات في مراجع API تابعة لجهات خارجية وليس نقطة نهاية تابعة لـ Meta. وتُرجع المسارات الأربعة جميعها code 2500، «مكونات مسار غير معروفة»:
| ما قد تكون قرأته | ما يجب استخدامه بدلاً من ذلك |
|---|---|
POST /{phone-number-id}/mark_message_as_read | POST /{phone-number-id}/messages مع جسم طلب يتضمن status: "read" — انظر تمييز الرسالة كمقروءة |
GET /{phone-number-id}/message_status | تصل حالات التسليم على خطاف الويب (webhook) الخاص بك؛ انظر اختيار ما تتلقاه |
/{phone-number-id}/whatsapp_calling_settings | /{phone-number-id}/settings |
/{phone-number-id}/conversational_components | لا شيء — أقرب مسار حقيقي هو conversational_automation، وهو غير متوفر على رقم تعايش |
حقيقية لدى Meta، وليست في قائمتنا
يعمل المسار GET /{waba-id}/phone_numbers لدى Meta ولا يتم حظره أو إعادة توجيهه هنا، لذا فإنه يجيب بـ code 100. وهو من أولى نقاط النهاية التي يستدعيها عميل Cloud API، لذا يجدر ذكره: فمفتاحك يثبّت بالفعل رقماً هاتفياً واحداً بالضبط، ومعرّفه هو المعرّف الذي تضعه في كل مسار في هذه الصفحة. ويمكنك قراءته من تبويب «نظرة عامة» الخاص بالمفتاح في لوحة التحكم.
قراءات العقدة المجردة
يعمل المساران GET /{v}/{waba-id}?fields=… وGET /{v}/{phone-number-id}?fields=… لدى Meta ولكن ليس هنا. فالمسار أحادي المقطع على هذه الواجهة هو معرّف وسائط — وهذا هو ما يعنيه GET /{v}/{media-id} — ولذا يتم البحث عن معرّف WABA في ذلك الموضع كوسائط ويفشل.
ويكون هذا الفشل مربكاً إذا لم تكن تتوقعه: فهو يتحقق من view_messages أولاً، لذا يتلقى المفتاح الذي لا يملك هذا الإذن رمزَ 403 يذكر إذناً لا علاقة له بما طُلب. استخدم صيغ الحواف بدلاً من ذلك — /{waba-id}/message_templates، و/{phone-number-id}/settings، وبقية إدارة الحساب.
خطافات الويب بتنسيق Meta
يُفتح تبويب خطافات الويب في لوحة التحكم على خيار لتنسيق الحمولة. WizMessage (v1) هو تنسيق الحمولة الذي توثقه الصفحة الأخرى؛ وهو ما يستخدمه المفتاح ما لم تقم بتغييره.

اختر Meta Graph وستتوقف نقطة النهاية لديك عن استلام حمولة {version, event, timestamp, data} الخاصة بنا وتبدأ في استلام المغلف الذي أرسلته Meta إلينا، مُعاداً توجيهه حرفياً — تسليم واحد لكل تغيير.
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"time": 1770000123,
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [{ "profile": { "name": "Priya Sharma" }, "wa_id": "919876543210" }],
"messages": [
{
"from": "919876543210",
"id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAEhgg…",
"timestamp": "1770000123",
"type": "text",
"text": { "body": "Has it shipped yet?" }
}
]
},
"field": "messages"
}
]
}
]
}
إذا كان لديك بالفعل معالج لخطافات ويب Cloud API، فهذا هو الشكل الذي صُمم لاستقباله.
كما يؤدي تبديل التنسيق إلى تغيير ما يطلبه منك التبويب: حيث تُستبدل خانات اختيار الأحداث بأسماء حقول Meta الخاصة، ويظهر حقل لرمز التحقق (verify token).

قبل أن تتمكن من حفظ أحدها
يلزم توفر ثلاثة أمور، وستخبرك لوحة التحكم بأي منها مفقود:
- سر خطاف الويب (Webhook secret). هو العنصر الوحيد الذي يُبنى عليه توقيع
X-Hub-Signature-256، وبدونه سيكون التسليم غير موقّع ويتعذر التحقق منه. أنشئ واحداً من تبويب Webhooks الخاص بالمفتاح. - رمز تحقق (Verify token). أي سلسلة نصية تختارها؛ ويجب أن تكون نقطة النهاية لديك على علم بها أيضاً.
- عنوان URL يستجيب بالفعل. انظر أدناه.
مصافحة التحقق
عندما تحفظ، نستدعي عنوان URL الخاص بك تماماً كما تفعل Meta:
GET https://your-server.example/webhooks
?hub.mode=subscribe
&hub.verify_token=<the token you set>
&hub.challenge=482910337
يجب على نقطة النهاية لديك التحقق من أن hub.verify_token يطابق ما قمت بضبطه، ثم الرد برمز 200 مع جعل hub.challenge هو كامل نص الاستجابة — دون تغليف بـ JSON، ودون علامات اقتباس، ودون أي شيء آخر. والتحدي هو رقم مكوّن من 9 خانات، لذا فإن أي معالج يُجري parseInt قبل إرجاع القيمة سيعيدها دون أي تغيير.
إذا لم يُعَد التحدي كما هو تماماً، يُرفض الحفظ ولا يتم تخزين أي شيء. وهذا ما يمنع أي شخص من توجيه قائمة انتظار التسليم لدينا إلى عنوان URL لا يتحكم فيه.
// express
app.get('/webhooks', (req, res) => {
if (req.query['hub.mode'] === 'subscribe' && req.query['hub.verify_token'] === VERIFY_TOKEN) {
return res.status(200).send(req.query['hub.challenge'])
}
res.sendStatus(403)
})
التحقق من التوقيع
يحمل كل تسليم الترويسة X-Hub-Signature-256، المحسوبة بالطريقة نفسها التي تحسبها بها Meta: تشفير HMAC-SHA256 لـ نص الطلب الخام، بالاعتماد على سر خطاف الويب الخاص بك كمفتاح، بترميز سداسي عشري (hex)، مسبوقاً بـ sha256=.
| الترويسة | القيمة |
|---|---|
X-Hub-Signature-256 | sha256= + تشفير HMAC-SHA256 لنص الطلب الخام، بمفتاح سر خطاف الويب الخاص بك، بأحرف سداسية عشرية صغيرة. |
X-Webhook-Event | meta.<field> — الحقل الذي يحمله هذا التسليم. |
X-Webhook-Id | معرّف فريد لمحاولة التسليم هذه. يُستخدم لمنع التكرار. |
User-Agent | facebookplatform/1.0 (+http://developers.facebook.com) |
ملاحظة: طريقة الاشتقاق هذه ليست نفسها المستخدمة في تنسيق WizMessage. إذ يوقّع ذاك
timestamp + "." + rawBodyويرسل الطابع الزمني في ترويسة خاصة به؛ بينما يوقّع هذا التنسيق نص الطلب بمفرده، دون تضمين طابع زمني في أي مكان. إذا كنت تشغّل كلا التنسيقين على خادم واحد، فاجعل أداتي التحقق منفصلتين — فالمحقّق المشترك سيفشل مع التنسيق الذي لم يُكتب من أجله.
وقّع البايتات الخام كما تم استلامها. فتحليل الـ JSON وإعادة تسلسله يغيّران ترتيب المفاتيح والمسافات، ولن يتطابق التوقيع أبداً.
const crypto = require('node:crypto')
// express: app.post('/webhooks', express.raw({ type: 'application/json' }), ...)
function verify(req) {
const provided = req.get('X-Hub-Signature-256') || ''
if (!provided.startsWith('sha256=')) return false
const expected = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(req.body) // the raw Buffer, not a parsed object
.digest('hex')
// Constant-time compare — a plain === leaks timing information.
const a = Buffer.from(expected, 'hex')
const b = Buffer.from(provided.slice('sha256='.length), 'hex')
return a.length === b.length && crypto.timingSafeEqual(a, b)
}
اختيار ما تتلقاه
يتطلب منك تنسيق WizMessage تحديد الأحداث باختيارها. بينما يتطلب منك هذا التنسيق تحديد أسماء حقول Meta، بما يطابق ما تشترك فيه داخل App Dashboard الخاصة بـ Meta نفسها.
| الحقل | ما الذي يصل |
|---|---|
messages | الرسائل الواردة وحالات التسليم. اقرأ الملاحظة أدناه. |
message_status | حالات التسليم، كحقل مستقل بذاته. |
smb_message_echoes | الرسائل التي أرسلها النشاط التجاري من تطبيق WhatsApp Business على هاتفه. |
smb_app_state_sync | تغييرات دفتر العناوين التي أُجريت على ذلك الهاتف. |
user_id_update | تغيّر هوية جهة الاتصال على واتساب. |
message_template_status_update | تمت الموافقة على قالب أو تم رفضه أو إيقافه مؤقتاً. |
message_template_quality_update | تغيّرت نقاط جودة القالب. |
account_update | تم ربط حساب واتساب أو فصله أو تقييده أو إلغاء إعداده (offboarded). |
history | المحادثات السابقة، أثناء المزامنة الأولية. حمولات بيانات كبيرة — لا تشترك فيها إلا إذا كنت بحاجة إليها. |
تبدأ خطافات الويب الجديدة لـ Graph بالاشتراك في messages وحدها. ويؤدي إلغاء تحديد كافة الحقول إلى إيقاف عمليات التسليم دون حذف الإعدادات.
ملاحظة: يحمل حقل
messagesبالفعل حالات التسليم. ترسل Meta كلاً منهما تحت"field": "messages"— الرسائل الواردة في مصفوفةmessages، وتقارير التسليم في مصفوفةstatusesضمن كائن القيمة نفسه. لذا، يكفي الاشتراك الافتراضي لربط معرّفwamidالذي تلقيته من عملية الإرسال. أماmessage_statusفهو حقل إضافي، وليس هو الحقل الذي تحتاجه للتتبع الأساسي للحالة. اقرأvalue.statusesقبل أن تفترض أن هناك اشتراكاً ناقصاً لديك.
ثلاثة أمور تختلف عن تنسيق WizMessage
يجدر بك الاطلاع عليها إذا كنت تنقل عملية تكامل، لأن كلاً منها يُغيّر ما يظهر لك دون إشعار مباشر.
- التسليم غير مشروط بنظام روبوت المحادثة. في تنسيق WizMessage، لا تصل الرسائل الواردة إلى نقطة النهاية لديك إلا عندما يكون نظام روبوت المحادثة للحساب مضبوطاً على Webhook. أما تنسيق Graph فيتجاهل هذا الإعداد تماماً — فتهيئة عنوان URL والاشتراك في أحد الحقول هما كل ما يلزم للاشتراك.
- تتلقى
status: "sent"وحالات الحملات. يتجاهل تنسيق WizMessage كلاً منهما عمداً. أما هنا فستتلقى كل ما أرسلته Meta، ما يعني حركة بيانات أكبر لحالات الرسائل على الحسابات التي تشغّل حملات جماعية. - لا يوجد حدث
message.sentمصطنع. ينشئ تنسيق WizMessage حدثاً مصطنعاً للرسائل المرسلة من واجهة برمجة التطبيقات (API) أو لوحة التحكم أو الهاتف. وتغطي Meta المجال نفسه باستخدامsmb_message_echoesوحالةsent، لذا لا يتم اختلاق أي شيء هنا.
التسليم وإعادة المحاولة وإيقاف التشغيل
مطابق لتنسيق WizMessage — ينطبق الجدول نفسه. باختصار: ننتظر 10 ثوانٍ، ولا نتبع عمليات إعادة التوجيه أبداً، ونعيد محاولة رموز 5xx/408/429/انتهاء المهلة 5 مرات مع تراجع تدريجي، ولا نعيد المحاولة مطلقاً مع رموز 4xx الأخرى، ونتعامل مع 410 Gone على أنه «إيقاف تشغيل خطاف الويب هذا».
تتم عمليات التسليم مرة واحدة على الأقل. امنع التكرار بناءً على X-Webhook-Id، ورُدّ برمز 2xx سريعاً.
التجربة دون كتابة تعليمات برمجية
يحتوي مربع حوار اختبار API الخاص بالمفتاح على عنصر تحكم صيغة API. اضبطه على Meta Graph وسيُستبدل بأداة اختيار نقطة النهاية الهدفُ الفعلي لحسابك — POST /v26.0/{your phone number id}/messages — مع جسم طلب مُعبّأ مسبقاً وفق بنية Meta.

يعيد خيار «محاكاة فقط» الطلب إليك دون الاتصال بـ Meta؛ أما التبديل إلى «إرسال رسالة حقيقية» فيرسله ويُظهر لك استجابة Meta الفعلية، بغلاف الخطأ وكل تفاصيله.
يستهدف مربع الحوار POST /{phone-number-id}/messages دون سواه، لذا لا يمكن الوصول إلى نقاط نهاية إدارة الحساب من خلاله — فجرّبها باستخدام curl أو عبر عميلك الخاص.
يتضمن الحصول على الكود عنصر التحكم نفسه، وبذلك تستهدف القصاصة البرمجية المُنشأة أي واجهة تختارها، بأيٍّ من اللغات الثماني. اترك خيار «طلب التوقيع» غير مفعّل في أي مفتاح تنوي استخدامه هنا — فعند تفعيله، تقوم قصاصة Graph المُنشأة بتوقيع الطلب أيضاً، وهو الأمر الوحيد الذي لا يستطيع عميل Cloud API غير المعدَّل القيام به.