منصة واتساب للأعمال > API السحابة > الدلائل

إرسال الرسائل

يصف هذا المستند كيفية استخدام API لإرسال الرسائل إلى مستخدمي واتساب.

أنواع الرسائل

يمكنك استخدام API لإرسال أنواع الرسائل التالية. يمكن إرسال كل هذه الأنواع باستثناء رسائل التفاعلات في صورة رد على رسالة سابقة.

تتيح لك رسائل العنوان طلب عنوان توصيل بسهولة من مستخدمي واتساب.

تعرض الرسائل الصوتية أيقونة مقطع صوتي ورابط للملف الصوتي. عندما يضغط مستخدم واتساب على الأيقونة، يتم تحميل عميل واتساب ويعمل على تشغيل الملف الصوتي.

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

تعرض رسائل المستندات أيقونة مستند، ترتبط بمستند ما، والتي يمكن لمستخدم واتساب الضغط عليها للتنزيل.

تعرض رسائل الصور صورة واحدة وشرحًا توضيحيًا اختياريًا.

تتيح لك الرسائل التفاعلية لأزرار عنوان URL للدعوة ��اتخاذ إجراء تعيين أي عنوان URL على زر، حتى لا تضطر إلى تضمين عناوين URL الأولية الطويلة أو الغامضة في نص الرسالة.

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

تسمح لك رسائل القائمة التفاعلية بعرض قائمة لمستخدمي واتساب تتضمن خيارات متعددة يمكن الاختيار منها.

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

تسمح لك رسائل أزرار الرد التفاعلية بإرسال ما يصل إلى ثلاثة ردود محددة مسبقًا للمستخدمين للاختيار منها.

تسمح لك رسائل الموقع بإرسال إحداثيات خط الطول وخط العرض الخاصة بالموقع إلى مستخدم واتساب.

تعرض رسائل الملصقات صور ملصقات متحركة أو ثابتة في رسالة واتساب.

الرسائل النصية هي رسائل تحتوي على نص ومعاينة اختيارية للرابط فقط.

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

تعرض رسائل الفيديو معاينة صورة مصغرة لصورة الفيديو مع شرح توضيحي اختياري. عندما يضغط مستخدم واتساب على المعاينة، يتم تحميل الفيديو وعرضه على المستخدم.

رسائل التفاعلات هي تفاعلات بالرموز التعبيرية التي يمكنك تطبيقها على رسالة سابقة تلقيتها من مستخدم واتساب.

نوافذ خدمة العملاء

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

يمكن إرسال كل أنواع الرسائل، باستثناء رسائل القوالب، إلى المستخدم إذا كانت فترة خدمة العملاء مفتوحة بينك وبين المستخدم.

يمكن إرسال رسائل القوالب إلى مستخدم في أي وقت، طالما أنه قد اشترك لاستلام الرسائل من جانبك.

الطلبات

تستخدم كل طلبات إرسال الرسائل نقطة النهاية POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/messages:

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

يختلف نص المنشور استنادًا إلى نوع الرسالة التي تريد إرسالها، ولكن تستخدم حمولة البيانات البنية الشائعة التالية:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "<MESSAGE_TYPE>",
  "<MESSAGE_TYPE>": {<MESSAGE_CONTENTS>}
}

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

على سبيل المثال، هذا طلب لإرسال رسالة نصية إلى مستخدم واتساب. لاحظ أنه تم تعيين type على text ويتبع ذلك الكائن text والذي يصف محتويات الرسالة:

curl 'https://graph.facebook.com/v20.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "As requested, here'\''s the link to our latest product: https://www.meta.com/quest/quest-3/"
  }
}'

فيما يلي شكل الرسالة في ��ميل واتساب إذا تم إرسال الرسالة النصية بنجاح إلى مستخدم واتساب:

الاستجابات

سترسل API الاستجابة التالية إذا تم قبول طلب إرسال الرسالة بنجاح بدون مواجهة أي أخطاء في الطلب ذاته:

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<WHATSAPP_USER_PHONE_NUMBER>",
      "wa_id": "<WHATSAPP_USER_ID>"
    }
  ],
  "messages": [
    {
      "id": "<WHATSAPP_MESSAGE_ID>"
      "message_status": "<PACING_STATUS>"
    }
  ]
}

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

