إنتقل إلى المحتوى الرئيسي

إرسال رسالة واتساب

يُرسل رسالة نصية حرة إلى مستلم واتساب. النص الحر مقيّد بـنافذة خدمة العملاء (24 ساعة) من ميتا — يجب أن يكون العميل قد راسل الوكيل خلال آخر 24 ساعة. للإرسال خارج النافذة، استخدم إرسال قالب بدلاً من ذلك.

أي نقطة أستدعي؟​

POST إلى /v1/whatsapp/messages عبر HTTPS. النقطة تتطلّب نطاق whatsapp:send على مفتاح API الخاص بك — راجع التوثيق لمعرفة كيف تعمل النطاقات.

POST /v1/whatsapp/messages

كيف يبدو الطلب؟​

curl -X POST https://api.mojeeb.app/v1/whatsapp/messages \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-to-ticket-9001" \
  -d '{
    "agent_id": "12345678-1234-1234-1234-123456789012",
    "from":     "+15557654321",
    "to":       "+15551234567",
    "text":     { "body": "Thanks for reaching out! How can I help?" }
  }'

ماذا يُوضع في جسم الطلب؟​

أربعة حقول مطلوبة. الوكيل وfrom معاً يُحدّدان رقم واتساب الذي ترسل منه؛ to وtext.body يحملان الوجهة والرسالة نفسها.

الحقلالنوعمطلوبالوصف
agent_idUUIDنعمالوكيل المُرسِل. يجب أن يكون مُصرَّحاً لمفتاح API.
fromنص E.164نعمرقم عمل واتساب المُرسِل. يجب مطابقة اتصال واتساب نشط على الوكيل.
toنص E.164نعمهاتف المستلم، مثل +15551234567.
text.bodyنصنعمنص الرسالة. حد طوله في المرجع.

ما الرؤوس الاختيارية التي يمكنني إرسالها؟​

اثنان يستحقّان المعرفة — كلاهما يُحسّن الموثوقية وقابلية التتبّع دون تغيير ما يُرسَل.

الرأسالغرض
Idempotency-Keyاجعل الإعادات آمنة. راجع الإعادة الآمنة.
X-Correlation-IDمعرّف تتبّع مخصّص نحترمه إن كان صالحاً ونُعيده في الاستجابة؛ راجع الأخطاء للقواعد.

كيف تبدو استجابة النجاح؟​

HTTP 202 Accepted مع كائن الرسالة: id، وstatus: "queued"، وagent_id وto كما أرسلتهما، وtype: "text"، وcreated_at. كل الحقول مع مثال موجودة في مرجع هذه النقطة، المعروض من عقد الواجهة نفسه فلا يتقادم أبداً.

الـ202 يعني أن الرسالة في طابور التسليم. استخدم id المُعاد مع استعلام حالة الرسالة لتتبّع التسليم.

ماذا قد يفشل؟​

يُعاد ظرف الخطأ القياسي. الرموز الشائعة أدناه؛ تفرّع على code (ثابت) — لا تفرّع أبداً على message (قد يُعاد صياغته). الكتالوج الكامل في صفحة الأخطاء.

codeHTTPمتى
invalid_request_body422حقل مطلوب مفقود — param يُسمي أيهما
invalid_phone_number422to ليس E.164 صالحاً
invalid_from_phone422from ليس E.164 صالحاً
from_phone_not_found_for_agent422from لا يطابق أي اتصال واتساب نشط — available_phones يُدرج ما يعمل
agent_not_authorized403مفتاح API غير مسموح له باستخدام هذا الوكيل
insufficient_scope403مفتاح API يفتقر whatsapp:send
rate_limit_exceeded429ميزانية المفتاح تم بلوغها — راجع حدود المعدّل

ماذا عن نافذة الـ24 ساعة؟​

قواعد WhatsApp Business تتطلّب إرسال النص الحر داخل نافذة خدمة العملاء (24 ساعة) — يجب أن يكون العميل قد راسل الوكيل خلال آخر 24 ساعة. خارج هذه النافذة، ميتا ترفض التسليم حتى لو قبل مجيب الطلب وأعاد 202.

إن أرسلت نصاً حراً خارج النافذة، الاستجابة الفورية لا تزال 202 (نقبل ونضع في الطابور)، لكن الرسالة ستنتقل إلى status: "failed" مع failed_at معبّأ بمجرد رفض ميتا للتسليم. استعلم عن حالة الرسالة لرؤية ذلك يحدث. يُعاد الإرسال الفاشل بضع مرات، فانتظر دقيقتين تقريباً قبل أن تعتبر failed نهائية؛ راجع هل failed نهائية؟

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

أسئلة شائعة​

هل يمكنني إرسال وسائط (صور، صوت، مستندات)؟​

ليس في v1 من الواجهة العامة. دعم الوسائط محجوز كتغيير إضافي. استخدم لوحة التحكم لإرسال الوسائط في الوقت الحالي.

ما الحد الأقصى لطول الجسم؟​

الحد الدقيق في مرجع هذه النقطة؛ وهو يُطابق حد واتساب نفسه. الأجسام الأطول تُرفَض بـinvalid_request_body.

هل تتحقّق الواجهة مما إذا كان المستلم داخل نافذة الـ24 ساعة؟​

لا — ميتا تُطبّق النافذة، وليس نحن. الواجهة تقبل طلبك وتضع الإرسال في الطابور؛ إن رفضت ميتا التسليم، سترى status: "failed" على استعلام حالة الرسالة.

هل يمكن لنفس الرقم الإرسال إلى نفسه؟​

لا يمكنك الإرسال إلى رقم عملك الخاص — ميتا ترفض هذا على مستوى المنصة. الإرسال يُعيد 202 منّا لكن failed على استعلام الحالة.