ربط برنامجك بواتساب

إدارة API هي الطريقة التي يرسل بها نظام آخر — برنامج الفوترة لديك، أو متجرك الإلكتروني، أو الواجهة الخلفية الخاصة بك — رسائل واتساب عبر WizMessage. من هنا تُصدر له مفتاح API، وتحدد له قالب واتساب المعتمد الذي يُسمح له بإرساله، وتوجّهه إلى خطاف ويب لتعود إليك الردود. يمر هذا الدليل على المسار كاملاً، ثم يوثّق واجهة REST التي سيستدعيها مطوروك.

لوحة التحكم

أين توجد مفاتيح API

يظهر هنا، ضمن «API Keys»، كل مفتاح أصدرته. يعرض كل صف حالة المفتاح، وبادئته العامة (وهي الجزء الوحيد من المفتاح الذي يُعرض مرة أخرى بعد إنشائه)، وعدد الاستدعاءات التي أجراها اليوم. يفتح زر «Manage» المفتاح، بينما يوقفه مفتاح التبديل مؤقتاً دون حذفه.

1. ▶ أين توجد مفاتيح API
2. ▶ مفتاح لم يكتمل إعداده بعد

مفتاح لم يكتمل إعداده بعد

يحمل أي مفتاح لم يُربط به قالب شارة «Needs setup». يستطيع هذا المفتاح المصادقة، لكنه لا يستطيع إرسال رسالة قالب حتى تربط به واحداً — وبذلك يتضح أي دمج ناقص الإعداد من نظرة واحدة بدلاً من أن يفشل لاحقاً عند الإرسال.

الإعداد الموجّه

الخطوة 1 — ما الذي تريد ربطه؟

يفتح زر «Connect your software» معالجاً من أربع خطوات. ابدأ بتسمية المفتاح باسم النظام الذي سيستخدمه، ثم اختر الإعداد المسبق المطابق. لا تقترح الإعدادات المسبقة سوى أسماء حقول معقولة — فإعداد الفوترة يقترح invoice_number، amount، due_date، customer_name — وهي لا تقيّد ما يمكنك ربطه.

1. ▶ الخطوة 1 — ما الذي تريد ربطه؟
2. ▶ الخطوة 2 — اختيار الرسالة
3. ▶ الخطوة 3 — إلى أين تذهب الردود؟
4. ▶ الخطوة 4 — الانتقال إلى الإنتاج

الخطوة 2 — اختيار الرسالة

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

الخطوة 3 — إلى أين تذهب الردود؟

عندما يرد أحدهم على رسالتك، أو يصل تقرير تسليم، نرسله عبر POST إلى رابط تتحكم به أنت. اترك هذا الخيار معطّلاً إذا كان نظامك يرسل فقط. يمكنك إضافته لاحقاً من علامة تبويب «Webhooks» الخاصة بالمفتاح — فلا شيء هنا دائم.

الخطوة 4 — الانتقال إلى الإنتاج

الضغط على «Next» في الخطوة السابقة هو ما يُنشئ المفتاح فعلياً — وهذه الشاشة ليست سوى التأكيد. انسخ القيم الثلاث الآن: يُعرض مفتاح API وسر API وسر توقيع خطاف الويب مرة واحدة فقط، ولا يمكن استرجاعها بعد ذلك. وإذا فقدت السر فعليك تدويره، وهو ما يعني تحديث أي نظام كان يستخدمه.

إدارة مفتاح

نظرة عامة

يؤدي فتح أي مفتاح إلى علامة تبويب «Overview»: ما يُسمح له بفعله، ومدى كثافة استخدامه، ونقاط النهاية التي يمكنه استدعاؤها. تُقرأ أعداد الاستخدام من سجل الطلبات، لذا فهي تعكس حركة المرور الفعلية.

1. ▶ نظرة عامة

مفتاح ما زال يحتاج إلى إعداد

