WhatsApp Template API

API للمطورين

أرسلوا قوالب WhatsApp المعتمدة من أنظمتكم الخاصة باستدعاء API واحد؛ وتستمر المحادثة بعد ذلك في MonoChat.

• WhatsApp
• REST API
• API فقط

التثبيت من MonoStoreاطّلع عليه في monochat.ai

نظرة عامة

يتيح WhatsApp Template API لنظام CRM أو ERP أو موقع التجارة الإلكترونية لديكم، أو لأي نظام خلفي، إرسال رسالة قالب WhatsApp معتمدة إلى عميل عبر MonoChat. يحدد طلب واحد رقم WhatsApp المُرسِل ورقم هاتف العميل والقالب ومتغيراته.

عندما يرد العميل، تصل المحادثة إلى صندوق وارد MonoChat لديكم مثل أي محادثة أخرى. ليس للتطبيق شاشات خاصة: كل شيء يتم عبر ثلاث نقاط نهاية API.

أبرز المزايا

• استدعاء API واحد. أرسلوا قالباً بالاسم واللغة، مع تعبئة متغيرات الرأس والنص والأزرار والشرائح من بياناتكم.
• مباشرة إلى الدردشة. يعيد كل إرسال معرّف المحادثة ورابطاً مباشراً إليها في MonoChat.
• العملاء الجدد مرحّب بهم. إذا لم يكن رقم الهاتف عميلاً بعد، يُنشأ العميل بالاسم الذي ترسلونه.

التثبيت والإعداد

1. اربطوا رقم WhatsApp Business الخاص بكم بـ MonoChat وتأكدوا من أنه موثَّق ولديه قوالب معتمدة من Meta.
2. ثبّتوا WhatsApp Template API من الإعدادات › MonoStore › التطبيقات، أو افتحوا رابط التثبيت app.monochat.ai/apps/K6u29LpbwCHBozZ8o. إذا لم يكن لديكم حساب MonoChat، يتيح لكم الرابط التسجيل أولاً ثم يثبّت التطبيق لكم.
3. أنشئوا رمز API من الملف الشخصي › رموز API. يظهر الرمز مرة واحدة فقط، لذا انسخوه فوراً.
4. استدعوا template/list.js لرؤية قوالبكم المعتمدة ومتغيراتها.
5. استدعوا template/send.js مع رقم العميل وقيم المتغيرات لإرسال أول قالب.

ملاحظة

• تُحاسَب كل رسالة مثل أي رسالة قالب تُرسل من MonoChat.
• يجب أن تظل روابط الوسائط متاحة حتى ينتهي WhatsApp من جلب الملف.
• أرسلوا إلى العملاء الذين وافقوا على تلقي رسائلكم: قد يقيّد WhatsApp الأرقام التي تُحظر رسائلها أو يُبلَّغ عنها.

الميزات

عرض القوالب

القوالب المعتمدة لرقم WhatsApp، مع لغتها وفئتها وحالتها ومتغيراتها، ليعرف نظامكم ما يمكنه إرساله.

إرسال قالب

بحسب اسم القالب ولغته، مع متغيرات الرأس والنص والأزرار والشرائح. أي قيمة ناقصة توقف الإرسال، فلا يصل إلى العميل شيء مكتمل جزئياً.

إسناد إلى موظف

أعطوا البريد الإلكتروني لموظف وتُفتح المحادثة باسمه.

رؤوس الوسائط

احصلوا على بيانات رفع قصيرة الأجل، وضعوا صورة أو فيديو أو مستنداً في تخزين MonoChat، واستخدموا رابطه كرأس للقالب.

رابط المحادثة

يعيد كل إرسال معرّف الجلسة ومعرّف الرسالة ورابطاً يفتح المحادثة في MonoChat.

أخطاء واضحة

يوضح الاستدعاء الفاشل ما الذي حدث، مثل “Channel not found” أو “Variable missing”.

قبل أن تبدؤوا

