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

إنشاء قوالب واتساب وإدارتها

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

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

اعثر على id قناة الرقم كما في عرض القوالب، ثم أرسل القالب بـ POST:

curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/connections/YOUR_CONNECTION_ID/whatsapp-templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name":          "order_shipped",
    "language":      "en",
    "category":      "utility",
    "body":          "Hi {{1}}, your order {{2}} is on its way.",
    "body_examples": { "1": "Sara", "2": "A-100" },
    "footer":        "Acme Clinics",
    "buttons": [
      { "type": "url", "text": "Track order", "url": "https://example.com/track/{{1}}", "example": "A-100" }
    ]
  }'

يكون الجواب 201 مع القالب، وحالته عادةً status: pending. وكل الحقول في مرجع إنشاء قالب.

كيف تعمل المتغيّرات والعيّنات؟​

اكتب المتغيّرات بالأرقام {{1}} و{{2}} وهكذا بالترتيب، أو بأسماء بأحرف صغيرة مثل {{first_name}}، بأسلوب واحد في الرأس والجسم معاً. وتراجع ميتا القالب بقيم تجريبية، فأعطِ عيّنة لكل متغيّر: body_examples تربط كل متغيّر في الجسم بعيّنته، بمفاتيح مثل مفاتيح parameters في الإرسال ("1" أو "first_name")، وheader.example هي عيّنة المتغيّر الوحيد في الرأس النصي.

كيف أضيف رأساً بصورة أو فيديو أو مستند؟​

حدّد header.format وأعطِ header.media_url، وهو رابط https لملف تجريبي. ينزّله مجيب مرة واحدة ويسلّمه لميتا للمراجعة. وحين ترسل القالب تستطيع إرسال ملف مختلف عبر template.header_media_url. ويجب أن يجيب الرابط بالملف نفسه، ونوعُه في Content-Type، من عنوان عام؛ فإعادة التوجيه لا تُتّبع. ويذكر المرجع أنواع الملفات والحجم الذي يقبله مجيب.

ما الأزرار التي يمكن أن يحملها القالب؟​

الردود السريعة، والروابط (url، وقد ينتهي بـ {{1}} يملؤه الإرسال)، ورقم هاتف واحد، وزر نسخ رمز واحد. أبقِ الردود السريعة معاً، قبل الأزرار الأخرى أو بعدها. أما رأس الموقع الجغرافي، والقوالب الدوّارة (carousel)، وعروض الوقت المحدود، وأزرار الكتالوج وFlow، فتُنشأ في WhatsApp Manager، لأن مجيب لا يستطيع إرسالها بعد.

كيف أنشئ قالب رمز تحقق؟​

اجعل category بقيمة authentication، وصِف زر الرمز في otp. يتيح copy_code للعميل نسخ الرمز، أما one_tap وzero_tap فيسلّمانه إلى تطبيقك على أندرويد المذكور في supported_apps. وتكتب ميتا الرسالة بنفسها بلغة القالب، ولا تختار أنت إلا إضافة سطر الأمان من عدمها ومتى ينتهي الرمز:

{
  "name": "login_code",
  "language": "en",
  "category": "authentication",
  "otp": { "type": "copy_code", "add_security_recommendation": true, "code_expiration_minutes": 10 }
}

ولإرساله أعطِ الرمز في "1" الخاص بالجسم وفي otp_code الخاص بالزر؛ راجع إرسال قالب واتساب.

كيف أعرف متى تعتمده ميتا؟​

اقرأ القالب بـ GET على id الخاص به (جلب قالب) حتى لا تبقى status بقيمة pending. القالب approved يمكن إرساله، والقالب rejected يذكر السبب في rejected_reason. وقد تستغرق مراجعة ميتا يوماً، فتحقّق كل بضع دقائق لا كل ثانية: نقاط نهاية القوالب تتشارك حد معدّل صغيراً تشرحه حدود المعدّل.