أما المفتاح الذي لم يُربط به أي قالب فيُفتح على علامة تبويب «Setup» بدلاً من ذلك — وهي المعالج نفسه، لكن مدمجاً في الصفحة. لاحظ اختلاف علامات التبويب عن اللقطة السابقة: فحتى يصبح للمفتاح قالب واحد على الأقل، لا تظهر علامتا «Templates» و«Webhooks»، لأنه لا يوجد بعد ما تعملان عليه.

1. ▶ مفتاح ما زال يحتاج إلى إعداد

القوالب

تعرض علامة تبويب «Templates» بطاقة لكل قالب يُسمح لهذا المفتاح بإرساله. النص الأساسي هو الرسالة كما اعتُمدت لدى Meta، والوسوم أسفله هي أسماء المتغيرات التي سيوفرها نظامك. يرسل زر «Try it» رسالة اختبارية، ويُنتج زر «Get code» طلباً جاهزاً بثماني لغات برمجة.

1. ▶ القوالب
2. ▶ قراءة المتغيرات — الأمر الوحيد الذي يستحق التمهل عنده

قراءة المتغيرات — الأمر الوحيد الذي يستحق التمهل عنده

انظر إلى بطاقة payment_failed_alert. تسير رسالتها هكذا: {{1}} ثم {{3}} ثم {{2}} — أي أن العناصر النائبة ليست مرتبة رقمياً داخل النص. أما الوسوم أسفلها فمُدرجة بالترتيب الرقمي: customer_name يملأ {{1}}، و renewal_date يملأ {{2}}، و plan_name يملأ {{3}}. طابق قيمك مع الرقم، لا مع الترتيب الذي تظهر به العناصر النائبة في الجملة. وهذا أكثر ما يوقع الناس في الخطأ مع القوالب المترجمة، حيث يزيح ترتيب الكلمات العناصر النائبة عن مواضعها.

الأزرار الثلاثة في كل قالب

«Try it» — أرسل اختباراً دون كتابة أي شيفرة

يفتح زر الطائرة الورقية هذا القالب محمّلاً مسبقاً بقيم نموذجية، واحدة لكل اسم متغير. وهو أسرع وسيلة للتأكد من صحة الربط قبل أن يلمسه مطوروك. لاحظ مفتاح التبديل: «Simulate Only» هو الوضع الافتراضي ولا يخرج شيء إلى الخارج — إذ يعيد الخادم حمولتك كما هي. حوّله إلى «Send Real Message» فتنطلق رسالة واتساب حقيقية إلى الرقم المكتوب في الحقل، وتُحتسب تكلفتها.

1. ▶ «Try it» — أرسل اختباراً دون كتابة أي شيفرة
2. ▶ ماذا يعيد إليك الإرسال المحاكى
3. ▶ «Get code» — الطلب مكتوباً من أجلك
4. ▶ تبديل اللغة
5. ▶ «Edit» — غيّر ما يرسله نظامك
6. ▶ Test API — الأداة نفسها، وأي نقطة نهاية
7. ▶ خطافات الويب — استقبال الردود

ماذا يعيد إليك الإرسال المحاكى

يعيد الضغط على «Send Request» في وضع «Simulate Only» الطلبَ كما استقبلته المنصة، مع حالة HTTP وزمن الذهاب والعودة. اقرأ ذلك بوصفه فحصاً للشكل لا بروفة نهائية: فهو يؤكد أن ملف JSON قد جرى تحليله وأن المفتاح قُبل، لكنه لا يتحقق من أسماء متغيراتك مقابل الربط، ولا يتصل بـ Meta إطلاقاً. والحمولة التي تُحاكى بنجاح قد تُرفض مع ذلك عند الإرسال الحقيقي. ولإثبات صحة الربط نفسه، فعّل «Send Real Message» وأرسل إلى هاتفك أنت.

«Get code» — الطلب مكتوباً من أجلك

