إرسال قوالب الرسائل التفاعلية

تعمل قوالب الرسائل التفاعلية على توسيع المحتوى الذي يمكنك إرساله إلى المستلمين بخلاف الرسائل من نوع قالب الرسالة القياسية وقالب رسائل الوسائط لتضمين الأزرار التفاعلية باستخدام كائن components.

هناك نوعان معروضان من الأزرار المحددة مسبقًا:

• دعوة لاتخاذ إجراء — يتيح لعميلك الاتصال برقم هاتف وزيارة موقع ويب
• الرد السريع — يتيح لعميلك الرد من خلال رسالة نصية بسيطة

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

قبل البدء

ستحتاج إلى ما يلي:

• تلبية كل المتطلبات الأساسية المُدرجة في قسم "قبل البدء" المتوفر في وثائق الرسائل.
• إنشاء قالب رسالة تفاعلية في مدير الأعمال. ويمكنك إضافة زر دعوة لاتخاذ إجراء أو زر رد سريع.

بمجرد اعتماد قالب الرسالة، يمكنك استخدام API لإرسال رسالة.

القيود

• بالنسبة لقوالب الدعوة لاتخاذ إجراء، يمكنك إضافة زرين، بحيث يكون هناك زر واحد لكل نوع (الاتصال برقم هاتف وزيارة موقع ويب).
• بالنسبة لقوالب الرد السريع، يمكنك إضافة حتى 3 أزرار.

الخطوة الأولى: إجراء طلب POST إلى /messages

