تخطٍ إلى المحتوى
29 min read

الاتصال عبر Meta Graph API

وجّه تكاملاً حالياً لـ WhatsApp Cloud API إلى WizMessage دون إعادة كتابته — مسارات Meta، ونصوص طلبات Meta، وغلاف أخطاء Meta، والخطافات (webhooks) بتنسيق Meta نفسه، ونقاط نهاية إدارة الحساب للقوالب والملف التجاري ورموز QR والتدفقات.

الاتصال عبر Meta Graph API

هناك طريقتان لإرسال رسائل واتساب عبر WizMessage. وتعد WizMessage API الخيار الأنسب إذا كنت تبدأ من الصفر — فهي تمنحك متغيرات قوالب مسماة، وواجهة مستخدم لربط الحقول، وحقل reference يمكنك ربط سجلاتك به.

توثق هذه الصفحة الطريقة الأخرى. فهي تحاكي WhatsApp Cloud API التابعة لـ Meta بدقة تكفي لأن يعمل الكود المكتوب مسبقاً لـ Meta هنا بعد تغيير أمرين اثنين: عنوان URL الأساسي والرمز المميز (token). المسارات نفسها، ونصوص الطلبات نفسها، ونصوص الاستجابات نفسها، وغلاف الأخطاء نفسه. وإذا كان لديك تكامل حالي، أو مكتبة برمجية، أو مطور يعرف بالفعل Cloud API، فهذا هو الطريق الأقصر.

وهي ليست مجرد واجهة للإرسال؛ فإلى جانب المراسلة، توفر نقاط نهاية إدارة الحساب — إنشاء القوالب وحذفها، وقراءة الملف التجاري وإعادة كتابته، ورموز QR، وإعدادات التجارة، وقائمة الحظر، وإعدادات الهاتف والتدفقات — وكلها عبر مسارات Meta نفسها. إدارة الحساب هي الفهرس الشامل، وما لا يتوفر هنا هو النصف الآخر الذي لا يقل أهمية.

تستخدم كلتا الواجهتين مفاتيح API نفسها، والأذونات نفسها، وحدود المعدل نفسها. لا شيء متوقف أو مهمل — اختر ما يناسب كل تكامل، ويمكنك استخدام كلتيهما معاً في الوقت ذاته.

أيهما تريد

مقارنة بين WizMessage API وواجهة Meta Graph المتوافقةاختر الواجهة التي تناسب ما لديك بالفعلWizMessage API/api/v1/externalمتغيرات قوالب مسماةواجهة لربط الحقول في لوحة التحكمحقل reference، واستعلام عن الحالةغلاف JSON خاص بناالأفضل عند البدء من الصفرMeta Graph API/v26.0/{phone-number-id}/…نصوص طلبات Metaغلاف أخطاء Metaإدارة القوالب والملف التجاريالخطافات (webhooks) بتنسيق Metaالأفضل عند توفر كود لـ Cloud 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.

الترويسةالقيمة
AuthorizationBearer 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-WarningSubscription 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 بعد انتهاء صلاحية الاشتراكمفتاح API واحدعاديلا ترويسةمهلة سماح7 أيام، تستمر الاستدعاءات بالنجاحX-Subscription-Warning مع كل استجابةمرفوضالرمز 10 مع 403أول استدعاء بعد انتهاء الصلاحيةيبدأ احتساب الوقت هناانتهاء المهلةلا تحذير إضافيالتجديد في أي وقت يعيد الوصول خلال بضع دقائق.
انتهاء الصلاحية في حد ذاته لا يغير شيئاً. يبدأ احتساب الوقت عند استدعائك التالي.

ثلاثة تفاصيل تحدد ما إذا كنت ستنتبه في الوقت المناسب:

  • يبدأ احتساب الوقت عند أول استدعاء تجريه، وليس في تاريخ الفاتورة. فالمفتاح الذي يظل خاملاً لمدة أسبوعين بعد انتهاء الصلاحية يحصل على أيامه السبعة كاملة، بدءاً من موعد استدعائه التالي.
  • المهلة لكل مفتاح 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، لا في مظروفنا أبداً. ومصدر الخطأ هو ما يحدد مقدار ما يخصنا منه.

كيف يصلك الخطأ اعتماداً على ما إذا كانت Meta قد أصدرتهخطأ في هذه الواجهةرفضته Metaتُمرَّر حرفياًرمز Meta ورمزها الفرعيمعرّف fbtrace_id الخاص بـ Metaالحالة تتبع Meta أيضاًنحن رفضناهالمصادقة، الإذن، حد المعدلمكتوبة برموز Metaليغطي معالج واحد كليهما401 · 403 · 429 · 400 · 500لا تفترض أبداً أن type هو OAuthException — فـ Meta تستخدم أنواعاً متعددة.
تُمرَّر أخطاء Meta نفسها دون أي تعديل. وأخطاؤنا تستعير رموز Meta.