يولّد زر الأقواس الزاوية طلباً عاملاً لهذا القالب تحديداً بثماني لغات: cURL و JavaScript و Node.js و Python و PHP و Ruby و Go و C#. سلّمه لمن يكتب الدمج. تظهر المتغيرات على هيئة {{placeholders}} مسمّاة وفق الربط لديك، وتبقى بيانات الاعتماد على صورة YOUR_API_KEY / YOUR_API_SECRET — فهذه النافذة لا تطبع مفتاحك الحقيقي أبداً، ومن ثم يمكن لصق المقتطف في تذكرة دعم بأمان.

تبديل اللغة

انقر أي لغة في الأعلى فيُعاد كتابة المقتطف بها — الاستدعاء نفسه، والترويسات نفسها، وعميل HTTP الخاص بتلك اللغة. ويُولَّد كل مقتطف عند أول نقرة عليه، لذا فمن الطبيعي أن ترى مؤشر تحميل قصيراً عند أول تبديل. ويأخذ زر «Copy» المقتطف كما يظهر: فهو كامل بما فيه عبارات الاستيراد، وإن كان هذا المفتاح يشترط التواقيع فخطوة التوقيع موجودة فيه سلفاً.

«Edit» — غيّر ما يرسله نظامك

يفتح زر القلم الربط نفسه. ونموذج الهاتف في الأعلى هو الرسالة الحقيقية بعد إحلال أسمائك الحالية فيها، فترى ما سيقرؤه العميل. وأسفله يمكن إعادة تسمية كل متغير مكتشف، أو إعادة ترتيبه، أو جعله إلزامياً، أو منحه نوعاً — تاريخاً أو مبلغاً مالياً أو صورة. وإعادة تسمية متغير تعيد تسميته في حمولة API لديك أيضاً، فأي نظام ما زال يرسل الاسم القديم سيبدأ بالفشل: غيّر الأمرين معاً.

Test API — الأداة نفسها، وأي نقطة نهاية

زر «Test API» أعلى علامة التبويب هو «Try it» نفسه لكن دون التقيد بقالب واحد: اختر أياً من نقاط نهاية الإرسال الثلاث، وبدّل القالب من القائمة المنسدلة الثانية، وحرّر الجسم كما تشاء. استعمله لفحص الاستدعاءات الخام /messages/text أو /messages/template، وهي بلا بطاقة خاصة بها لأنها غير مرتبطة بأي ربط. ولاحظ أن متغيرات هذا القالب ما زالت تحمل الأسماء body_1 و body_2 و body_3 — هكذا يبدو القالب غير المربوط، وهذا تحديداً ما وُجد زر «Edit» لإصلاحه.

الردود

خطافات الويب — استقبال الردود

الإرسال ليس سوى نصف عملية الدمج. من علامة تبويب «Webhooks»، وجّه خطاف ويب إلى نقطة نهاية HTTPS خاصة بك، وسيرسل إليها WizMessage عبر POST الرسائل الواردة وتحديثات التسليم. يُعرض سر التوقيع مرة واحدة عند إنشائه؛ تحقق منه مع كل عملية تسليم لتتأكد أن الطلب صادر عنا فعلاً.

الأحداث التي تستقبلها

حدد الأحداث التي يجب أن يستقبلها هذا العنوان. كل حدث يصل في طلب POST مستقل.

ملاحظة: يتم تسليم message.received وmessage.reaction الواردة فقط عندما يكون نظام روبوت المحادثة للحساب مضبوطًا على Webhook. وإذا كان مضبوطًا على غير ذلك، تذهب الرسائل الواردة إلى الروبوت ولا يُستدعى عنوانك أبدًا — وتنبهك علامة تبويب Webhooks عند حدوث ذلك. أما التفاعلات التي يرسلها النشاط التجاري نفسه (direction: "outbound") فلا يؤثر عليها هذا الإعداد.