POST /v1/messages
{
    "to": "recipient_wa_id",
    "type": "template",
    "template": {
        "namespace": "your-namespace",
        "language": {
            "policy": "deterministic",
            "code": "your-language-and-locale-code"
        },
        "name": "your-template-name",
        "components": [
            {
                "type" : "header",
                "parameters": [
                    {
                        "type": "text",
                        "text": "replacement_text"
                    }
                ]
            # end header
            },
            {
                "type" : "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "replacement_text"
                    },
                    {
                        "type": "currency",
                        "currency" : {
                            "fallback_value": "$100.99",
                            "code": "USD",
                            "amount_1000": 100990
                        }
                    },
                    {
                        "type": "date_time",
                        "date_time" : {
                            "fallback_value": "February 25, 1977",
                            "day_of_week": 5,
                            "day_of_month": 25,
                            "year": 1977,
                            "month": 2,
                            "hour": 15,
                            "minute": 33, #OR
                            "timestamp": 1485470276
                        }
                    },
                    {
                        ...
                        # Any additional template parameters
                    }
                ] 
            # end body
            },

            # The following part of this code example includes several possible button types, 
            # not all are required for an interactive message template API call.
            {
                "type": "button",
                "sub_type" : "quick_reply",
                "index": "0", 
                "parameters": [
                    {
                        "type": "payload",
                        # Business Developer-defined payload
                        "payload":"aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type" : "url",
                "index": "1", 
                "parameters": [
                    {
                        "type": "text",
                        # Business Developer-defined dynamic URL suffix
                        "text": "9rwnB8RbYmPF5t2Mn09x4h"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type" : "url",
                "index": "2",
                "parameters": [
                    {                    
                        "type": "text",
                        # Business Developer-defined dynamic URL suffix
                        "text": "ticket.pdf"
                    }
                ]
            }
        ]
    }
}

المعلمات

• المعلمات المشتركة لكل طلبات الرسائل
• معلمات قوالب الرسائل:

  • كائنtemplate
  • كائن components: بالنسبة لقوالب الرسائل التفاعلية، يمكنك تضمين نوع button وحقل sub_type
  • كائن parameters

الخطوة الثانية: التحقق من استجابة API

تتضمن الاستجابة الناجحة كائن messages بالمعرف id.

{
  "messages": [{
    "id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
  }]
}

تتضمن الاستجابة غير الناجحة كائن خطأ بسلسلة خطأ ورمز خطأ ومعلومات أخرى.

لمزيد من المعلومات حول الأخطاء، يمكنك الرجوع إلى رموز الخطأ والحالة.

الخطوة الثالثة الاختيارية: معالجة إجراء المستخدم

عندما ينقر المستخدم على زر الرد السريع، يتم إرسال استجابة إلى النشاط التجاري مرة أخرى. راجع استجابة الاستدعاء الواردة من النقر على زر الرد السريع لمزيد من المعلومات. كما يمكن للمستخدمين اختيار عدم النقر على الزر والاكتفاء بإرسال رسالة حرة إليك.

استجابة الاستدعاء الواردة من النقر على زر الرد السريع

{
    "contacts": [
        {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16505551234"
        }
    ],
    "messages": [
        {
            "button": {
                "payload": "No-Button-Payload",
                "text": "No"
            },
            "context": {
                "from": "16315558007",
                "id": "gBGGFmkiWVVPAgkgQkwi7IORac0"
            },
            "from": "16505551234",
            "id": "ABGGFmkiWVVPAgo-sKD87hgxPHdF",
            "timestamp": "1591210827",
            "type": "button"
        }
    ]
    # If there are any errors, an errors field (array) will be present        
    "errors": [ { ... } ]
}

أمثلة

توضح هذه الأمثلة عملية إعداد قوالب الرسائل التفاعلية بداية من إنشاء القالب في مدير الأعمال وإرسال قوالب الرسائل من خلال استدعاءات API إلى نقطة النهاية messages.

التذكير بالرحلات

يعرض هذا المثال عملية إنشاء قالب رسالة وسائط تفاعلية يتضمن أزرار الرد السريع.

1. إنشاء قالب رسالة الوسائط التفاعلية في مدير الأعمال.

2. تتم إضافة استدعاء API messages في معلومات المعلمة.

POST /v1/messages
{
    "to": "your-test-recipient-wa-id",
    "recipient_type": "individual",
    "type": "template",
    "template": {
        "namespace": "88b39973_f0d5_54e1_29cf_e80f1e3da4f2",
        "name": "upcoming_trip_reminder",
        "language": {
            "code": "en",
            "policy": "deterministic"
        },
        "components": [
            {
                "type": "header",
                "parameters": [
                    {
                        "type": "text",
                        "text": "12/26"
                    }
                ]
            },
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "*Ski Trip*"
                    },
                    {
                        "type": "date_time",
                        "date_time" : {
                            "fallback_value": "29th July 2019, 8:00am",
                            "day_of_month": "29",
                            "year": "2019",
                            "month": "7",
                            "hour": "8",
                            "minute": "00"
                        }
                    },
                    {
                            "type": "text",
                            "text": "*Squaw Valley Ski Resort, Tahoe*"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type": "quick_reply",
                "index": 0,
                "parameters": [
                    {
                        "type": "payload",
                        "payload": "Yes-Button-Payload"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type": "quick_reply",
                "index": 1,
                "parameters": [
                    {
                        "type": "payload",
                        "payload": "No-Button-Payload"
                    }
                ]
            }
        ]
    }
}

3. يتلقى عميلك رسالة تذكير بالرحلة تتضمن أزرار الرد السريع.

شحن المنتجات

يعرض هذا المثال عملية إنشاء قالب رسالة وسائط تفاعلية يتضمن أزرار رقم الهاتف وعنوان URL.

1. إنشاء قالب رسالة الوسائط التفاعلية في مدير الأعمال:

2. تتم إضافة استدعاء API messages في معلومات المعلمة.

POST /v1/messages
{
    "to": "your-test-recipient-wa-id",
    "recipient_type": "individual",
    "type": "template",
    "template": {
        "namespace": "88b39973_f0d5_54e1_29cf_e80f1e3da4f2",
        "name": "oculus_shipment_update",
        "language": {
            "code": "en",
            "policy": "deterministic"
        },
        "components": [
            {
                "type": "header",
                "parameters": [{
                    "type": "image",
                    "image": {
                        "link": "link-to-your-image"
                    }
                }]
            },
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "Anand"
                    },
                    {
                        "type": "text",
                        "text": "Quest"
                    },
                    {
                        "type": "text",
                        "text": "113-0921387"
                    },
                    {
                        "type": "date_time",
                        "date_time" : {
                            "fallback_value": "23rd Nov 2019",
                            "day_of_month": "20",
                            "year": "2019",
                            "month": "9"
                        }
                    }
                ] 
            },
            {
                "type": "button",
                "index": "0",
                "sub_type": "url",
                "parameters": [
                    {
                        "type": "text",
                        "text": "1Z999AA10123456784"
                    }
                ]
            }
        ]
    }
}

3. يتلقى عميلك رسالة شحن منتج تتضمن أزرار إجراء مكالمة هاتفية وعنوان URL: