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

يُرسل قالباً معتمداً مسبقاً إلى مستلم واتساب. القوالب يمكن إرسالها في أي وقت، بما في ذلك خارج نافذة خدمة العملاء (24 ساعة) من ميتا — هذه النقطة المناسبة للإرسال الاستباقي مثل تأكيدات الطلبات، تذكيرات المواعيد، ورسائل إعادة الإشراك.

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

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

POST /v1/whatsapp/templates

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

استدعاء أدنى يحتاج إلى وكيل، ورقم إرسال، ومستلم، واسم القالب + اللغة. معظم الإرسالات الفعلية تتضمّن أيضاً parameters لملء المتغيّرات.

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"
    }
  }'

مع متغيّرات الجسم:

curl -X POST https://api.mojeeb.app/v1/whatsapp/templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-shipped" \
  -d '{
    "agent_id": "12345678-1234-1234-1234-123456789012",
    "from":     "+15557654321",
    "to":       "+15551234567",
    "template": {
      "name":     "order_shipped",
      "language": "en",
      "parameters": {
        "customer_name": "Sara",
        "tracking_url":  "https://example.com/track/A123"
      }
    }
  }'

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

ستة حقول إجمالاً. الأربعة الأولى (agent_id، from، to، template.name/language) مطلوبة لأي إرسال. template.parameters اختياري ولا يهم إلا عندما يحوي قالبك متغيّرات يجب ملؤها.

الحقل	النوع	مطلوب	الوصف
agent_id	UUID	نعم	الوكيل المُرسِل.
from	نص E.164	نعم	رقم عمل واتساب المُرسِل.
to	نص E.164	نعم	هاتف المستلم.
template.name	نص	نعم	اسم قالب معتمد من ميتا (مثل order_shipped).
template.language	نص	نعم	علامة لغة BCP-47 (مثل en، ar، en_US).
template.parameters	كائن	لا	خريطة مسطّحة اسم → قيمة لمتغيّرات الجسم.

كيف تعمل متغيّرات القوالب؟

القوالب يمكن أن تحوي متغيّرات في جسمها — مثلاً قالب جسمه Hello {{customer_name}}, your order is on the way: {{tracking_url}}. مرّر القيم كخريطة مسطّحة:

"parameters": {
  "customer_name": "Sara",
  "tracking_url":  "https://example.com/track/A123"
}

في v1 المتغيّرات على مستوى الجسم فقط مدعومة. متغيّرات الرأس (صورة، مستند، فيديو) ومتغيّرات التذييل قد تُضاف لاحقاً كتغييرات إضافية دون كسر العقد القائم.

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

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 المُعاد مع استعلام حالة الرسالة لتتبّع التسليم.

ماذا قد يفشل؟

ظرف الخطأ القياسي. حالات خاصة بالقوالب:

code	HTTP	متى
invalid_template_name	422	template.name مفقود أو فارغ
invalid_request_body	422	حقل مطلوب مفقود — param يُسمي أيهما
from_phone_not_found_for_agent	422	from لا يطابق أي اتصال واتساب نشط — available_phones يُدرج ما يعمل
agent_not_authorized	403	مفتاح API غير مسموح له باستخدام هذا الوكيل

إن لم يكن اسم القالب موجوداً على حساب WhatsApp Business للوكيل، أو لم يكن معتمداً في منطقة المستلم، يُعيد مجيب 202 (لا نُتحقّق مسبقاً مع ميتا). الإرسال ينتقل إلى status: "failed" بمجرد رفض ميتا للتسليم — راجع استعلام حالة الرسالة.

أسئلة شائعة

كيف أُنشئ قالباً؟

القوالب تُنشأ وتُعتمد عبر WhatsApp Business Manager من ميتا، ثم تصبح متاحة للإرسال. هذا إعداد لمرة واحدة لكل قالب، منفصل عن تكامل مجيب. لوحة تحكم مجيب تُظهر قوالبك القائمة تحت اتصال واتساب للوكيل.

ما الفرق بين لغة en و en_US؟

علامات لغة BCP-47. ميتا تستخدمها لاختيار الترجمة الصحيحة للقالب. en هي الإنجليزية العامة؛ en_US هي الإنجليزية الأمريكية تحديداً. استخدم أي علامة لغة اعتُمد قالبك بها.

هل يمكنني حذف parameters إن لم يحوِ قالبي متغيّرات؟

نعم. احذف حقل parameters تماماً (أو مرّر كائناً فارغاً). القوالب بدون متغيّرات تتجاهل المتغيّرات على أي حال.

هل تتحقّق الواجهة من المتغيّرات مقابل متغيّرات القالب المتوقَّعة؟

لا، ليس على طبقة الواجهة. إن احتاج قالبك customer_name ولم تُمرّره، ميتا ترفض الإرسال وسترى status: "failed" على استعلام الحالة. اختبر القوالب الجديدة دائماً بإرسال حقيقي واحد على الأقل قبل الاعتماد عليها في الإنتاج.

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

نعم — استخدم Idempotency-Key. راجع الإعادة الآمنة.