ملاحظة: التفاعلات التي يرسلها النشاط التجاري من هاتفه كانت تصل سابقًا بصيغة message.sent ونصّها "[Unsupported message type]". أصبحت الآن تصل بصيغة message.reaction مع direction: "outbound". فعّل الحدث الجديد إن كنت تعتمد عليها.

التسليم يتم مرة واحدة على الأقل (at-least-once). أزل التكرار بالاعتماد على event مع data.message_id وليس على ترويسة X-Webhook-Id وحدها، وأجب بـ 2xx بسرعة.

مرجع واجهة REST

كل ما سبق يهيّئ المفتاح. أما هذا فهو ما يستدعيه مطوروك فعلياً. الرابط الأساسي هو https://wizmessage.com/api/v1/external. تتطلب كل نقطة نهاية ترويسات المصادقة أدناه، وتخضع لحدود المعدل الخاصة بالمفتاح.

المصادقة

أرسل مفتاح API مع كل طلب. وإذا كان خيار «Require signature» مفعّلاً للمفتاح، فعليك أيضاً توقيع الطلب — وأي مفتاح مفعّل لديه هذا الخيار سيرفض تماماً كل استدعاء غير موقّع.

ملاحظة: لا تُفرض التواقيع إلا عندما يكون require_signature مفعّلاً للمفتاح. وإن لم يكن كذلك، فمفتاح API وحده يكفي لإرسال الرسائل — وهذا بالضبط سبب كون المفتاح سراً لا معرّفاً. تعامل معه ككلمة مرور: يُعرض مرة واحدة، وكل من يملكه يستطيع مراسلة عملائك.

const crypto = require('node:crypto')

const body = JSON.stringify({ to: '+919876543210', message: 'Hello' })
const timestamp = Math.floor(Date.now() / 1000).toString()

const secretHash = crypto.createHash('sha256').update(API_SECRET).digest('hex')
const signature = crypto.createHmac('sha256', secretHash)
	.update(timestamp + '.' + body)
	.digest('hex')

await fetch('https://wizmessage.com/api/v1/external/messages/text', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'X-API-Key': API_KEY,
		'X-Timestamp': timestamp,
		'X-API-Signature': signature,
	},
	body,
})

نقاط النهاية

إرسال قالب مربوط

هذه هي الحمولة المقابلة لعلامة تبويب «Templates». أنت ترسل المتغيرات بالاسم — الأسماء الظاهرة كوسوم على بطاقة القالب — وتتولى المنصة تجميع مكوّنات Meta نيابةً عنك. وهذا هو الغرض كله من ربط القالب: نظام الفوترة لديك لا يحتاج إلى معرفة أي شيء عن صيغة المكوّنات لدى Meta.

POST /api/v1/external/messages/template/send

{
	"to": "+919876543210",
	"template_name": "payment_failed_alert",
	"language": "en",
	"variables": {
		"customer_name": "Priya Sharma",
		"renewal_date": "12 Aug 2026",
		"plan_name": "Wiz Pro"
	},
	"reference": "invoice-2026-0817"
}

ملاحظة: يجب أن تطابق أسماء المتغيرات الربط تماماً — فالاسم غير المعروف يُتجاهل، وغياب اسم مطلوب يؤدي إلى رفض الطلب برمز 400. أما reference فهو لك: يُعاد إرساله في خطافات الويب حتى تتمكن من ربط تقرير التسليم بسجل في نظامك.

حدود المعدل

لكل مفتاح حدوده الخاصة، وهي ظاهرة في علامة تبويب «Overview» — 60 طلباً في الدقيقة و1000 رسالة في اليوم افتراضياً. تتضمن الاستجابات الرصيد المتبقي، لذا خفّف من وتيرة الطلبات عندما يقترب من النفاد بدلاً من إعادة المحاولة حتى تصطدم بالحائط.

إرسال الملفات عبر الـ API