الأخطاء التي نثيرها

codeHTTPمتى
190401مفتاح مفقود أو غير معروف أو ملغى أو معلق أو منتهي الصلاحية — أو استدعاء غير موقّع لمفتاح يتطلب توقيعات. يُثار أيضاً عندما يفقد حساب واتساب نفسه اتصاله بـ Meta؛ راجع الملاحظة أدناه.
10403المفتاح يفتقر إلى الإذن الذي يتطلبه هذا الاستدعاء (راجع الأذونات)، أو أن اشتراك الحساب قد انتهت صلاحيته وتجاوز فترة السماح الخاصة به.
4429استُنفد الحد المسموح به للمفتاح في الدقيقة أو اليوم.
100400طلب مشوّه الصياغة، أو معرّف id في المسار لا يخصك، أو نقطة نهاية لا تخدمها هذه الواجهة.
2500حدث خطأ ما من جانبنا. أعد المحاولة.

ملاحظة: أمران مختلفان يُرجِعان 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}.
رفع ملف مرة واحدة وإرساله مراراً وتكراراًPOST /{v}/{pnid}/mediaالملف نفسه{ id }قابل لإعادة الاستخدامPOST /{v}/{pnid}/messagesالإشارة إلى المعرّفتم التسليمتصل الحالات عبر webhook
يعيد الرفع معرّف id. وهذا المعرّف هو ما تضعه في الرسالة.

الفارق المقصود الوحيد

يعيد 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 أو stickersend_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} و/downloadview_messages

إدارة الحساب — راجع إدارة الحساب:

الاستدعاءالإذن
GET /{v}/{waba-id}/message_templatesview_templates
POST وDELETE /{v}/{waba-id}/message_templatesmanage_templates
GET /{v}/{waba-id}/template_analyticsview_analytics
GET لملف النشاط التجاري، ورموز QR، وإعدادات التجارة، وقائمة الحظر، وإعدادات الهاتف، والتدفقات (flows)view_templates
POST لهذه العناصر الستة نفسهاmanage_profile
DELETE /{v}/{pnid}/message_qrdls/{code} وDELETE /{v}/{pnid}/block_usersmanage_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 نفسها. ثمانية موارد، ويعتمد الإذن الذي تحتاجه على ما إذا كنت تقرأ أو تكتب.

نقاط نهاية إدارة الحساب مجمعة حسب الإذن الذي تحتاجه كل منهاقراءة أي شيءالموارد الثمانية كلهاالملف التعريفي، ورموز QR، والتجارةقائمة الحظر، والإعدادات، والتدفقاتالقوالبview_templatesكتابة الحسابالملف التعريفي والظهورالملف التعريفي التجاري، ورموز QRالتجارة، وقائمة الحظرالإعدادات، والتدفقاتmanage_profileكتابة القوالبالإنشاء والحذفmessage_templatesالتحليلات منفصلةmanage_templatesلتحليلات القوالب شريحتها الخاصة: view_analytics.
القراءة شريحة واحدة. أما الكتابة فتنقسم بحسب ما تكتبه.

تنطبق ثلاثة أمور على كل نقطة نهاية في هذا القسم، وهي السبب الأساسي في إمكانية وجودها أصلاً:

  • جسم الطلب خاص بـ 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
الطريقةالإذنما يُعاد
GETview_templates{ data, paging } الخاصة بـ Meta
POSTmanage_templatesاستجابة الإنشاء من Meta
DELETEmanage_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 غير مدعوم.» وكلاهما لا يمكن تمييزه عمداً عن كائن لا يمكنك ببساطة رؤيته — فالخطأ الذي يؤكد أي نقاط النهاية موجودة سيكون وسيلة لرسم خريطة لهذه الواجهة.

لماذا قد لا تتوفر نقطة نهاية على هذه الواجهةنقطة نهاية ليست موجودة هنانحن نرفضهاregistration, subscribed_appsسيعطل حسابكلا يوجد حل بديلMeta ترفضهاليست على رقم تعايشconversational_automation, callsإجابة Meta نفسهاإنها غير موجودةأربعة مسارات من نسخ API المتطابقةMeta تجيب بـ code 2500استخدم المسار الحقيقيهناك مجموعة رابعة ليست في قائمتنا بعد ببساطة — انظر أدناه.
أربعة أسباب، وواحد منها فقط من طرفنا.

مرفوضة عمداً

تُحظر هذه المسارات مع كل طريقة، قبل إعادة توجيه أي شيء:

المسارالسبب
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_automationcode 100 — «تمت محاولة الوصول إلى حقل غير موجود»
/{phone-number-id}/callscode 100 — «تمت محاولة الوصول إلى حقل غير موجود»
/{phone-number-id}/groupscode 131000 عند 500