• رقم WhatsApp Business الخاص بكم مرتبط بـ MonoChat وموثَّق. راجعوا القنوات.
• القوالب التي تريدون إرسالها معتمدة من Meta. القوالب هي وسيلتكم للكتابة أولاً، أو للوصول إلى عميل خارج نافذة 24 ساعة. راجعوا رسائل القوالب.
• لديكم رمز API من الملف الشخصي › رموز API. راجعوا رموز API.
• تعرفون tenant slug الخاص بكم: الجزء الذي يلي /tenants/ في عنوان MonoChat الخاص بكم. في https://app.monochat.ai/tenants/mybusiness يكون الـ slug هو mybusiness.

مرجع API

ليس للتطبيق شاشات خاصة. كل شيء يتم عبر ثلاث نقاط نهاية، كل منها طلب POST بجسم JSON:

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

نقطة النهاية	ما تفعله
template/list.js	تعرض قوالب أحد أرقام WhatsApp لديكم، مع متغيراتها.
template/send.js	ترسل قالباً إلى عميل وتعيد رابطاً إلى المحادثة.
upload/get-token.js	تعطي بيانات رفع قصيرة الأجل لصورة أو فيديو أو مستند يُستخدم كرأس.

تُكتب أرقام الهواتف دائماً مع رمز الدولة وبدون +، مثل 905334445566. يردّ الاستدعاء الناجح بالحالة 200 مع بيانات نقطة النهاية ضمن result.

1. عرض القوالب

POST /api/<slug>/custom-functions/template-app/api/template/list.js

يعرض كل قوالب رقم WhatsApp Business المحدد: الاسم، ورمز اللغة، والفئة، والمكوّنات (الرأس، والنص، والتذييل، والأزرار)، وأنواع المتغيرات، وحالة الاعتماد.

الحقل	مطلوب	الوصف
phoneNumber	نعم	رقم WhatsApp Business الخاص بكم في MonoChat، مع رمز الدولة وبدون +.
options	لا	التقسيم إلى صفحات والمرشِّحات، مثل { "pagination": { "currentPage": 1, "pageItems": 50 } }.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

الاستجابة (مختصرة):

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

كيف تقرؤون الاستجابة:

• name: اسم النظام الذي ترسلون به القالب.
• languageCode: اللغة التي يُرسل بها.
• category: فئة WhatsApp (MARKETING أو UTILITY أو AUTHENTICATION).
• components: الأجزاء التي يتكوّن منها القالب.

المكوّن	المحتوى	الوصف
HEADER	IMAGE أو VIDEO أو DOCUMENT أو نص	يُذكر format للوسائط؛ وتظهر المتغيرات ضمن variables.
BODY	نص مع متغيرات	نص الرسالة، مع عناصر نائبة مثل {{1}} و{{2}}.
FOOTER	نص	عادةً بلا متغيرات.
BUTTONS	رابط URL، رد سريع…	نصوص الأزرار ومتغيراتها إن وُجدت.

يحتاج القالب المثال أعلاه إلى صورة واحدة للرأس ونصّين للنص الأساسي (اسم العميل واسم المنتج). التذييل ثابت ("Teşekkürler") ولا توجد أزرار.

2. إرسال قالب

POST /api/<slug>/custom-functions/template-app/api/template/send.js

يرسل قالباً معتمداً إلى عميل. إذا لم يكن رقم الهاتف عميلاً بعد، يُنشأ العميل؛ وتُفتح المحادثة (أو يُعاد استخدامها) ويُرسل القالب فيها.

الحقل	مطلوب	الوصف
phoneNumber	نعم	رقم WhatsApp Business الذي يُرسل منه. يجب أن يكون مرتبطاً بـ MonoChat وموثَّقاً.
templateMessageName	نعم	name القالب، تماماً كما تعيده القائمة.
languageCode	نعم	لغة القالب، كما تعيدها القائمة (مثل tr-TR).
customerPhoneNumber	نعم	رقم WhatsApp الخاص بالعميل.
variables	عندما يحتوي القالب على متغيرات	قيم متغيرات القالب (انظر أدناه).
customerFirstName, customerLastName	لا	تُستخدم عندما يكون العميل جديداً على MonoChat.
agentEmailAddress	لا	تُسند المحادثة إلى الموظف الذي يحمل هذا البريد الإلكتروني.

