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

البدء السريع

أرسل أول رسالة واتساب في 5 دقائق. هذا الدليل يفترض أن لديك حساب مجيب على خطة 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.

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

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

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

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:

{
  "id":                  "01c45011-d803-4eb0-a762-3228a4c392f3",
  "status":              "queued",
  "agent_id":            "12345678-1234-1234-1234-123456789012",
  "to":                  "+15551234567",
  "type":                "template",
  "platform_message_id": null,
  "created_at":          "2026-04-30T09:18:31Z",
  "sent_at":             null,
  "failed_at":           null
}

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 من ميتا للمرجعية في سجلاتهم. تصنيف الحالة الكامل في الاستعلام عن حالة الرسالة.

ما التالي؟​

أسئلة شائعة​

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

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

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

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

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

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