الرسائل

/v1/messages

استخدم العقدة messages لإرسال النص والوسائط وجهات الاتصال والمواقع والرسائل التفاعلية بالإضافة إلى قوالب الرسائل إلى العملاء.

يمكنك الرجوع إلى الدلائل التالية للحصول على معلومات حول الأنواع المحددة للرسائل التي يمكنك إرسالها: الرسائل النصية ورسائل الوسائط ورسائل جهات الاتصال والموقع والرسائل التفاعلية وقوالب الرسائل وقوالب رسائل الوسائط وقوالب الرسائل التفاعلية.

قبل البدء

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

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

القيود

• يتم دعم الأنواع التالية من الرسائل: النصوص وقوالب الرسائل والصور والمستندات والمقاطع الصوتية.
• يمكن أن يصل طول الرسالة النصية إلى 4096 حرفًا كحد أقصى.

الإنشاء

يمكنك إرسال الرسائل من خلال إجراء استدعاء POST للعقدة /messages بغض النظر عن نوع الرسالة. ويختلف محتوى نص رسالة JSON حسب أنواع الرسائل (نص، صورة، وغير ذلك).

المعلمات

هذه هي المعلمات الرئيسية المستخدمة في طلبات POST لـ /messages:

كائن النص

كائن الوسائط

بالنسبة لواجهة API داخل المواقع، يتم إرجاع معرف كائن الوسائط عند تحميل الوسائط بنجاح إلى عميل الواجهة داخل المواقع/المرجع في واتساب للأعمال من خلال نقطة النهاية media.

كائن جهات الاتصال

داخل contacts، يمكنك تضمين الكائنات التالية: addresses وemails وname وorg وphone وurls. يجب أن يتم تضمين الكائنات المجمعة في مصفوفة كما هو موضح في المثال أدناه.

مثال على كائن contacts يتضمن الكائنات المجمَّعة المتداخلة ضمن:

"contacts": [
    {
        "addresses": [
            {
                "city": "city name",
                "country": "country name",
                "country_code": "code",
                "state": "Contact's State",
                "street": "Contact's Street",
                "type": "Contact's Address Type",
                "zip": "Contact's Zip Code"
            }
        ],
        "birthday": "birthday",
        "emails": [
            {
                "email": "email",
                "type": "HOME"
            },
            {
                "email": "email",
                "type": "WORK"
            }
        ],
        "name": {
            "first_name": "first name value",
            "formatted_name": "formatted name value",
            "last_name": "last name value",
            "suffix": "suffix value"
        },
        "org": {
            "company": "company name",
            "department": "dep name",
            "title": "title"
        },
        "phones": [
            {
                "phone": "Phone number",
                "wa-id": "WA-ID value",
                "type": "MAIN"
            },
            {
                "phone": "Phone number",
                "type": "HOME"
            },
            {
                "phone": "Phone number",
                "type": "WORK"
            }
        ],
        "urls": [{
            "url": "some url",
            "type": "WORK"
        }]
    }
]

كائن الموقع

كائن القالب

داخل template، يمكنك تضمين كائنات components وlanguage.

كائن المكونات

داخل components، يمكنك إجراء تداخل للكائن parameters. بالإضافة إلى ذلك، يمكنك تعيين type على button.

كائن المعلمة

نوع الزر

داخل الكائن components، يمكنك تعيين type إلى button. هذه هي معلمات الزر:

مثال على نوع button مع sub_type بالقيمة quick_reply:

 {
    "type": "button",
    "sub_type": "quick_reply",
    "index": 0,
    "parameters": 
     [{
    	"type": "payload",
    	"payload": "Yes-Button-Payload"
     }]
 } 

مثال على نوع button مع sub_type بالقيمة copy_code

    
 { 
    "type": "button", 
    "sub_type": "copy_code", 
    "index": 0, 
    "parameters": 
    [{ 
     "type": "coupon_code", 
     "coupon_code": "DISCOUNT20" 
    }] 
 }

كائن Hsm

الكائن التفاعلي

كائن الإجراء

أمثلة

الرسائل الصوتية:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "audio",
  "audio": {
      "id": "your-media-id",
  }
}

رسائل المستند باستخدام filename:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "document",
  "document": {
      "id": "your-media-id",
      "filename": "your-document-filename"
  }
}

رسائل المستندات، باستخدام link:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "document",
  "document": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }     
    }
}

رسائل الفيديو باستخدام link:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "video",  
  "video": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }
    }
  }
}

الرسائل النصية:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "text",
  "text": {
      "body": "your-message-content"
  }
}

