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

البدء السريع

أرسل أول رسالة واتساب في 5 دقائق. هذا الدليل يفترض أن لديك حساب مجيب على باقة Starter أو Professional ورقم واتساب واحد متّصل على الأقل.

الخطوة 1 — كيف أحصل على مفتاح API؟​

  1. سجّل دخولك إلى لوحة تحكم مجيب
  2. افتح صفحة مفاتيح API من الشريط الجانبي
  3. اضغط إنشاء مفتاح، اعطه اسماً، وأكّد
  4. انسخ المفتاح — يبدو هكذا: mk_live_8aB3cDe4FgH5iJ6kLm7nOp_a1b2c3d4e5

السر يُعرض مرة واحدة. إذا فقدته يجب إلغاؤه وإنشاء واحد جديد. احفظه في مدير الأسرار، وليس في الكود المصدري.

الخطوة 2 — كيف أجد agent_id ورقم الإرسال (from)؟​

نفس صفحة مفاتيح API تُدرج كل وكلاء مؤسستك تحت قسم "معرّفات الوكلاء" — اضغط على أي معرّف لنسخه إلى الحافظة. الـagent_id هو UUID مثل 12345678-1234-1234-1234-123456789012. ويستطيع مفتاحك أن يخبرك أيضاً: GET /v1/me يؤكد أن المفتاح يعمل، وGET /v1/agents يعرض الوكلاء الذين يستطيع العمل عليهم (راجع مفتاحك ووكلاؤه).

لرقم from، اذهب إلى الاتصالات على الوكيل وانسخ أي رقم واتساب نشط — يبدو مثل +15557654321. إذا قدّمت رقم from لا يطابق أي اتصال نشط، تُخبرك الواجهة بالضبط بالأرقام التي ستعمل في رسالة الخطأ — لا حاجة للتخمين.

الخطوة 3 — كيف أُرسل أول قالب؟​

القوالب معتمدة مسبقاً من ميتا ويمكن إرسالها في أي وقت، حتى خارج نافذة الـ24 ساعة لخدمة العملاء. النص الحر مقيّد بداخل النافذة وموثَّق بشكل منفصل في إرسال رسالة.

لست متأكداً من الاسم الدقيق للقالب أو لغته؟ اعرض قوالب الرقم أولاً: يأتي كل قالب بحالته وبما يلزم تعبئته، ولا تُسلَّم إلا القوالب approved. راجع عرض قوالب واتساب.

curl -X POST https://api.mojeeb.app/v1/whatsapp/templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "12345678-1234-1234-1234-123456789012",
    "from":     "+15557654321",
    "to":       "+15551234567",
    "template": {
      "name":     "arabic_signup_message",
      "language": "ar"
    }
  }'

الاستجابة الناجحة هي HTTP 202 Accepted مع كائن الرسالة، بحالة status: queued في البداية. كل الحقول في مرجع إرسال قالب واتساب.

id هو معرّفك للاستعلام عن الحالة. الـ202 يعني أن الرسالة في طابور الإرسال — التسليم الفعلي يحدث بشكل غير متزامن عبر واجهة WhatsApp Business Cloud من ميتا.

الخطوة 4 — كيف أتحقّق من حالة التسليم؟​

curl https://api.mojeeb.app/v1/whatsapp/messages/01c45011-d803-4eb0-a762-3228a4c392f3 \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"

تتحرّك الحالة عبر queued → sent → delivered → read (أو تنتقل إلى failed). بمجرد قبول ميتا للرسالة، يُعبّأ platform_message_id بـwamid من ميتا للمرجعية في سجلاتهم. تصنيف الحالة الكامل في الاستعلام عن حالة الرسالة.

ما التالي؟​

  • التوثيق — صيغة المفتاح الكاملة، النطاقات، التقييد لكل وكيل
  • الإعادة الآمنة — اجعل إعادات المحاولة آمنة بـIdempotency-Key
  • الأخطاء — كل رمز خطأ مع حالة HTTP والمعنى
  • حدود المعدّل — الافتراضي 60 طلب/دقيقة/مفتاح وكيف تتعامل مع 429
  • مفتاحك ووكلاؤه — أول أدلّة الوكيل: الإعدادات، وجهات الاتصال والعملاء المحتملون، والمعرفة، والقنوات، والفريق، والتحليلات، والاستخدام
  • مرجع الواجهة — العقد الكامل القابل للقراءة آلياً

أسئلة شائعة​

ماذا لو رقم from لا يطابق أي اتصال؟​

ستحصل على 422 from_phone_not_found_for_agent مع available_phones تُدرج كل رقم واتساب نشط على الوكيل. صحّح وأعد المحاولة — لا حاجة لاستعلام آخر لاكتشاف ما هو صالح.

لماذا لم تصل رسالتي؟​

الـ202 يعني أن مجيب وضع الإرسال في الطابور. التسليم قد يفشل في جانب ميتا لأسباب لا يمكننا توقّعها (المستلم حظر رقم العمل، أو كان خارج نافذة الـ24 ساعة لإرسال نص حر، أو القالب غير معتمد في منطقة المستلم). استعلم عن GET /v1/whatsapp/messages/{id} — status: "failed" مع failed_at معبّأ يُخبرك أن الإرسال رُفض في المصب.

هل يمنعني مجيب من إرسال قالب غير معتمد؟​

لا. قبل وضع الإرسال في الطابور، يتحقق مجيب من وجود اسم القالب ولغته على الرقم، أياً كانت حالتهما. فالقالب الذي لا يزال قيد المراجعة أو رُفض يُقبَل بـ202 ثم يفشل لدى ميتا. اعرض قوالب الرقم أولاً وأرسل فقط ما حالته status: approved؛ راجع عرض قوالب واتساب.

هل يمكنني إرسال نفس الرسالة مرّتين بأمان؟​

نعم — أضف رأس Idempotency-Key. أول إرسال يُعيد 202؛ إعادة محاولة مطابقة بنفس المفتاح تُعيد الاستجابة الأصلية. راجع الإعادة الآمنة.