يتم تضمين الخاصية message_status فقط عند إرسال رسائل القوالب التي تستخدم قالبًا يتم استخدامه بمعدل عرض.

Webhooks

تعمل الرسائل المرسلة إلى مستخدمي واتساب على تشغيل أحداث webhooks الرسائل، لذا تأكد من الاشتراك في هذا الموضوع لاستلام إشعارات حالة الرسالة.

رسائل المعاملات التجارية

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

الردود

يمكنك إرسال أي نوع من الرسائل كرد على رسالة سابقة. ستظهر الرسالة السابقة أعلى الرسالة الجديدة، مقتبسة ضمن فقاعة سياقية.

التقييدات

لن تظهر الفقاعة السياقية أعلى الرسالة التي تم إرسالها كرد إذا:

تم حذف الرسال�� السابقة أو نقلها مساحة التخزين طويلة الأجل (عادةً ما يتم نقل الرسائل إلى مساحة التخزين طويلة الأجل بعد 30 يومًا، ما لم تكن قد قمت بتمكين مساحة التخزين المحلية).
قمت بالرد برسالة صوتية أو رسالة صورة أو رسالة فيديو وكان مستخدم واتساب يعمل بنظام KaiOS.
كنت تستخدم عميل واتساب للرد برسالة الضغط للتحدث وكان مستخدم واتساب يعمل بنظام KaiOS.
قمت بالرد برسالة قالب.

بنية الطلب

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

نص المنشور

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "context": {
    "message_id": "WAMID_TO_REPLY_TO"
  },

  /* Message type and type contents goes here */

}

معلمات نص المنشور

العنصر النائب الوصف مثال على القيمة

العنصر النائب	الوصف	مثال على القيمة
`<WAMID_TO_REPLY_TO>` String (سلسلة)	مطلوب. معرف رسالة واتساب (wamid) لرسالة سابقة تريد الرد عليها.	`wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTdCNTg5RjY1MEMyRjlGMjRGNgA=`
`<WHATSAPP_USER_PHONE_NUMBER>` String	Required. WhatsApp user phone number.	`+16505551234`

<WAMID_TO_REPLY_TO>

String (سلسلة)

مطلوب.

معرف رسالة واتساب (wamid) لرسالة سابقة تريد الرد عليها.

wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTdCNTg5RjY1MEMyRjlGMjRGNgA=

<WHATSAPP_USER_PHONE_NUMBER>

String

Required.

WhatsApp user phone number.

+16505551234

مثال على الطلب

مثال لرسالة نصية مرسلة كرد على رسالة سابقة.

curl 'https://graph.facebook.com/v19.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "context": {
    "message_id": "wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTdCNTg5RjY1MEMyRjlGMjRGNgA="
  },
  "type": "text",
  "text": {
    "body": "You'\''re welcome, Pablo!"
  }
}'

WhatsApp User Phone Number Formats

Plus signs (+), hyphens (-), parenthesis ((,)), and spaces are supported in send message requests.

We highly recommend that you include both the plus sign and country calling code when sending a message to a customer. If the plus sign is omitted, your business phone number's country calling code is prepended to the customer's phone number. This can result in undelivered or misdelivered messages.

For example, if your business is in India (country calling code 91) and you send a message to the following customer phone number in various formats:

Number In Send Message Request	Number Message Delivered To	Outcome
`+16315551234`	`+16315551234`	Correct number
`+1 (631) 555-1234`	`+16315551234`	Correct number
`(631) 555-1234`	`+916315551234`	Potentially wrong number
`1 (631) 555-1234`	`+9116315551234`	Potentially wrong number

أصول الوسائط

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

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

تخزين وسائط HTTP مؤقتًا

تدعم API السحابة في واتساب تخزين وسائط HTTP مؤقتًا. إذا كنت تستخدم (link) لأصل وسائط موجود على الخادم (على عكس (id) الذي يُستخدم للأصل الذي قمت بتحميله على الخوادم)، فيمكنك إرسال تعليمات بتخزين الأصل مؤقتًا لإعادة استخدامه مع الرسائل المستقبلية عن طريق تضمين العناوين أدناه في استجابة الخادم عندما نطلب الأصل. إذا لم يتم تضمين أي من هذه العناوين، فلن يتم تخزين الأصل مؤقتًا.