المتغيرات. لكل عنصر في المصفوفة variables حقل type وقائمة parameters، مرتّبة بحسب ترتيب العناصر النائبة في القالب:

type	parameters
HEADER	متغير نص الرأس، أو الرابط العام لصورة الرأس أو الفيديو أو المستند.
BODY	قيم {{1}} و{{2}} و… في النص الأساسي بالترتيب.
BUTTONS	قيمة واحدة لكل زر فيه متغير (مثل الجزء الديناميكي من زر رابط URL أو رمز قسيمة)، بترتيب الأزرار.
CAROUSEL	بدلاً من parameters، مصفوفة cards فيها عنصر لكل شريحة، ولكل منها components خاصة بها.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

أي قيمة ناقصة توقف الإرسال برسالة Variable missing، فلا يصل إلى العميل شيء مكتمل جزئياً. نادراً ما يحتوي FOOTER على متغيرات.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

الاستجابة:

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

• url: يفتح المحادثة في MonoChat، للأشخاص الذين سجّلوا الدخول ويُسمح لهم برؤيتها.
• sessionId: معرّف المحادثة.
• messageId: معرّف الرسالة في MonoChat. تظهر حالة تسليمها وقراءتها في الدردشة مثل أي رسالة أخرى.

الوسائط في القوالب. ينزّل WhatsApp وسائط الرأس من الرابط الذي تعطونه، لذا يجب أن يكون الرابط صالحاً ومتاحاً للعموم. الروابط التي تتطلب تسجيل دخول لا تعمل. وإذا رفعتم الملف عبر upload/get-token.js، فاستخدموا رابط الملف المبني من تلك الإجابة.

3. رفع وسائط للرأس

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

عندما يكون رأس القالب صورة أو فيديو أو مستنداً، يحتاج الملف إلى عنوان عام يستطيع WhatsApp تنزيله منه. تمنحكم نقطة النهاية هذه إذناً قصير الأجل لوضع الملف في تخزين MonoChat.

الحقل	مطلوب	الوصف
fileName	نعم	اسم الملف مع امتداده، مثل product.jpg أو promo.pdf.

تُخزَّن الملفات دائماً في مجلد chat-assets الخاص بمساحة عملكم؛ وتبقى الأمثلة القديمة التي ترسل حقل key تعمل، فالقيمة غير مطلوبة.

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

تخبركم الإجابة بمكان وضع الملف وتعطيكم بيانات اعتماد للقيام بذلك:

الحقل	الوصف
bucket, region, path	المكان الذي يوضع فيه الملف.
temporaryCredentials	بيانات اعتماد للرفع فقط لهذا المسار وحده، صالحة لمدة 15 دقيقة.
baseUrl	العنوان العام للتخزين. رابط الملف هو baseUrl + / + path.

ارفعوا الملف فوراً بأي عميل S3 باستخدام بيانات الاعتماد هذه، ثم مرّروا رابطه كمعامل HEADER عند إرسال القالب. تفشل الملفات الكبيرة جداً أو الصيغ التي لا يدعمها WhatsApp (يقبل صيغ الصور والفيديو وPDF الشائعة).

مثال: قالب برأس صورة

لنفترض أن لديكم قالباً معتمداً اسمه new_product_announcement برأس صورة ومتغيرين في النص (اسم العميل واسم المنتج)، وتريدون إرساله إلى عميل.

1. اعرضوا القوالب. استدعوا template/list.js مع رقم WhatsApp الخاص بكم وابحثوا عن new_product_announcement. تُظهر مكوّناته متغير IMAGE واحداً في الرأس ومتغيرين TEXT في النص.
2. ارفعوا الصورة. استدعوا upload/get-token.js مع { "fileName": "urun.jpg" }، وارفعوا الملف ببيانات الاعتماد المُعادة، وابنوا رابطه من baseUrl وpath.
3. أرسلوا القالب. استدعوا template/send.js مع رابط الملف كمعامل HEADER و["Ayşe", "XYZ Telefon"] كمعاملات BODY ({{1}} ← Ayşe، {{2}} ← XYZ Telefon). وإذا كان للقالب متغيرات في الأزرار فأضيفوا عنصر BUTTONS بالطريقة نفسها.
4. افتحوا الدردشة. يفتح url في الإجابة المحادثة؛ وعندما يرد العميل تستمر في صندوق وارد MonoChat لديكم.