الرسائل التفاعلية (القوائم):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "interactive",
  "interactive":{
    "type": "list",
    "header": {
      "type": "text",
      "text": "your-header-content-here"
    },
    "body": {
      "text": "your-text-message-content-here"
    },
    "footer": {
      "text": "your-footer-content-here"
    },
    "action": {
      "button": "cta-button-content-here",
      "sections":[
        {
          "title":"your-section-title-content-here",
          "rows": [
            {
              "id":"unique-row-identifier-here",
              "title": "row-title-content-here",
              "description": "row-description-content-here",           
            }
          ]
        },
        {
          "title":"your-section-title-content-here",
          "rows": [
            {
              "id":"unique-row-identifier-here",
              "title": "row-title-content-here",
              "description": "row-description-content-here",           
            }
          ]
        },
        ...
      ]
    }
  }

}

الرسائل التفاعلية (أزرار الرد):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": { # optional
      "type": "text" | "image" | "video" | "document",
      "text": "your text"
      # OR
      "document": {
        "id": "your-media-id",
        "filename": "some-file-name"
      }
      # OR
      "document": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name",
        },
        "filename": "some-file-name"
      },
      # OR
      "video": {
        "id": "your-media-id"
      }
      # OR
      "video": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
      # OR
      "image": {
        "id": "your-media-id"
      }
      # OR
      "image": {
        "link": "http(s)://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
    }, # end header
    "body": {
      "text": "your-text-body-content"
    },
    "footer": { # optional
      "text": "your-text-footer-content"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "First Button’s Title" 
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "Second Button’s Title" 
          }
        }
      ] 
    } # end action   
  } # end interactive

}

الرسائل التفاعلية (رسائل المنتج الواحد ورسائل المنتجات المتعددة):

{ 
  "recipient_type": "individual",
  "to" : "{{Recipient-WA-ID}}",
  "type": "interactive",
  "interactive": {
    "type": "product",
    "body": {
      "text": "body text"
    },
    "footer": {
      "text": "footer text"
    },
    "action": {
      "
      
      _id": "catalog-ID",
      "product_retailer_id": "product-ID"
    }
  }
}

الرسائل التفاعلية (رسائل المنتجات المتعددة):

{ 
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive",
  "interactive": 
    {
    "type": "product_list",
    "Header":{
       "type": "text",
        "text": "text-header-content"
     },
     "body":{
        "text": "text-body-content"
      },
     "footer":{
        "text":"text-footer-content"
     },
     "action":{
        "catalog_id":"catalog-id",
        "sections": [
             {
             "title": "section-title",             
             "product_items": [
                  { "product_retailer_id": "product-SKU-in-catalog" },
                  { "product_retailer_id": "product-SKU-in-catalog" },
                            ...
              ]},
              {
              "title": "the-section-title",
              "product_items": [
                 { "product_retailer_id": "product-SKU-in-catalog" }
                           ...
              ]},
               ...
       ]
     },  
    }
}

الرسائل التفاعلية (رسائل الكتالوج):

{ 
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive",
  "interactive": 
    {
    "type": "catalog_message",
     "body":{
        "text": "text-body-content"
      },
     "footer":{
        "text":"text-footer-content"
     },
     "action":{
        "name": "catalog_message",
      	"parameters":{ 
      	  "thumbnail_product_retailer_id": "product-SKU-in-catalog"
      	}
     },  
    }
}

الرسائل التفاعلية (التدفقات):

{
  "recipient_type": "individual",
  "to": "{{Recipient-WA-ID}}",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "header": {
      "type": "text",
      "text": "Flow message header"
    },
    "body": {
      "text": "Flow message body"
    },
    "footer": {
      "text": "Flow message footer"
    },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s",
        "flow_id": "<FLOW_ID>",
        "flow_cta": "Book!",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "<SCREEN_ID>",
          "data": { # optional
            "user_name": "name",
            "user_age": 25
          }
        }
      }
    }
  }
}

فيما يلي مثال على payload في الاستجابة، ويتم حذف كائنات التعريف وكائنات الأخطاء للاختصار.

{
  "messages": [{ 
    "id": "message-id" 
  }]    
}

في حالة نجاح الطلب، ستتلقى استجابة تحتوي على معرف الرسالة. وإذا قام الطلب بإرجاع القسم errors، فتحقق من الرسالة الأصلية وقم بتصحيح الأخطاء قبل إعادة إرسال الطلب. لمزيد من المعلومات حول الأخطاء، راجع رموز أخطاء عميل الواجهة داخل المواقع/المرجع في واتساب للأعمال ورموز حالة HTTP.

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

    {
      "messages": [{ 
        "id": "message-id",
        "message_status": "Message has been held because quality assessment is pending",
      }]    
    }
    

التنسيقات في الرسائل النصية

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

الأداء

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

الأسئلة المتكررة

معرفة المزيد

• وثائق تسجيل الدخول والمصادقة
• وثائق جهات الاتصال
• رموز أخطاء عميل الواجهة داخل المواقع/المرجع في واتساب للأعمال
• رموز حالة HTTP