داخل نافذة الـ 24 ساعة المفتوحة يمكن لبرنامجك إرسال ملف مباشرةً — بلا قالب وبلا موافقة. نقطة نهاية واحدة تغطي المستندات والصور والفيديو والصوت.

ما الذي يمكنك إرساله

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

POST /api/v1/external/messages/media

{
	"to": "+919876543210",
	"type": "document",
	"link": "https://example.com/invoice-2026-0817.pdf",
	"filename": "Invoice 2026-0817.pdf",
	"caption": "Your invoice for August",
	"reference": "invoice-2026-0817"
}

ارفع مرة، وأرسل مرارًا

إذا كنت ترسل الملف نفسه بشكل متكرر — قائمة أسعار أو كتالوج أو ملف شروط — فارفعه مرة واحدة واحتفظ بالمعرّف. يظل صالحًا 30 يومًا ويوفّر على واتساب إعادة جلب رابطك مع كل رسالة.

POST /api/v1/external/messages/media

{
	"to": "+919876543210",
	"type": "image",
	"media_id": "1234567890",
	"caption": "This month’s catalogue"
}

متى يُرفض الإرسال

• خارج نافذة الـ 24 ساعة. الوسائط الحرة تحتاج محادثة مفتوحة. أرسل قالبًا معتمدًا بدلًا من ذلك — راجع دليل صندوق الوارد المشترك لمعرفة آلية النافذة.
• المفتاح لا يملك صلاحية send_media. تحقق من شارات الصلاحيات في تبويب Overview للمفتاح.
• تعليق على ملف صوتي. واتساب لا يعرضه، لذا يُرفض بدل أن يُحذف بصمت.
• اسم ملف لغير المستندات. المستندات وحدها هي التي تعرض اسمًا.
• غياب media_id وlink معًا. واحد منهما مطلوب بالضبط.

ملاحظة: يمكنك تجربة كل هذا دون كتابة أي كود. افتح المفتاح، اضغط Test API، واختر POST /messages/media من قائمة نقاط النهاية — سيكون النص جاهزًا، و«Get code» سيكتب الطلب نفسه بثماني لغات.

التفاعلات

التفاعل هو الإيموجي الذي يضعه أحدهم على رسالة بعينها — 👍 على تأكيد طلب، ❤️ على صورة. وهو ليس رسالة قائمة بذاتها: بل يشير إلى رسالة. يستطيع برنامجك قراءة التفاعلات لحظة حدوثها، وإرسالها أيضًا.

حدث واحد، ثلاثة مصادر

قد يأتي التفاعل من عميلك، أو من المالك وهو يضغطه على هاتف تطبيق Business، أو من برنامجك عبر واجهة API. تصل الثلاثة كلها عبر الحدث نفسه message.reaction، فيكفي معالج واحد لكل الحالات — ويخبرك direction وsource أيها بين يديك.

كيف يبدو خطاف تفاعل

هنا يضيف عميل 👍 إلى رسالة أرسلتها إليه.

{
	"version": 1,
	"event": "message.reaction",
	"timestamp": "2026-08-01T09:14:22.031Z",
	"data": {
		"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjkz…",
		"direction": "inbound",
		"from": "+919876543210",
		"to": "+911122334455",
		"reaction": {
			"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…",
			"emoji": "👍",
			"action": "added"
		},
		"contact": {
			"name": "Priya Sharma",
			"wa_id": "919876543210"
		}
	}
}

في هذه الحمولة معرّفان باسم message_id، وهما ليسا الشيء نفسه. وهذا هو الحقل الجدير بقراءة ثانية.

ملاحظة: data.from هو عادةً رقم هاتف العميل، لكن واتساب لا يرسل رقمًا دائمًا. وحين لا يفعل، تحصل على معرّف مستخدم واتساب الخاص به — فتعامل مع from كمعرّف، لا كرقم يمكنك الاتصال به دائمًا.

إضافة تفاعل وإزالته

إزالة التفاعل حدث قائم بذاته، بحقل emoji فارغ وaction: "removed".

