مرجع واتساب API للمطورين: عناوين الإرسال والحقول ورموز الأخطاء والحدود
مرجع واجهة إرسال واتساب API في عربي بوت: العناوين الخمسة، وحقول إرسال القالب والنص، وحالات الرسالة، وكل رمز رفض مع رمز HTTP وما تفعله معه، وحدود الطلبات والطابور.
في هذه الصفحة 9
الإجابة المختصرة
واجهة إرسال واتساب في عربي بوت خمسة عناوين تحت https://app.arabybot.com/api/v1 بمفتاح في ترويسة Authorization: التحقق من المفتاح، وسرد القوالب المعتمدة، وإرسال قالب، وإرسال نص حر داخل نافذة ٢٤ ساعة، والسؤال عن حالة الرسالة. تقبل ٦٠٠ طلب في الدقيقة لكل مفتاح، وما يزيد على سرعة الرقم عند واتساب ينتظر في طابور ولا يضيع، وحقل reference يمنع الإرسال مرتين.
يُسأل عنها أيضًا: «توثيق واتساب api» · «ارسال رسالة واتساب عن طريق api» · «واتساب api للمطورين» · «whatsapp api documentation»
العنوان والمصادقة
| البند | القيمة |
|---|---|
| العنوان الأساسي | https://app.arabybot.com/api/v1 |
| المفتاح | من «أدوات المطورين» في اللوحة، يبدأ بـabk_ ويظهر مرة واحدة |
| الترويسة | Authorization: Bearer abk_… أو X-Api-Key: abk_… |
| جسم الطلب | JSON، ويُقبل النموذج العادي للأنظمة التي لا ترسل JSON |
| الرد | JSON دائمًا، وفيه success، وعند الرفض error_code ورسالة بالعربية والإنجليزية |
النداء من خادمك إلى خادمنا. لا تضع المفتاح في صفحة يفتحها الزائر ولا في تطبيق الهاتف، فمن يملكه يرسل من رقمك.
العناوين الخمسة
| النداء | ما يفعله | أهم ما يعيده |
|---|---|---|
GET /me | يتأكد أن المفتاح يعمل | اسم المفتاح وأرقام واتساب التي يرسل منها، وأيها الافتراضي |
GET /templates | يسرد القوالب المعتمدة | اسم كل قالب ولغته وفئته ونصه، وجسم طلب جاهز لإرساله في example |
POST /messages/template | يرسل قالبًا معتمدًا إلى رقم واحد | id, message_id, status |
POST /messages/text | يرسل نصًا حرًّا داخل نافذة ٢٤ ساعة | id, message_id, status |
GET /messages/{id} | يسأل أين وصلت الرسالة | الحالة، والسبب إن فشلت |
إرسال قالب: الحقول
| الحقل | مطلوب؟ | القيمة |
|---|---|---|
to | نعم | رقم المستلم بكود الدولة، مثل 966501234567 |
template | نعم | اسم القالب كما في GET /templates |
language | لا | لغة القالب إن كان الاسم نفسه بأكثر من لغة، مثل ar |
variables | إن كان في القالب متغيرات | قائمة بالترتيب ["أحمد","1042"]، أو بالرقم {"1":"أحمد"}، أو بالاسم للقوالب ذات المتغيرات المسمّاة |
header | إن كان للقالب رأس بقيمة | نص، أو رابط صورة أو فيديو أو ملف، أو {"link":"…","filename":"…"} |
buttons | إن احتاج زر إلى قيمة | قائمة بقيمة كل زر بالترتيب، كذيل الرابط أو رمز الخصم |
from | لا | الرقم الذي ترسل منه إن كان على حسابك أكثر من رقم |
reference | لا، ونوصي به | مرجع من نظامك حتى مئة حرف؛ يمنع الإرسال مرتين |
POST https://app.arabybot.com/api/v1/messages/template
Authorization: Bearer abk_…
Content-Type: application/json
{
"to": "966501234567",
"template": "order_shipped",
"language": "ar",
"variables": ["Ahmed", "1042"],
"header": "https://example.com/invoice-1042.pdf",
"buttons": ["1042"],
"reference": "order-1042-shipped"
}
200
{ "success": true, "id": 512, "message_id": "wamid.…", "status": "accepted", "to": "966501234567" } قبل أن يصل الطلب إلى ميتا نراجع القيم على القالب المعتمد نفسه: متغير ناقص، أو صورة لقالب رأسه صورة، أو قيمة فيها سطر جديد. كل ذلك يُرفض مرة واحدة بالرمز BAD_VALUES مع قائمة problems، بدل أن ترفضه ميتا لكل رسالة.
إرسال نص حر
POST /messages/text يأخذ to وtext حتى ٤٠٩٦ حرفًا، ومعهما from وreference اختياريًّا. ويصلح للرد على عميل راسلك خلال آخر ٢٤ ساعة، كإشعار من نظامك بأن طلبه جاهز بعد أن سأل عنه. خارج النافذة ترفضه ميتا ويعود الرد بالرمز META_REFUSED.
حالة الرسالة
| الحالة | معناها |
|---|---|
queued | تنتظر دورها في طابور رقمك، وتُرسل وحدها |
accepted | قبلتها واتساب |
sent | خرجت إلى هاتف العميل |
delivered | وصلت |
read | قرأها العميل |
failed | فشلت، وفي error رمز ميتا والسبب |
GET https://app.arabybot.com/api/v1/messages/512
Authorization: Bearer abk_…
200
{ "success": true, "id": 512, "message_id": "wamid.…", "to": "966501234567",
"status": "delivered", "reference": "order-1042-shipped",
"created_at": "2026-11-15 18:04:10", "updated_at": "2026-11-15 18:04:13" }
# a failed message carries the reason
{ "success": true, "id": 513, "status": "failed",
"error": { "meta_code": "131026", "message": "…", "meta_message": "…" } } يُسأل عن الرسالة برقمها عندنا id أو برقم ميتا message_id. ورسائل الواجهة تظهر في الدردشة المباشرة داخل محادثة العميل مع بقية رسائله، فيراها فريقك.
رموز الرفض وما تفعله مع كلٍّ منها
409
{ "success": false, "error_code": "TEMPLATE_NOT_APPROVED",
"message": "…", "message_en": "Template \"order_shipped\" is still in Meta's review — it can be sent once approved.",
"template_status": "PENDING" } | الرمز | HTTP | ما يعنيه وما تفعله |
|---|---|---|
NO_KEY · INVALID_KEY | 401 | المفتاح غائب أو خاطئ أو أُلغي. أنشئ مفتاحًا من «أدوات المطورين». |
SUBSCRIPTION_EXPIRED · MONTHLY_LIMIT | 402 | الاشتراك منتهٍ، أو بلغ الحساب حد الإرسال الشهري في باقته. |
NOT_IN_PLAN · API_OFF | 403 | الباقة لا تشمل «أدوات المطورين»، أو الواجهة غير متاحة للحساب الآن. |
NO_NUMBER | 409 | لا رقم واتساب متصل بالحساب، أو الرقم في from ليس من أرقامه. |
NO_TEMPLATE · NO_TEXT · BAD_PHONE · TEXT_TOO_LONG | 422 | حقل ناقص أو رقم بلا كود الدولة أو نص أطول من ٤٠٩٦ حرفًا. صحّح الطلب. |
TEMPLATE_NOT_FOUND | 404 | لا قالب بهذا الاسم واللغة على الرقم. الأسماء في GET /templates. |
TEMPLATE_NOT_APPROVED | 409 | القالب في المراجعة أو مرفوض أو موقوف؛ الحالة في template_status. |
BAD_VALUES | 422 | قيم لا تطابق القالب؛ التفصيل في problems. |
OPTED_OUT | 409 | العميل أوقف الرسائل التسويقية من واتساب، فلا يصله قالب تسويق. لا تُعد المحاولة. |
META_REFUSED | 422 | رفضت واتساب الرسالة؛ رمزها في meta_code ونصها في meta_message. |
TRY_AGAIN | 503 | واتساب مشغول أو تعذّر التسجيل لحظةً. أعد الطلب نفسه بالمرجع نفسه بعد دقيقة. |
UNCERTAIN | 202 | انقطع رد واتساب بعد الإرسال وقد تكون الرسالة وصلت. اسأل عنها بـGET /messages/{id} قبل أن تعيد. |
NOT_FOUND | 404 | لا رسالة بهذا الرقم على الحساب. |
BAD_JSON · METHOD · NO_SUCH_ENDPOINT | 400 · 405 · 404 | جسم ليس JSON صحيحًا، أو عنوان يُستدعى بـPOST، أو عنوان غير موجود. |
SERVER | 500 | خطأ عندنا. أعد المحاولة، وإن تكرر فأبلغ الدعم. |
أكواد أخطاء واتساب API من ميتا ومعنى كلٍّ منها
الحدود
| الحد | القاعدة |
|---|---|
| الطلبات | ٦٠٠ طلب في الدقيقة لكل مفتاح؛ ما يزيد يُرد برمز ٤٢٩ وترويسة Retry-After |
| سرعة الرقم | رسائل الرقم تخرج بالسرعة التي يقبلها واتساب، والزائد ينتظر في الطابور بحالة queued |
| رفض واتساب بسبب الضغط | نعيد الإرسال تلقائيًا تحت رقم الرسالة الأول |
| النص الحر | ٤٠٩٦ حرفًا، وداخل نافذة ٢٤ ساعة |
| المرجع | حتى مئة حرف، ويبقى فريدًا على مستوى الحساب |
وحدود ميتا نفسها على رقمك، كعدد من تبدأ معهم محادثات في اليوم وتقييم الجودة، تبقى كما هي خلف هذه الواجهة. تقييم الجودة وحدود الإرسال
الباقات واللغات
الواجهة في باقات «WhatsApp Pro» و«WhatsApp Premium» و«Complete Plan» و«Ultimate Plan»، ورسوم ميتا على حساب واتساب للأعمال الخاص بك بلا عمولة منا. وفي صفحة «أدوات المطورين» منشئ يكتب لك الطلب جاهزًا بأربع صيغ. وهنا شرح كامل بكل لغة:
- إرسال رسالة واتساب بلغة PHP ولارافيل
- إرسال رسالة واتساب بلغة بايثون
- إرسال رسالة واتساب من Node.js
- واجهة رموز التحقق OTP على واتساب
- كل ما يملكه المطورون في عربي بوت: الإرسال والويب هوك وأدوات الوكيل
الأسئلة الشائعة
من أين أحصل على مفتاح واجهة الإرسال؟
من صفحة «أدوات المطورين» في لوحة عربي بوت. يبدأ المفتاح بـabk_ ويظهر مرة واحدة عند إنشائه، لأننا لا نحتفظ منه إلا ببصمته. إن ضاع فألغِه وأنشئ غيره.
هل أستطيع إرسال نص حر لأي رقم؟
لا. النص الحر يُقبل خلال ٢٤ ساعة من آخر رسالة كتبها العميل، وهذا شرط ميتا لا شرطنا. خارج هذه النافذة ترسل قالبًا معتمدًا.
ماذا يحدث إن أرسل نظامي مئات الرسائل في لحظة واحدة؟
لا تضيع رسالة. ما يزيد على السرعة التي يقبلها واتساب لرقمك يدخل طابورًا ويعود رده بالحالة queued ومعه رقم الرسالة، ثم يُرسل وحده خلال لحظات. وإن رفضت واتساب رسالة بسبب الضغط أعدنا إرسالها تحت الرقم نفسه.
كيف أمنع إرسال الرسالة مرتين؟
أرسل مع كل طلب حقل reference بقيمة ثابتة من نظامك، كرقم الطلب مع نوع الإشعار. إن وصلنا المرجع نفسه مرة ثانية لم نرسل شيئًا، وأعدنا إليك الرسالة الأولى مع "duplicate": true.
هل تأخذ عربي بوت عمولة على كل رسالة؟
لا. رسوم ميتا على المحادثات تُحسب على حساب واتساب للأعمال الخاص بك، كما في أي قالب ترسله، ولا نضيف عليها شيئًا. والواجهة جزء من الباقات التي تشمل «أدوات المطورين».
اقرأ بعدها
جرّب الوكيل قبل أن تدفع شيئًا
الوكيل الذي يرد على عملائك هو نفسه الذي يرد عليك الآن: اسأله من زر الدردشة هنا أو على واتساب. وحسابك مجاني بلا بطاقة ائتمان، والتجربة المجانية على رقمك أو صفحتك تُفعَّل بعد التواصل مع الإدارة على واتساب خدمة العملاء.