إشعارات الرسائل المستلمة
عندما تتلقى رسالة واردة، يتم إرسال إشعار إلى عنوان URL الخاص بحدث Webhook الذي قمت بتعيينه في إعدادات التطبيق. يتناول هذا المستند الرسائل الواردة التي يمكنك تلقيها ويقدم أمثلة.
كائنات الإشعار
يمكن أن تحتوي إشعارات الرسائل المستلمة على الكائنات التالية:
عند استلام رسالة تتضمن وسائط، يعمل عميل API واتساب للأعمال على تنزيل الوسائط. يتم إرسال إشعار إلى حدث Webhook لديك بمجرد تنزيل الوسائط. يحتوي هذا الإشعار على المعلومات التي تُحدد كائن الوسائط وتتيح لك العثور على الكائن واسترداده. استخدم نقطة نهاية الوسائط مع id الخاص بالوسائط لاسترداد الوسائط.
أمثلة على الرسائل المستلمة
الرسالة النصية
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages":[{
"from": "16315551234",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1518694235",
"text": {
"body": "Hello this is an answer"
},
"type": "text"
}]
}
رسالة الموقع الثابت
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages":[{
"from":"16315551234",
"id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"location":{
"address":"Main Street Beach, Santa Cruz, CA",
"latitude":38.9806263495,
"longitude":-131.9428612257,
"name":"Main Street Beach",
"url":"https://foursquare.com/v/4d7031d35b5df7744"},
"timestamp":"1521497875",
"type":"location"
}]
}
رسالة جهات الاتصال
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages": [{
"contacts": [{
"addresses": [{
"city": "Menlo Park",
"country": "United States",
"country_code": "us",
"state": "CA",
"street": "1 Hacker Way",
"type": "WORK",
"zip": "94025"
}],
"birthday": "2012-08-18",
"emails": [{
"email": "kfish@fb.com",
"type": "WORK"
}],
"ims": [{
"service": "AIM",
"user_id": "kfish"
}],
"name": {
"first_name": "Kerry",
"formatted_name": "Kerry Fisher",
"last_name": "Fisher"
},
"org": {
"company": "Meta",
"department": "WhatsApp"
},
"phones": [{
"phone": "+1 (940) 555-1234",
"type": "CELL"
},
{
"phone": "+1 (650) 555-1234",
"type": "WORK",
"wa_id": "16505551234"
}],
"urls": [{
"url": "https://www.facebook.com",
"type": "WORK"
}]
}],
"from": "16505551234",
"id": "ABGGFlA4dSRvAgo6C4Z53hMh1ugR",
"timestamp": "1537248012",
"type": "contacts"
}]
}
يصبح الإعداد contact_image فارغًا إذا كان العميل المستهلك يستخدم iPhone.
رسائل الوسائط
الرسالة التي تحتوي على صورة:
{
"messages": [{
"from": "16315551234",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"image": {
"file": "/usr/local/wamedia/shared/b1cf38-8734-4ad3-b4a1-ef0c10d0d683",
"id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
"mime_type": "image/jpeg",
"sha256": "29ed500fa64eb55fc19dc4124acb300e5dcc54a0f822a301ae99944db",
"caption": "Check out my new phone!"
},
"timestamp": "1521497954",
"type": "image"
}]
}
الحقل caption اختياري لرسائل الوسائط. لا يتم تضمينه إلا إذا قام المستخدم بتعيين شرح توضيحي.
الرسالة التي تحتوي على مستند:
{
"messages": [{
"from": "16315551234",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1522189546",
"type": "document",
"document": {
"caption": "80skaraokesonglistartist",
"file": "/usr/local/wamedia/shared/fc233119-733f-49c-bcbd-b2f68f798e33",
"id": "fc233119-733f-49c-bcbd-b2f68f798e33",
"mime_type": "application/pdf",
"sha256": "3b11fa6ef2bde1dd14726e09d3edaf782120919d06f6484f32d5d5caa4b8e"
}
}]
}
الرسالة الصوتية:
{
"messages":[{
"from": "16315551234",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1521827831",
"type": "voice",
"voice": {
"file": "/usr/local/wamedia/shared/463e/b7ec/ff4e4d9bb1101879cbd411b2",
"id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
"mime_type": "audio/ogg; codecs=opus",
"sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"}
}]
}
الرسالة التي تحتوي على ملصق:
{
"messages":[{
"from": "16315551234",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1521827831",
"type": "sticker",
"sticker": {
"id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
"metadata": {
"sticker-pack-id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
"sticker-pack-name" : "Happy New Year",
"sticker-pack-publisher" : "Kerry Fisher",
"emojis": ["🐥", "😃"],
"ios-app-store-link" : "https://apps.apple.com/app/id3133333",
"android-app-store-link" : "https://play.google.com/store/apps/details?id=com.example",
"is-first-party-sticker" : 0 | 1 # integer
},
"mime_type": "image/webp",
"sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
}
}]
}
الرسالة التي تم إنشاؤها من إعلانات النقر لفتح محادثة في واتساب
{
"messages":[{
"from":"12345678",
"id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"image":{
"id":"b1c68f38-8734-4ad3-b4a1-ef0c10d683",
"mime_type":"image/jpeg",
"sha256":"29ed500fa64eb55fc19dc4124acb300e5dcca0f822a301ae99944db"
"caption": "Check out my product!",
},
"timestamp":"1521497954",
"type":"image",
"referral" : {
"headline": "Our new product",
"body" : "This is a great product",
"source_type": "<SOURCE_TYPE>",
"source_id": "<SOURCE_ID>",
"source_url": "<SOURCE_URL>", //for the moment, this will always be a Facebook owned domain
"video": {
"id": "e144be57-12b1-4035-a520-703fcc87ef45",
}
}
}]
}راجع المزيد من المعلومات حول الخاصية referral.
مثال: الرسائل غير المدعومة
من الممكن استلام إشعار باستدعاء unknown. فيما يلي مثال على نوع رسالة غير مدعوم تم استلامها من أحد العملاء.
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages": [{
"errors": [{
"code": 501,
"details": "Message type is not currently supported",
"title": "Unknown message type"
}],
"from": "16315551234",
"id": "ABGGFRBzFymPAgo6N9KKs7HsN6eB",
"timestamp": "1531933468",
"type": "unknown"
}]
}
الرسائل المعاد توجيهها
يمكنك ملاحظة إذا ما تمت إعادة توجيه الرسالة المستلمة أو تتم إعادة توجيهها بشكل متكرر. فيما يلي إشعار لرسالة معاد توجيهها:
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages": [{
"context": {
"forwarded": true
},
"from": "16315558011",
"id": "ABGGFmkiWVVPAgo-sOGh7pv13wVJ",
"text": {
"body": "Party at Dotty's tonight!"
},
"timestamp": "1593068329",
"type": "text"
}]
}
فيما يلي إشعار لرسالة معاد توجيهها بشكل متكرر:
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages": [{
"context": {
"frequently_forwarded": true
},
"from": "16315558011",
"id": "ABGGFmkiWVVPAgo-sBTHfS3swNIl",
"timestamp": "1593068225",
"type": "video",
"video": {
"id": "e144be57-12b1-4035-a520-703fcc87ef45",
"mime_type": "video/mp4",
"sha256": "02c4e68a4f0d6af5ec6ef02120e20d15f520a4dd473b535abec1aab175c4e8b9"
}
}]
}
تمكين إشعار الأمان
إذا تم تعيين المعلمة show_security_notifications إلى القيمة true في إعدادات التطبيق، فتتضمن جميع إشعارات الرسائل الواردة المعلومات التالية حول هوية المستخدم المضمنة داخل الكائن identity:
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages": [{
"from": "16315553601",
"id": "ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
"identity": {
"acknowledged": true,
"created_timestamp": 1602532300000,
"hash": "Sjvjlx8G6Z0="
},
"text": {
"body": "Hi from new number 3601"
},
"timestamp": "1602532300",
"type": "text"
}]
}رسالة من نقرة على زر الرد السريع
{
"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": [ { ... } ]
}
الردود الواردة على الرسائل المُرسلة
يمكن للمستخدمين الرد على رسالة معيّنة في واتساب. ولكي يحدد النشاط التجاري سياق الرد على الرسالة، يتم تضمين كائن context. يوفر الكائن context هذا id للرسالة التي رد عليها العميل ومعرف واتساب الخاص بمرسل الرسالة الأصلية ومعرفات أي منتجات قد يشير إليها العميل.
يحتوي دليل الرد على الرسائل على مزيد من المعلومات.
مثال: العميل الذي رد على رسالتك
فيما يلي مثال على رسالة واردة تمثل ردًا على رسالة أرسلتها. راجع قسم الكائن context أدناه لمزيد من المعلومات.
{
"contacts": [ {
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
} ],
"messages":[{
"context":{
"from":"16315558011",
"id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf"
},
"from":"16315551234",
"id":"gBGGFlA5FpafAgkOuJbRq54qwbM",
"text":{"body":"Yes, count me in!"},
"timestamp":"1521499915",
"type":"text"
}]
}
يكون الحقل text اختياريًا لرسائل الوسائط. وإذا كانت القيمة text موجودة، فإنها تمثل الشرح التوضيحي للوسائط المرسلة أو نص الاستجابة، إذا كانت الاستجابة رسالة نصية.
مثال: العميل الذي رد على قائمة الرسائل
{
"messages": [ {
"context": {
"from": "sender_wa_id_of_context_message",
"group_id": "group_id_of_context_message",
"id": "message_id_of_context_message",
"mentions": [ "wa_id1", "wa_id2" ]
},
"from": "sender_wa_id",
"group_id": "group_id",
"id": "message_id",
"timestamp": "message_timestamp",
"type": "interactive",
"interactive": {
"type": "list_reply",
"list_reply": {
"title": "row-title-content-here",
"id": "unique-row-identifier-here",
"description": "row-description-content-here"
}
}
}
مثال: العميل الذي رد على رسالة زر الرد
{
"messages": [
{
"context": {
"from": "sender_wa_id_of_context_message",
"group_id": "group_id_of_context_message",
"id": "message_id_of_context_message",
"mentions": [ "wa_id1", "wa_id2" ]
},
"from": "sender_wa_id",
"group_id": "group_id",
"id": "message_id",
"timestamp": "message_timestamp",
"type": "interactive",
"interactive": {
"type": "button_reply",
"button_reply": {
"id": "unique-button-identifier",
"title": "button-text"
}
} # end interactive node
} # end message item
] # end messages array
}مثال: العميل الذي يطلب معلومات بخصوص منتج محدد
{
"contacts": [
{
"profile": {
"name": "customer-name"
},
"wa_id": "customer-whatsapp-ID"
}
],
"messages": [
{
"from": "customer-whatsapp-ID",
"id": "message-ID",
"text": {
"body": "Can I get this in another color?"
},
"context": {
"referred_product": {
"catalog_id": "catalog-ID",
"product_retailer_id": "product-ID"
}
},
"timestamp": "message-received-timestamp",
"type": "text"
}
]
}
مثال: قدم العميل طلبًا بعد تلقيه رسالة منتج واحد أو منتجات متعددة
{
"messages": [ {
"from": "customer-whatsapp-id",
"group_id": "group-id",
"id": "message-ID",
"timestamp": "message-timestamp",
"type": "order"
"order": {
"catalog_id": "catalog_id",
"product_items": [
{
"product_retailer_id":"product-ID",
"quantity":"number-of-items",
"item_price":"unitary-price-of-item",
"currency":"price-currency"
},
...
],
"text":"text-message-sent-along-with-the-order"
}
}
}
رسائل النظام الواردة
يتم إنشاء رسائل النظام بواسطة النظام عند وقوع حدث ما.
مثال: تغيير المستخدم لرقمه
إذا تم تعيين المعلمة notify_user_change_number إلى القيمة true في إعدادات التطبيق، فستتلقى رسائل نظام واردة عندما يحاول المستخدم تغيير رقم هاتفه.
{
"messages": [
{
"from": "16315558889",
"id": "ABGGFjFVWIifAzNzeXMtMTYzMTU1NTg4ODlAcy53aGF0c2FwcC5uZXQtMTU3NDA4MDEwMjIxMy1jaGFuZ2U",
"system": {
"body": "User A changed from +1 (631) 555-8889 to +1 (631) 555-8890",
"new_wa_id": "16315558890",
"type": "user_changed_number"
},
"timestamp": "1574080102",
"type": "system"
}
]
}
مثال: احتمالية تغيير المستخدم
إذا تم تعيين المعلمة show_security_notifications إلى القيمة true في إعدادات التطبيق، فستتلقى رسائل نظام واردة عند تغير المستخدم (الذي تقوم بمحادثته) على WhatsApp.
إلى أن يتم التعرف على هذا الإشعار باستخدام نقطة النهاية identity، سيتم حظر جميع الرسائل الصادرة إلى هذا المستخدم. وسيستمر تلقي الرسائل الواردة كما هو متوقع.
{
"messages": [
{
"from": "16315553601",
"id": "ABGGFjFVU2AfAzVzeXMtMTYzMTU1NTM2MDFAcy53aGF0c2FwcC5uZXQtMTYwMjUzNTM1NjMzMi1pZGVudGl0eQ",
"system": {
"body": "Test security code change",
"identity": "Rc/eg9Rl0JA=",
"type": "user_identity_changed",
"user": "16315553601"
},
"timestamp": "1602535356",
"type": "system"
}
]
}
أنواع رسائل النظام
| نوع رسالة النظام | الوصف |
|---|---|
| تم تغيير رقم هاتف المستخدم |
| احتمالية تغيير المستخدم على WhatsApp |
ذكر المستخدمين في الرسائل
عندما تُرسِل رسالة تذكر معرف WhatsApp معيّن مباشرةً ويرد شخص ما على تلك الرسالة، فسترى المعرف الذي تم ذكره في الكائن context وفي مصفوفة mentions. نظرًا لإمكانية ذكر أكثر من رقم هاتف واحد، فإن الحقل mentions سيكون عبارة عن مجموعة من أرقام الهواتف، حتى إذا تم ذكر رقم هاتف واحد فقط.
مثال: العميل الذي يرد على رسالتك
فيما يلي مثال لرد العميل على رسالة تضمنت إشارات. يحتوي الكائن context على الأرقام التي تم ذكرها في الرسالة الأصلية. ويذكر الرد الموجود في الكائن text الأرقام نفسها مرة أخرى.
{
"messages": [{
"context": {
"from": "16315555544",
"id": "gBGGFlA5FpafAgkOuJbRq54qwbM",
"mentions": [
"16315551000",
"16315551099"
]
},
"from": "16315551234 ",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1504902988",
"text": {
"body": "@16315551000 and @16315551099 are mentioned"
},
"type": "text"
}]
}