{
	"event": "message.reaction",
	"data": {
		"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSN0U3…",
		"direction": "inbound",
		"reaction": {
			"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…",
			"emoji": "",
			"action": "removed"
		}
	}
}

كل ضغطة رسالة واتساب مستقلة بمعرّف خاص بها. فالتفاعل بـ 👍، ثم تغييره إلى ❤️، ثم إزالته تمامًا يعطيك ثلاثة أحداث، ولا يحلّ أيٌّ منها محل الآخر في مخزنك. اجعل data.reaction.message_id هو المفتاح واحتفظ بالأحدث — فهو التفاعل الحالي لتلك الرسالة.

إرسال تفاعل من برنامجك

نقطة النهاية نفسها تضيف وتزيل. وما سيحدث يتوقف كليًا على ما إذا كنت ترسل إيموجي.

POST /api/v1/external/messages/reaction

{
	"to": "+919876543210",
	"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…",
	"emoji": "👍",
	"reference": "invoice-2026-0817"
}

الـ message_id هنا هو معرّف واتساب — أي whatsapp_message_id من استجابة إرسال، أو data.reaction.message_id من خطاف ويب. وهو ليس أبدًا أحد معرّفاتنا من نوع uuid. تستخدم التفاعلات صلاحية send_text، فأي مفتاح يستطيع مراسلة العميل يستطيع التفاعل.

ملاحظة: التفاعل لا ينتج عنه أبدًا message.delivered ولا message.read. فواتساب لا يرسلهما للتفاعل — والحدث اللاحق الوحيد الممكن هو message.failed عند رفض التفاعل. أما الاستعلام عنه بـ GET /messages/:uuid فيعمل كأي إرسال آخر.

متى يُرفض التفاعل

بعض حالات الرفض تحدث هنا، قبل أن يصل أي شيء إلى واتساب. وهي تعيد خطأً إلى استدعاء API ولا تنتج أي خطاف ويب على الإطلاق — إذ لا شيء يُبلَّغ عنه، لأن شيئًا لم يُرسَل.

• المفتاح لا يملك send_text. 403. تعيد التفاعلات استخدام هذه الصلاحية؛ ولا توجد صلاحية أخرى تُمنح.
• to ليس بصيغة E.164. 422. الصيغة +… نفسها كأي نقطة نهاية أخرى.
• message_id مفقود أو فارغ. 422. حتى 255 حرفًا.
• emoji مفقود. 422. لإزالة تفاعل أرسل "emoji": "" — أرسل الحقل فارغًا ولا تحذفه. حتى 16 حرفًا.

أما البقية فتحدث لدى واتساب، بعد قبولنا للاستدعاء. تحصل أولًا على 200 وخطاف message.reaction، ثم على message.failed يحمل الخطأ 131009 حالما يرفضه واتساب.

• مضى على الرسالة أكثر من 30 يومًا. هذا حدّ واتساب للتفاعل لا حدّنا — فنحن لا نتحقق من عمر الرسالة.
• الرسالة ليست من هذه المحادثة. wamid من دردشة أخرى، أو أحد معرّفاتنا uuid أُرسل سهوًا.
• الرسالة محذوفة، أو هي نفسها تفاعل. لا يمكن التفاعل مع تفاعل.

ملاحظة: إذا فشل الإرسال من أوله بدل أن يُرفض لاحقًا، تحصل على 500 وعلى message.failed يكون فيه data.message_id هو معرّفنا نحن من نوع uuid، لا wamid — إذ لا يوجد معرّف واتساب يُبلَّغ عنه، لأن واتساب لم يقبله أصلًا.

ملاحظة: كما هي الحال مع أي نقطة نهاية أخرى، يمكنك تجربة هذا دون كتابة كود. افتح المفتاح، اضغط Test API، واختر POST /messages/reaction — تفاعَل مع رسالة على هاتفك وراقب وصول الخطاف.