هذه قيود تفرضها Meta على الأرقام التي تعمل في وضع التعايش مع تطبيق WhatsApp Business، وليست قيوداً من طرفنا — فنحن نعيد توجيه الطلب وهذا ما يصلنا في الرد. وتُوسّع Meta نطاق التوفر من حين لآخر، لذا إذا كان أحد هذه المسارات يهمك، فيجدر بك إعادة اختباره بدلاً من الاعتماد على هذا الجدول إلى ما لا نهاية.

مسارات غير موجودة في أي مكان

يظهر كل مسار من هذه المسارات في مراجع API تابعة لجهات خارجية وليس نقطة نهاية تابعة لـ Meta. وتُرجع المسارات الأربعة جميعها code 2500، «مكونات مسار غير معروفة»:

ما قد تكون قرأتهما يجب استخدامه بدلاً من ذلك
POST /{phone-number-id}/mark_message_as_readPOST /{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) هو تنسيق الحمولة الذي توثقه الصفحة الأخرى؛ وهو ما يستخدمه المفتاح ما لم تقم بتغييره.

تبويب خطافات الويب (Webhooks) مع ضبط تنسيق الحمولة على 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).

تبويب خطافات الويب (Webhooks) بتنسيق Meta Graph، مبيناً رمز التحقق وأسماء حقول Meta التسعة القابلة للاشتراك

قبل أن تتمكن من حفظ أحدها

يلزم توفر ثلاثة أمور، وستخبرك لوحة التحكم بأي منها مفقود:

ما يجب توفره قبل حفظ خطاف ويب بتنسيق Meta Graphسر خطاف الويبيُستخدم مفتاحاً للتوقيعرمز التحققيثبت ملكيتك للرابطعنوان URL نشطنستدعيه قبل الحفظتم الحفظتبدأ عمليات التسليملا يمكن حفظ عنوان URL لا يستجيب بعد. انشر أولاً، ثم قم بالإعداد.
يتم التحقق من الأمور الثلاثة جميعها عند الضغط على حفظ، بهذا الترتيب.
  • سر خطاف الويب (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-256sha256= + تشفير HMAC-SHA256 لنص الطلب الخام، بمفتاح سر خطاف الويب الخاص بك، بأحرف سداسية عشرية صغيرة.
X-Webhook-Eventmeta.<field> — الحقل الذي يحمله هذا التسليم.
X-Webhook-Idمعرّف فريد لمحاولة التسليم هذه. يُستخدم لمنع التكرار.
User-Agentfacebookplatform/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

يجدر بك الاطلاع عليها إذا كنت تنقل عملية تكامل، لأن كلاً منها يُغيّر ما يظهر لك دون إشعار مباشر.

ثلاثة سلوكيات تختلف بين تنسيقي خطافات الويبدون قيود من روبوت المحادثةيتم التسليم في الحالتينيتطلب v1 وضع الروبوت = Webhookيتجاهل Graph هذا الإعدادتصلك حالة sentوحالات الحملاتيقوم v1 بتصفية كليهمايُمرر Graph كل شيءلا يوجد sent مصطنعأحداث Meta الأصلية بدلاً منهsmb_message_echoesوالحالاتتوقّع حركة بيانات على تنسيق Graph أكبر مما كان ينتجه الحساب نفسه على v1.
تؤدي جميعها إلى جعل تنسيق Graph يرسل المزيد، وليس الأقل.
  • التسليم غير مشروط بنظام روبوت المحادثة. في تنسيق 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.

مربع حوار اختبار API في وضع Meta Graph، يعرض نقطة نهاية الرسائل للقراءة فقط وجسم طلب وفق بنية Meta

يعيد خيار «محاكاة فقط» الطلب إليك دون الاتصال بـ Meta؛ أما التبديل إلى «إرسال رسالة حقيقية» فيرسله ويُظهر لك استجابة Meta الفعلية، بغلاف الخطأ وكل تفاصيله.

يستهدف مربع الحوار POST /{phone-number-id}/messages دون سواه، لذا لا يمكن الوصول إلى نقاط نهاية إدارة الحساب من خلاله — فجرّبها باستخدام curl أو عبر عميلك الخاص.

يتضمن الحصول على الكود عنصر التحكم نفسه، وبذلك تستهدف القصاصة البرمجية المُنشأة أي واجهة تختارها، بأيٍّ من اللغات الثماني. اترك خيار «طلب التوقيع» غير مفعّل في أي مفتاح تنوي استخدامه هنا — فعند تفعيله، تقوم قصاصة Graph المُنشأة بتوقيع الطلب أيضاً، وهو الأمر الوحيد الذي لا يستطيع عميل Cloud API غير المعدَّل القيام به.