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

إدارة 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 الرسائل الواردة وتحديثات التسليم. يُعرض سر التوقيع مرة واحدة عند إنشائه؛ تحقق منه مع كل عملية تسليم لتتأكد أن الطلب صادر عنا فعلاً.

مرجع واجهة REST

كل ما سبق يهيّئ المفتاح. أما هذا فهو ما يستدعيه مطوروك فعلياً. الرابط الأساسي هو /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://your-host/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 رسالة في اليوم افتراضياً. تتضمن الاستجابات الرصيد المتبقي، لذا خفّف من وتيرة الطلبات عندما يقترب من النفاد بدلاً من إعادة المحاولة حتى تصطدم بالحائط.