messages
Webhook Event ReferenceThis 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
, reel
, and ig_reel
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|reel|ig_reel>",
"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 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>" } } } }
This webhook applies to the scenario when a user clicks on a CTM (Click-to-Messenger) advertisement and sends a message to a Facebook page. In addition to the message details included, the application will receive ads referral information.
Message with Ads Referral Information requires the application to have page subscriptions to both the messages
and the messaging_referrals
fields.
{ "sender":{ "id":"<PSID>" }, "recipient":{ "id":"<PAGE_ID>" }, "timestamp":1458692752478, "message":{ "mid":"mid.1457764197618:41d102a3e1ae206a38", "text":"hello, world!", "referral": { "ref": "<REF_DATA_IF_SPECIFIED_IN_THE_AD>", "ad_id": "<ID_OF_THE_AD>", "source": "ADS", "type": "OPEN_THREAD", "ads_context_data": { "ad_title": "<TITLE_OF_THE_AD>", "photo_url": "<URL_OF_THE_IMAGE_FROM_AD_THE_USER_IS_INTERESTED_IN>", "video_url": "<THUMBNAIL_URL_OF_THE_VIDEO_FROM_THE_AD>", "post_id": "<ID_OF_THE_POST>", "product_id": "<PRODUCT_ID>" } } } }
{ "object": "page", "entry": [ { "id": "<PAGE_ID>", "time": 1697643211842, "messaging": [ { "sender": { "id": "<PSID>" }, "recipient": { "id": "<PAGE_ID>" }, "timestamp": 1697643027400, "message": { "mid": "m_3vs...", "text": "find flights from SFO to LAX next Thursday", "commands": [ { "name": "flights" } ] } } ] } ] }
sender
sender Field | Description |
---|---|
| The Page-scoped ID for the person who sent a message to your business |
| The reference for a person who used the Chat Plugin to messsage your business |
recipient
recipient Field | Description |
---|---|
| The ID for your Facebook Page |
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 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
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: |
| Number | Persistent id of this sticker, for example |
| Number | ID of the video associated with the attached reel. 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 Shops product detail page.
Property | Type | Description |
---|---|---|
| Object | Product information |
| String | The source of the referral. Supported values: |
| String | The referral type. Currently supports |
| String | The optional |
| String | Advertisement ID from Ads Manager. |
| Object | Advertisement context data from Ads Manager. |
message.referral.product
Property | Type | Description |
---|---|---|
| String | Product ID |
message.referral.ads_context_data
Property | Type | Description |
---|---|---|
| String | Title of the ad in Ads Manager. |
| String | [Optional] URL of the image from the ad. |
| String | [Optional] Thumbnail URL of the video from the ad. |
| String | ID of the ad post in Ads manager. |
| String | [Optional] Product ID from the ad. |
message.commands
Property | Type | Description |
---|---|---|
| String | The name of the command |