الردود الجاهزة

الرد الجاهز إجابة يكتبها فريقك مرة واحدة ويرسلها بنقرتين من صندوق الرسائل، وترسلها مسارات العمل تلقائياً. وعبر الواجهة البرمجية يستطيع التكامل إبقاء هذه الإجابات متوافقة مع نظام آخر: كتحديث الأسعار في رد ما عند تغيّر كتالوجك، أو إضافة رد لكل فرع جديد.

لمعرفة كيف يستخدم أعضاء الفريق الردود الجاهزة في التطبيق، راجع الردود الجاهزة.

المتطلبات

الإجراء إمكانية المفتاح صلاحية عضو الفريق
القائمة والعرض 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 غير موجود، أو نص تجاوز حده.