الأخطاء

يردّ الاستدعاء الفاشل بحالة خطأ ورسالة توضح ما الذي حدث. سجّلوا هذه الرسائل في نظامكم وأظهروا رسالة مفهومة لمستخدميكم عند الحاجة.

الرسالة	السبب
phoneNumber field is required	استُدعي template/list.js بدون phoneNumber.
phoneNumber, templateMessageName, customerPhoneNumber fields are required	حقل مطلوب في template/send.js مفقود.
Channel not found	الـ phoneNumber ليس رقم WhatsApp في مساحة عملكم.
Channel is not verified	رقم WhatsApp مرتبط لكنه غير موثَّق.
Template message not found	لا يوجد قالب معتمد بهذا الاسم واللغة على الرقم. تحققوا من الإملاء ومن languageCode.
Template message is not approved	القالب موجود لكنه غير معتمد من Meta.
Variable missing: …	variables لا يطابق القالب، مثلاً يحتاج القالب إلى قيمتين في النص وأرسلتم واحدة.
Agent user not found	لا يوجد موظف بالبريد الإلكتروني في agentEmailAddress.
Customer Channel not found	تعذّر إنشاء هوية WhatsApp الخاصة بالعميل أو العثور عليها.

رموز حالة HTTP التي قد تراها:

• 401 Unauthorized: ترويسة Authorization: Bearer <API_TOKEN> مفقودة، أو الرمز خاطئ أو منتهي الصلاحية. استخدموا رمزاً صالحاً من حسابكم.
• 403 Forbidden: ليس للرمز صلاحية الوصول إلى مساحة العمل أو التطبيق هذا، مثلاً tenant slug خاطئ.
• 404 Not Found: عنوان نقطة النهاية خاطئ. تحققوا من المسار الكامل /api/<slug>/custom-functions/template-app/api/....
• 500 Internal Server Error: مشكلة غير متوقعة في MonoChat أو لدى مزوّد WhatsApp، أو رفض من جهة WhatsApp (الرقم ليس على WhatsApp، أو حظركم العميل، أو حدود الجودة أو المعدل). أعيدوا المحاولة لاحقاً وتواصلوا مع دعم MonoChat إن استمرت المشكلة.

لقطات الشاشة

إرسال قالب WhatsApp معتمد من نظام CRM أو ERP أو تجارة إلكترونية باستدعاء API واحد عبر MonoChatقائمة قوالب WhatsApp المعتمدة مع متغيراتهاإرسال قالب إلى رقم جديد ينشئ العميل تلقائياًقالب واحد مُرسَل بعدة لغاتقوالب برؤوس صور وفيديو ومستندات وPDF

الأسئلة الشائعة

هل لدى WhatsApp Template API واجهة مستخدم؟

لا. إنه تطبيق API فقط بثلاث نقاط نهاية: عرض القوالب، وإرسال قالب، والحصول على بيانات الرفع لرؤوس الوسائط.

ماذا أحتاج قبل أن أستخدمه؟

رقم WhatsApp Business مرتبط بـ MonoChat وموثَّق، وقوالب معتمدة من Meta، ورمز API من الملف الشخصي › رموز API.

ماذا يحدث عندما يرد العميل؟

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

هل يمكنني الإرسال إلى رقم ليس عميلاً بعد؟

نعم. إذا لم يكن رقم الهاتف عميلاً بعد، يُنشأ العميل بالاسم الذي ترسلونه.

كم تبلغ تكلفة رسائل القوالب؟

تُحاسَب كل رسالة مثل أي رسالة قالب تُرسل من MonoChat. تسعّر Meta القوالب بحسب الفئة وبلد المستلم؛ استخدموا حاسبة تكلفة الرسائل الجماعية على WhatsApp لتقدير تكلفة الإرسال.

ذات صلة

• Session Link
• Bulk Template Message API
• رسائل القوالب
• تطبيقات MonoStore