Cache-Control: <CACHE_CONTROL>
Last-Modified: <LAST_MODIFIED>
ETag: <ETAG>

Cache-Control

يخبرنا العنوان Cache-Control بطريقة معالجة تخزين الأصل مؤقتًا. ندعم التوجيهات التالية:

max-age=n: يشير إلى عدد الثواني المستغرقة (n) لتخزين الأصل مؤقتًا. سنعيد استخدام الأصل المخزن مؤقتًا في الرسائل ال��احقة حتى يتم تجاوز هذا الوقت، وبعد ذلك سنطلب الأصل مجددًا، إذا لزم الأمر. مثال: Cache-Control: max-age=604800.
no-cache: يشير إلى إمكانية تخزين الأصل مؤقتًا لكن يجب تحديثه إذا كانت قيمة العنوان Last-Modified مختلفة عن الاستجابة السابقة. يتطلب العنوان Last-Modified. مثال: Cache-Control: no-cache.
no-store: يشير إلى تعذر تخزين الأصل مؤقتًا. مثال: Cache-Control: no-store.
private: يشير إلى أنه تم إضفاء طابع شخصي على الأصل للمستلم ويجب ألا يتم تخزينه مؤقتًا.

Last-Modified

يشير إلى تاريخ آخر تعديل للأصل. يتم استخدامه مع Cache-Control: no-cache. إذا كانت القيمة Last-Modified مختلفة عن الاستجابة السابقة وتم تضمين Cache-Control: no-cache في الاستجابة، فسيتم تحديث الإصدار المخزن مؤقتًا للأصل واستبداله بالأصل الموجود في الاستجابة. مثال: Date: Tue, 22 Feb 2022 22:22:22 GMT.

ETag

عنوان ETag هو سلسلة فريدة تحدد الإصدار المعين لأصل. مثال: ETag: "33a64df5". يتم تجاهل هذا العنوان ما لم يتم تضمين كل من Cache-Control وLast-Modified في الاستجابة. في هذه الحالة، سيتم تخزين الأصل مؤقتًا وفقًا للمنطق الداخلي الخاص (والذي لا نكشف عنه).

عينة من الاستجابة التي تتضمن عناوين

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 1024
Date: Tue, 22 Feb 2022 22:22:22 GMT
ETag: "33a64df5"
Cache-Control: max-age=604800

<IMAGE_PAYLOAD>

تسلسل تسليم الرسائل المتعددة

عند إرسال سلسلة من الرسائل، لا يمكن ضمان مطابقة ترتيب تسليم الرسائل مع ترتيب طلبات API. إذا كنت بحاجة إلى ضمان تسلسل تسليم الرسائل، فتأكد من تلقي حالة delivered في حدث webhook الرسائل قبل إرسال الرسالة التالية في تسلسل الرسائل.

فترة الصلاحية

إذا تعذر عليك تسليم الرسالة إلى مستخدم واتساب، فسنتابع محاولة تسليم الرسالة لفترة من الزمن تُسمى فترة الصلاحية (TTL) أو فترو صلاحية الرسالة. إذا تعذر علينا تسليم رسالة في وقت يتخطى فترة الصلاحية، فسنتوقف عن محاولة إرسال الرسالة وسنتجاهلها.

تكون ��ترة الصلاحية لكل الرسائل، باستثناء قوالب الرسائل التي تستخدم قالب المصادقة 30 يومًا.
يكون لرسائل القوالب التي تستخدم قالب مصادقة فترة صلاحية افتراضية مدتها 10 دقائق.

يمكنك تخصيص هذه الإعدادات الافتراضية من خلال تعيين فترة صلاحية مخصصة في قوالب المصادقة وقوالب المساعدة. راجع تخصيص فترة الصلاحية.

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

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

استكشاف الأخطاء وإصلاحها

إذا كنت تواجه مشكلات في تلقي الرسائل، فراجع الرسائل التي لم يتم تسليمها.

منصة واتساب للأعمال | API السحابة | API إدارة الأعمال