messages
Webhook Event ReferenceOn March 4th, 2020 we introduced Messenger webhook versioning. For v6.0
and above we adjusted the way attachments type fallback
and image
with a sticker are sent.
We introduced replies as part of the message webhook.
This callback will occur when a message has been sent to your Page. Messages are always sent in order. You may receive text messages or messages with attachments.
Attachment types image
, audio
, video
, file
, or location
are the main supported types. You may also receive fallback
attachments. A common example of a 'fallback' is when a user shares a URL with a Page, an attachment is created based on link sharing. For unsupported shares made by users to your Page a fallback
with no payload might be sent.
You can subscribe to this callback by selecting message
when setting up your webhook.
{ "sender":{ "id":"<PSID>" }, "recipient":{ "id":"<PAGE_ID>" }, "timestamp":1458692752478, "message":{ "mid":"mid.1457764197618:41d102a3e1ae206a38", "text":"hello, world!", "quick_reply": { "payload": "<DEVELOPER_DEFINED_PAYLOAD>" } } }
{ "sender":{ "id":"<PSID>" }, "recipient":{ "id":"<PAGE_ID>" }, "timestamp":1458692752478, "message":{ "mid":"m_1457764197618:41d102a3e1ae206a38", "text":"hello, world!", "reply_to": { "mid":"m_1fTq8oLumEyIp3Q2MR-aY7IfLZDamVrALniheU" } } }
{
"id": "682498302938465",
"time": 1518479195594,
"messaging": [
{
"sender": {
"id": "<PSID>"
},
"recipient": {
"id": "<PAGE_ID>"
},
"timestamp": 1518479195308,
"message": {
"mid": "mid.$cAAJdkrCd2ORnva8ErFhjGm0X_Q_c",
"attachments": [
{
"type": "<image|video|audio|file>",
"payload": {
"url": "<ATTACHMENT_URL>"
}
}
]
}
}
]
}
Message webhook with product template is only available on Graph API v8.0+
This webhook applies to the scenario when user shares products from other threads or sharing flow to the page. This webhook is limited to only products that are owned by the page. App will need to have catalog_management
permission approved to receive product details in webhooks.
{
"id": "682498302938465",
"time": 1518479195594,
"messaging": [
{
"sender": {
"id": "<PSID>"
},
"recipient": {
"id": "<PAGE_ID>"
},
"timestamp": 1518479195308,
"message": {
"mid": "mid.$cAAJdkrCd2ORnva8ErFhjGm0X_Q_c",
"attachments": [
{
"type": "template",
"payload": {
"product":{
"elements":[ // multiple elements for Hscroll
{
"id":"<PRODUCT_ID>",
"retailer_id":"<EXTERNAL_ID>",
"image_url":"https://fb.cdn.com/sdsd",
"title":"Some product title",
"subtitle": "$40",
},
{...},
]
}
}
]
}
}
]
}
Example applicable to messages
on version +v6.0
{ "object": "page", "entry": [ { "id": "<PAGE_ID>", "time": 1583173667623, "messaging": [ { "sender": { "id": "<PSID>" }, "recipient": { "id": "<PAGE_ID>" }, "timestamp": 1583173666767, "message": { "mid": "m_toDnmD...", "text": "This is where I want to go: https:\/\/youtu.be\/bbo_fZAjIhg", "attachments": [ { "type": "fallback", "payload": { "url": "<ATTACHMENT_URL >", "title": "TAHITI - Heaven on Earth" } } ] } } ] } ] }
Message webhook from Facebook Shops product detail page is only available on Graph API v8.0+
{ "sender":{ "id":"<PSID>" }, "recipient":{ "id":"<PAGE_ID>" }, "timestamp":1458692752478, "message":{ "mid":"mid.1457764197618:41d102a3e1ae206a38", "text":"hello, world!", "referral": { "product": { "id":"<PRODUCT_ID>" } } } }
sender
Property | Type | Description |
---|---|---|
| String | The PSID of the user that triggered the webhook event. |
| String | The user_ref of the user that triggered the webhook event. This is only available for webhook event from the chat plugin. |
recipient
Property | Type | Description |
---|---|---|
| String | Your Page ID. |
message
For +v6.0 sticker_id
was moved from message
, to message.attachments.payload
Property | Type | Description |
---|---|---|
| String | Message ID |
| String | Text of message |
| Object | Optional custom data provided by the sending app |
| Object | Reference to the message id (mid) that this message is replying to |
| Array< | Array containing attachment data |
| Object | Referral of the message from Facebook Shops product details page. |
message.quick_reply
A quick_reply
payload is only provided with a text message when the user tap on a Quick Replies button.
Property | Type | Description |
---|---|---|
| String | Custom data provided by the app |
message.reply_to
A quick_reply
payload is only provided with a text message when the user tap on a Quick Replies button.
Property | Type | Description |
---|---|---|
| String | Reference to the message ID that this message is replying to |
message.attachments
Property | Type | Description |
---|---|---|
| String |
|
| String |
message.attachments.payload
Property | Type | Description |
---|---|---|
| String | URL of the attachment type. Applicable to attachment type: |
| String | Title of the attachment. Applicable to attachment type: |
| String | Persistent id of this sticker, for example |
| Number | Latitude. Applicable to attachment type: |
| Number | Longitude. Applicable to attachment type: |
message.attachments.payload.product.elements
Property | Type | Description |
---|---|---|
| String | Product ID from Facebook product catalog |
| String | External ID that is associated with the Product. (ex: SKU/ Content ID) |
| String | URL of product |
| String | Title of product |
| String | Subtitle of product |
message.referral
referral
payload is only provided when the user sends a message from Facebook Shops product detail page.
Property | Type | Description |
---|---|---|
| Object | Product information |
message.referral.product
Property | Type | Description |
---|---|---|
| String | Product ID |