كيف أعدّل قالباً؟​

أرسل محتواه كاملاً بـ PUT إلى id الخاص به. تستبدل ميتا كل أجزاء القالب عند التعديل، فأرسل كل ما يجب أن يقوله لا التغيير وحده. ولا يتغيّر الاسم ولا اللغة؛ ولا ترسل category لتبقى كما هي. والرأس الذي فيه وسائط ويُرسل دون media_url يحتفظ بعيّنته، أما الرأس الذي يتغيّر نوعه فيحتاج media_url. وتسمح ميتا بتعديل القالب المعتمد مرة في اليوم وعشر مرات في الشهر، وتراجع كل تعديل؛ والمحتوى المطابق لما لدى ميتا لا يُرسل ولا يستهلك تعديلاً. أما قالب رمز التحقق، وmessage_send_ttl_seconds، وmedia_url الجديد، فتُعدّ تغييراً دائماً، لأن قائمة ميتا لا تعرضها للمقارنة. راجع مرجع تعديل قالب.

كيف أحذف قالباً؟​

احذفه بـ DELETE حسب id. يحذف هذا نسخة اللغة تلك وحدها، وتبقى لغاته الأخرى. وحذف قالب معتمد أو موقوف مؤقتاً يحجز اسمه لدى ميتا 30 يوماً، فأضف ?acknowledge_name_lock=true؛ ودونه تجيب الواجهة بـ 409 template_delete_locks_name مع التاريخ. ولا يمكن استعادة القالب المحذوف. راجع مرجع حذف قالب.

لماذا رُفض قالبي؟​

لا يُرسل شيء إلى ميتا حتى يتّبع القالب قواعد ميتا التي يستطيع مجيب التحقق منها:

  • 422 invalid_request_body: جزء لا تقبله فئته، أو متغيّر دون عيّنة، أو أزرار بترتيب خاطئ. ويسمّي param الحقل، مثل buttons[1].url.
  • 422 template_header_media_url_invalid: لم يستطع مجيب تنزيل عيّنة الرأس؛ وتذكر الرسالة السبب.
  • 422 template_rejected: رفضت ميتا القالب، والرسالة هي سبب ميتا. والتعديل الذي لا تقبله ميتا، مثل فئة جديدة لقالب معتمد، يُرفض بالطريقة نفسها قبل أن يصل إليها.
  • 409 template_name_taken: لدى الرقم قالب بهذا الاسم بهذه اللغة.
  • 409 template_status_not_allowed أو template_edit_limit_reached أو template_in_use_by_broadcast: لا يمكن تغيير القالب الآن.

وتسرد الأخطاء كل الرموز.

أسئلة شائعة​

هل أستطيع إعادة محاولة إنشاء انتهت مهلته؟​

نعم. إن كان الأول قد وصل إلى ميتا، فستجيب إعادة المحاولة بـ 409 template_name_taken، لأن الاسم صار موجوداً بتلك اللغة. اعرض القائمة لتجده. ولا يحتاج الإنشاء إلى Idempotency-Key.

هل تظهر القوالب المنشأة عبر الواجهة في لوحة التحكم؟​

نعم. القوالب محفوظة لدى ميتا في حساب واتساب للأعمال الخاص بالرقم، فتعرضها كلها صفحة واتساب في لوحة التحكم وWhatsApp Manager، أياً كانت طريقة إنشائها.

ما النطاقات التي تحتاجها هذه الاستدعاءات؟​

whatsapp_templates:write لإنشاء القوالب وتعديلها وحذفها، وwhatsapp:read لقراءتها. ويحملهما كل مفتاح اليوم؛ راجع التوثيق.

هل يستطيع مساعد ذكاء اصطناعي إنشاء القوالب؟​

نعم. عبر خادم MCP يستطيع المساعد إنشاء القوالب وقراءتها وتعديلها، لكنه لا يحذفها أبداً.