الرد الجاهز إجابة يكتبها فريقك مرة واحدة ويرسلها بنقرتين من صندوق الرسائل، وترسلها مسارات العمل تلقائياً. وعبر الواجهة البرمجية يستطيع التكامل إبقاء هذه الإجابات متوافقة مع نظام آخر: كتحديث الأسعار في رد ما عند تغيّر كتالوجك، أو إضافة رد لكل فرع جديد.
لمعرفة كيف يستخدم أعضاء الفريق الردود الجاهزة في التطبيق، راجع الردود الجاهزة.
| الإجراء | إمكانية المفتاح | صلاحية عضو الفريق |
|---|---|---|
| القائمة والعرض | predefined-response-index |
عرض الردود الجاهزة |
| الإنشاء | predefined-response-create |
إنشاء رد جاهز جديد |
| التعديل | predefined-response-update |
تعديل رد جاهز |
| الحذف | predefined-response-delete |
حذف رد جاهز |
يتوقف عدد الردود الجاهزة الذي يستطيع الحساب امتلاكه على الباقة. راجع الباقات في صفحة الأسعار.
لكل رد جاهز نوع type يحدد ما يحمله وأين يمكن إرساله:
type |
subtype |
يحمل | يُرسل عبر |
|---|---|---|---|
general |
- | نصاً أو مرفقات أو كليهما | كل القنوات |
instagram |
generic |
مجموعة بطاقات متتالية | انستغرام |
whatsapp |
button |
رسالة فيها حتى 3 أزرار رد | واتساب |
whatsapp |
interactive_list |
رسالة فيها قائمة يختار منها العميل | واتساب |
whatsapp |
interactive_url |
رسالة فيها زر يفتح رابطاً | واتساب |
whatsapp |
location_request_message |
رسالة تطلب من العميل مشاركة موقعه | واتساب |
يأتي المحتوى ضمن template، ويتبع شكله نوع الرد، كما تُظهر الأمثلة في إنشاء رد جاهز.
{
"_id": "6659e1f2a3b4c5d6e7f8a901",
"name": "ساعات العمل",
"type": "general",
"subtype": null,
"template": {
"type": "general",
"description": "نستقبلكم يومياً من 9 صباحاً حتى 9 مساءً، وتجدون قائمة الطعام مرفقة.",
"attachments": [
{
"url": "https://files.example.com/spring-menu.pdf",
"media_type": "application/pdf",
"type": "application",
"subtype": "pdf",
"file_size": 245760,
"caption": null,
"file_name": "spring-menu.pdf",
"source": "upload",
"purpose": "media",
"unavailable": false
}
]
},
"account_id": 1024,
"updated_at": "2026-10-20T09:30:00.000000Z",
"created_at": "2026-10-20T09:30:00.000000Z"
}
لا تحتوي الردود الجاهزة على متغيرات، ويُرسل النص كما كُتب تماماً.
GET https://app.alaaqat.com/api/conversations/predefined-responses
تعرض هذه النقطة الردود الجاهزة في حسابك.
تقبل هذه النقطة معطيات الصفحات.
| المفتاح | النوع | الافتراضي | الوصف |
|---|---|---|---|
| search | نص | - | البحث حسب الاسم. |
| filters[types][] | نص | - | الردود من هذا النوع type فقط. كرّره لأكثر من نوع. |
| filters[workflow_connection] | نص | - | connected للردود التي يرسلها أحد مسارات العمل، وnot_connected لغيرها. |
GET https://app.alaaqat.com/api/conversations/predefined-responses?filters[types][]=whatsapp&search=order
200 OK، أو 206 Partial Content إذا تبقّت صفحات أخرى. ويحمل كل رد أيضاً الحقل workflows: مسارات العمل التي ترسله،
مع قيمة _id لكل منها واسمه name وهل هو مفعّل.
{
"data": [
{
"_id": "6659e1f2a3b4c5d6e7f8a902",
"name": "الطلب جاهز",
"type": "whatsapp",
"subtype": "button",
"template": {
"type": "button",
"header": {
"type": "text",
"text": "طلبك جاهز"
},
"body": {
"text": "هل تفضّل أن نوصله إليك، أم ستستلمه بنفسك؟"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "delivery",
"title": "أوصلوه إليّ"
}
},
{
"type": "reply",
"reply": {
"id": "pickup",
"title": "سأستلمه بنفسي"
}
}
]
}
},
"account_id": 1024,
"updated_at": "2026-10-20T09:40:00.000000Z",
"created_at": "2026-10-20T09:40:00.000000Z",
"workflows": [
{
"_id": "665ae1f2a3b4c5d6e7f8a911",
"name": "ردود حالة الطلب",
"is_active": true
}
]
}
],
"links": {
"first": "https://app.alaaqat.com/api/conversations/predefined-responses?page=1",
"last": "https://app.alaaqat.com/api/conversations/predefined-responses?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://app.alaaqat.com/api/conversations/predefined-responses",
"per_page": 15,
"to": 1,
"total": 1
}
}
GET https://app.alaaqat.com/api/conversations/predefined-responses/{_id}
حيث _id هو قيمة _id للرد الجاهز. تُرجع هذه النقطة رداً واحداً ضمن data بشكل كائن الرد الجاهز، وتحتاج
إلى الإمكانية نفسها التي تحتاجها القائمة: predefined-response-index.
POST https://app.alaaqat.com/api/conversations/predefined-responses
تُنشئ هذه النقطة رداً جاهزاً. يأخذ كل نوع هذين الحقلين، إضافة إلى حقول نوعه المذكورة أدناه:
| الحقل | مطلوب | التحققات | الوصف |
|---|---|---|---|
| name | مطلوب | نص حتى 30 حرفاً للنوع general، وحتى 150 حرفاً لبقية الأنواع |
الاسم الذي يختار به فريقك الرد، ولا يراه العملاء. |
| type | مطلوب | general أو instagram أو whatsapp |
ما يحمله الرد. |
يجب إرسال الرد الذي يحمل ملفات، كالمرفقات أو صورة البطاقة، بصيغة multipart/form-data، أما الرد النصي فقط فيمكن إرساله
بصيغة JSON.
تكون الاستجابة 201 Created، ويأتي الرد الجديد ضمن data.
| الحقل | مطلوب | التحققات | الوصف |
|---|---|---|---|
| description | مطلوب إن لم تُرسل attachments |
نص من 3 أحرف على الأقل | نص الرد. |
| attachments[] | مطلوب إن لم يُرسل description |
ملفات، حجم كل منها 1 كيلوبايت على الأقل | الملفات التي تُرسل مع النص. |
يمكن أن تكون المرفقات صوراً (PNG وJPG)، أو مقاطع فيديو (MP4)، أو ملفات صوتية (AAC وWAV وMP3 وOGG وWebM)، أو مستندات (PDF وWord وExcel وPowerPoint). ويصل حجم الصورة إلى نحو 5 ميغابايت، والفيديو إلى نحو 25 ميغابايت، والملف الصوتي إلى نحو 16 ميغابايت. ويحوّل نظام علاقات الملفات الصوتية إلى صيغة تقبلها كل القنوات.
مُرسلاً بصيغة multipart/form-data:
name: ساعات العمل
type: general
description: نستقبلكم يومياً من 9 صباحاً حتى 9 مساءً، وتجدون قائمة الطعام مرفقة.
attachments[0]: (الملف spring-menu.pdf)
وتبقى حدود الملفات الخاصة بكل قناة سارية عند إرسال الرد، راجع إرسال الرسائل.
مجموعة بطاقات متتالية. اجعل subtype يساوي generic، وصِف كل بطاقة ضمن elements. ويعرض انستغرام حتى 10 بطاقات.
| الحقل | مطلوب | التحققات | الوصف |
|---|---|---|---|
| subtype | مطلوب | generic |
|
| elements[].title | مطلوب | نص حتى 80 حرفاً | عنوان البطاقة. |
| elements[].subtitle | اختياري | نص من 3 إلى 80 حرفاً | السطر الذي يلي العنوان. |
| elements[].image | اختياري | ملف صورة حتى 16 ميغابايت | صورة البطاقة. |
| elements[].default_action.type | اختياري | web_url |
يفتح رابطاً عندما ينقر العميل على البطاقة. |
| elements[].default_action.url | مطلوب مع default_action |
رابط | الرابط الذي تفتحه البطاقة. |
| elements[].buttons[] | اختياري | حتى 3 أزرار | أزرار البطاقة. |
| elements[].buttons[].type | مطلوب | web_url أو postback أو phone_number |
يفتح رابطاً، أو يرسل رداً، أو يتصل برقم. |
| elements[].buttons[].title | مطلوب | نص حتى 20 حرفاً | عنوان الزر. |
| elements[].buttons[].url | مطلوب للنوع web_url |
رابط | الرابط الذي يفتحه الزر. |
| elements[].buttons[].payload | مطلوب للنوع phone_number |
نص | رقم الهاتف الذي يُتصل به. |
{
"name": "عرض الكرسي",
"type": "instagram",
"subtype": "generic",
"elements": [
{
"title": "كرسي مكتب مريح",
"subtitle": "ارتفاع قابل للتعديل وظهر شبكي أسود",
"buttons": [
{
"type": "web_url",
"title": "اطلب الآن",
"url": "https://shop.example.com/chair"
},
{
"type": "phone_number",
"title": "اتصل بنا",
"payload": "+96265000000"
}
]
}
]
}
رسالة واتساب تفاعلية. اجعل subtype أحد الأنواع الأربعة أدناه. ويأخذ كل نوع الحقل body.text، وهو نص الرسالة الأساسي،
حتى 1,024 حرفاً.
أزرار الرد (button): يجيب العميل بالنقر على أحد الأزرار.
| الحقل | مطلوب | التحققات | الوصف |
|---|---|---|---|
| header.type | اختياري | text أو image أو video أو document |
ما تعرضه الترويسة. |
| header.text | اختياري | نص حتى 60 حرفاً | الترويسة، عندما يكون header.type هو text. |
| header.attachment | اختياري | ملف | ملف الترويسة، عندما يكون header.type هو image أو video أو document. |
| body.text | مطلوب | نص حتى 1,024 حرفاً | الرسالة. |
| footer.text | اختياري | نص حتى 60 حرفاً | سطر قصير تحت الرسالة. |
| action.buttons[] | مطلوب | من زر إلى 3 أزرار | |
| action.buttons[].reply.id | مطلوب | نص حتى 256 حرفاً | معرّف تختاره، ويعود إليك عندما ينقر العميل على الزر. |
| action.buttons[].reply.title | مطلوب | نص حتى 20 حرفاً | عنوان الزر. |
{
"name": "الطلب جاهز",
"type": "whatsapp",
"subtype": "button",
"header": {
"type": "text",
"text": "طلبك جاهز"
},
"body": {
"text": "هل تفضّل أن نوصله إليك، أم ستستلمه بنفسك؟"
},
"action": {
"buttons": [
{
"reply": {
"id": "delivery",
"title": "أوصلوه إليّ"
}
},
{
"reply": {
"id": "pickup",
"title": "سأستلمه بنفسي"
}
}
]
}
}
القائمة (interactive_list): يفتح العميل قائمة ويختار منها سطراً واحداً.
| الحقل | مطلوب | التحققات | الوصف |
|---|---|---|---|
| header.text | اختياري | نص حتى 60 حرفاً | ترويسة نصية. |
| body.text | مطلوب | نص حتى 1,024 حرفاً | الرسالة. |
| footer.text | اختياري | نص حتى 60 حرفاً | سطر قصير تحت الرسالة. |
| action.button | مطلوب | نص حتى 20 حرفاً | عنوان الزر الذي يفتح القائمة. |
| action.sections[] | مطلوب | حتى 10 أقسام، تضم 10 أسطر في المجموع | مجموعات الأسطر. |
| action.sections[].title | مطلوب | نص حتى 24 حرفاً | عنوان القسم. |
| action.sections[].rows[].id | مطلوب | نص حتى 200 حرف | معرّف تختاره، ويعود إليك عندما يختار العميل السطر. |
| action.sections[].rows[].title | مطلوب | نص حتى 24 حرفاً | عنوان السطر. |
| action.sections[].rows[].description | اختياري | نص حتى 72 حرفاً | سطر تحت عنوان السطر. |
{
"name": "الفروع",
"type": "whatsapp",
"subtype": "interactive_list",
"body": {
"text": "أي فرع تودّ زيارته؟"
},
"action": {
"button": "عرض الفروع",
"sections": [
{
"title": "عمّان",
"rows": [
{
"id": "abdoun",
"title": "عبدون",
"description": "من 9 صباحاً حتى 9 مساءً"
},
{
"id": "sweifieh",
"title": "الصويفية",
"description": "من 10 صباحاً حتى 10 مساءً"
}
]
}
]
}
}
زر رابط (interactive_url): زر يفتح صفحة ويب.
| الحقل | مطلوب | التحققات | الوصف |
|---|---|---|---|
| header.type وheader.text وheader.attachment | اختياري | كما في أزرار الرد | الترويسة. |
| body.text | مطلوب | نص حتى 1,024 حرفاً | الرسالة. |
| footer.text | اختياري | نص حتى 60 حرفاً | سطر قصير تحت الرسالة. |
| action.parameters.display_text | مطلوب | نص حتى 20 حرفاً | عنوان الزر. |
| action.parameters.url | مطلوب | رابط | الصفحة التي يفتحها الزر. |
{
"name": "الكتالوج",
"type": "whatsapp",
"subtype": "interactive_url",
"body": {
"text": "صدر كتالوجنا الجديد، اطّلع على عروض هذا الموسم."
},
"action": {
"parameters": {
"display_text": "افتح الكتالوج",
"url": "https://shop.example.com/catalogue"
}
}
}
طلب الموقع (location_request_message): يطلب من العميل مشاركة موقعه.
| الحقل | مطلوب | التحققات | الوصف |
|---|---|---|---|
| body.text | مطلوب | نص حتى 1,024 حرفاً | الرسالة. |
{
"name": "طلب الموقع",
"type": "whatsapp",
"subtype": "location_request_message",
"body": {
"text": "شاركنا موقعك من فضلك لنرسل إليك أقرب سائق."
}
}
يحسب واتساب هذه الحدود بالأحرف الظاهرة، فيُعدّ الرمز التعبيري حرفاً واحداً. أما نظام علاقات فقد يعدّ بعض الرموز التعبيرية حرفين أو ثلاثة، فاترك هامشاً عند استخدامها.
PUT https://app.alaaqat.com/api/conversations/predefined-responses/{_id}
حيث _id هو قيمة _id للرد الجاهز. أرسل الرد كاملاً من جديد، بما فيه name وtype، بالحقول نفسها التي
أنشأته بها، فما ترسله يحلّ محل المحتوى الحالي.
أما الملفات التي لا ترسلها من جديد فتبقى: إذا لم ترسل attachments أو image البطاقة أو attachment الترويسة، يبقى
الملف الحالي. وأرسل ملفاً جديداً في الموضع نفسه لاستبداله.
{info} لا تستطيع معظم أدوات HTTP إرسال الملفات مع
PUT. لاستبدال ملف، أرسل التعديل بطلبPOSTإلى الرابط نفسه بصيغةmultipart/form-data، مع حقل إضافي_methodقيمتهPUT.
تكون الاستجابة 200 OK، ويأتي الرد بعد التعديل ضمن data.
DELETE https://app.alaaqat.com/api/conversations/predefined-responses/{_id}
حيث _id هو قيمة _id للرد الجاهز. تحذف هذه النقطة الرد وملفاته.
لا يمكن حذف رد يرسله أحد مسارات العمل: يُرفض الطلب بالرمز 403، وتذكر الرسالة أسماء مسارات العمل تلك. أزل الرد منها
أولاً.
تكون الاستجابة 200 OK:
{
"message": "Entity was deleted successfully.",
"data": []
}
| الرمز | المعنى |
|---|---|
| 402 | وصل حسابك إلى حد الردود الجاهزة في باقتك. راجع الباقات في صفحة الأسعار. |
| 403 | المفتاح لا يحمل الإمكانية، أو عضو الفريق لا يملك الصلاحية. وعند التعديل والحذف، إذا لم يكن في حسابك رد جاهز بقيمة _id هذه، وعند الحذف، إذا كان أحد مسارات العمل يرسل الرد. |
| 404 | عند العرض: لا يوجد في حسابك رد جاهز بقيمة _id هذه. |
| 422 | فشل أحد الحقول في التحقق، مثلاً: name غير موجود، أو type أو subtype غير موجود، أو نص تجاوز حده. |