التكاملات

مرجع واتساب API للمطورين: عناوين الإرسال والحقول ورموز الأخطاء والحدود

مرجع واجهة إرسال واتساب API في عربي بوت: العناوين الخمسة، وحقول إرسال القالب والنص، وحالات الرسالة، وكل رمز رفض مع رمز HTTP وما تفعله معه، وحدود الطلبات والطابور.

9 دقائق قراءة آخر تحديث 15 نوفمبر 2026 فريق عربي بوت
فريق عربي بوتشريك Meta الرسمي · نكتب من بيانات منصتنا
في هذه الصفحة 9
  1. العنوان والمصادقة
  2. العناوين الخمسة
  3. إرسال قالب: الحقول
  4. إرسال نص حر
  5. حالة الرسالة
  6. رموز الرفض وما تفعله مع كلٍّ منها
  7. الحدود
  8. الباقات واللغات
  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_KEY401المفتاح غائب أو خاطئ أو أُلغي. أنشئ مفتاحًا من «أدوات المطورين».
SUBSCRIPTION_EXPIRED · MONTHLY_LIMIT402الاشتراك منتهٍ، أو بلغ الحساب حد الإرسال الشهري في باقته.
NOT_IN_PLAN · API_OFF403الباقة لا تشمل «أدوات المطورين»، أو الواجهة غير متاحة للحساب الآن.
NO_NUMBER409لا رقم واتساب متصل بالحساب، أو الرقم في from ليس من أرقامه.
NO_TEMPLATE · NO_TEXT · BAD_PHONE · TEXT_TOO_LONG422حقل ناقص أو رقم بلا كود الدولة أو نص أطول من ٤٠٩٦ حرفًا. صحّح الطلب.
TEMPLATE_NOT_FOUND404لا قالب بهذا الاسم واللغة على الرقم. الأسماء في GET /templates.
TEMPLATE_NOT_APPROVED409القالب في المراجعة أو مرفوض أو موقوف؛ الحالة في template_status.
BAD_VALUES422قيم لا تطابق القالب؛ التفصيل في problems.
OPTED_OUT409العميل أوقف الرسائل التسويقية من واتساب، فلا يصله قالب تسويق. لا تُعد المحاولة.
META_REFUSED422رفضت واتساب الرسالة؛ رمزها في meta_code ونصها في meta_message.
TRY_AGAIN503واتساب مشغول أو تعذّر التسجيل لحظةً. أعد الطلب نفسه بالمرجع نفسه بعد دقيقة.
UNCERTAIN202انقطع رد واتساب بعد الإرسال وقد تكون الرسالة وصلت. اسأل عنها بـGET /messages/{id} قبل أن تعيد.
NOT_FOUND404لا رسالة بهذا الرقم على الحساب.
BAD_JSON · METHOD · NO_SUCH_ENDPOINT400 · 405 · 404جسم ليس JSON صحيحًا، أو عنوان يُستدعى بـPOST، أو عنوان غير موجود.
SERVER500خطأ عندنا. أعد المحاولة، وإن تكرر فأبلغ الدعم.

أكواد أخطاء واتساب API من ميتا ومعنى كلٍّ منها

الحدود

الحدالقاعدة
الطلبات٦٠٠ طلب في الدقيقة لكل مفتاح؛ ما يزيد يُرد برمز ٤٢٩ وترويسة Retry-After
سرعة الرقمرسائل الرقم تخرج بالسرعة التي يقبلها واتساب، والزائد ينتظر في الطابور بحالة queued
رفض واتساب بسبب الضغطنعيد الإرسال تلقائيًا تحت رقم الرسالة الأول
النص الحر٤٠٩٦ حرفًا، وداخل نافذة ٢٤ ساعة
المرجعحتى مئة حرف، ويبقى فريدًا على مستوى الحساب

وحدود ميتا نفسها على رقمك، كعدد من تبدأ معهم محادثات في اليوم وتقييم الجودة، تبقى كما هي خلف هذه الواجهة. تقييم الجودة وحدود الإرسال

الباقات واللغات

الواجهة في باقات «WhatsApp Pro» و«WhatsApp Premium» و«Complete Plan» و«Ultimate Plan»، ورسوم ميتا على حساب واتساب للأعمال الخاص بك بلا عمولة منا. وفي صفحة «أدوات المطورين» منشئ يكتب لك الطلب جاهزًا بأربع صيغ. وهنا شرح كامل بكل لغة:

الأسئلة الشائعة

1

من أين أحصل على مفتاح واجهة الإرسال؟

من صفحة «أدوات المطورين» في لوحة عربي بوت. يبدأ المفتاح بـabk_ ويظهر مرة واحدة عند إنشائه، لأننا لا نحتفظ منه إلا ببصمته. إن ضاع فألغِه وأنشئ غيره.

2

هل أستطيع إرسال نص حر لأي رقم؟

لا. النص الحر يُقبل خلال ٢٤ ساعة من آخر رسالة كتبها العميل، وهذا شرط ميتا لا شرطنا. خارج هذه النافذة ترسل قالبًا معتمدًا.

3

ماذا يحدث إن أرسل نظامي مئات الرسائل في لحظة واحدة؟

لا تضيع رسالة. ما يزيد على السرعة التي يقبلها واتساب لرقمك يدخل طابورًا ويعود رده بالحالة queued ومعه رقم الرسالة، ثم يُرسل وحده خلال لحظات. وإن رفضت واتساب رسالة بسبب الضغط أعدنا إرسالها تحت الرقم نفسه.

4

كيف أمنع إرسال الرسالة مرتين؟

أرسل مع كل طلب حقل reference بقيمة ثابتة من نظامك، كرقم الطلب مع نوع الإشعار. إن وصلنا المرجع نفسه مرة ثانية لم نرسل شيئًا، وأعدنا إليك الرسالة الأولى مع "duplicate": true.

5

هل تأخذ عربي بوت عمولة على كل رسالة؟

لا. رسوم ميتا على المحادثات تُحسب على حساب واتساب للأعمال الخاص بك، كما في أي قالب ترسله، ولا نضيف عليها شيئًا. والواجهة جزء من الباقات التي تشمل «أدوات المطورين».

فريق عربي بوتشريك Meta الرسمي للأعمال في الشرق الأوسط 239 دليلًا أرقام من منصتنا كل الأدلة

كيف نكتب هذه الأدلة الأرقام من منصتنا وفواتير ميتا الفعلية ومؤرّخة بعيّنتها، والوصف لما يعمل اليوم لا لما نعد به، ونذكر ما لا نفعله ومتى يكون غيرنا الخيار الأفضل. راجعه فريق عربي بوت في 15 نوفمبر 2026.

شارك الدليل
وتديره كله من موبايلككل ما في هذه الصفحة تديره من تطبيق عربي بوت على جوالك — الردود والطلبات والحملات وتقارير الذكاء الاصطناعي. لا لوحة تحكم على الويب فحسب.

جرّب الوكيل قبل أن تدفع شيئًا

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