Messenger Platform

message_echoes Webhook Event Reference

Breaking Change Notice

Effective May 8, 2019, the parameter seq will always be 0 for all Messenger webhook events. This deprecation was announced on November 8, 2016. After Jul 31, 2019 the seq parameter will no longer be included in the webhook events. To de-duplicate messages use the mid parameter.

This callback will occur when a message has been sent by your page. You may receive text messsages or messages with attachments (image, video, audio, template or fallback). The payload will also include an optional custom metadata sent by the sender, and the corresponding app_id.
You can subscribe to this callback by selecting the message_echoes field when setting up your webhook.

Multiple types of messages are supported:

Common Format

Example 1

{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<USER_ID>"
  },
  "timestamp":1457764197627,
  "message":{
    "is_echo":true,
    "app_id":1517776481860111,
    "metadata": "<DEVELOPER_DEFINED_METADATA_STRING>",
    "mid":"mid.1457764197618:41d102a3e1ae206a38",
    ...
  }
}

Example 2

{
    "object": "page",
    "entry": [
        {
            "id": "<PAGEID>",
            "time": 1570053170926,
            "standby": [
                {
                    "sender": {
                        "id": "<PAGEID>"
                    },
                    "recipient": {
                        "id": "<PSID>"
                    },
                    "timestamp": 1570053170673,
                    "message": {
                        "mid": "qT7ywaKpO9kkQR7Gv-nM8LIfLZDamVrALniheUYEDdHJXjDXEAyaS1xxONzb2Iv-DFzmTihfWJV012P5pK0AhQ",
                        "is_echo": true,
                        "app_id": <APPID>,
                        "attachments": [
                            {
                                "title": "",
                                "url": "https:\/\/www.facebook.com\/commerce\/update\/",
                                "type": "template",
                                "payload": {
                                    "template_type": "media",
                                    "elements": [
                                        {
                                            "media_type": "image",
                                            "attachment_id": 2457235337685388
                                        }
                                    ]
                                }
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Properties

sender

PropertyTypeDescription

id

String

The PSID of the user that triggered the webhook event.

user_ref

String

The user_ref of the user that triggered the webhook event. This is only available for webhook event from the chat plugin.

recipient

PropertyTypeDescription

id

String

Your Page ID.

message

Field Name Type Description

is_echo

Boolean

Indicates the message sent from the page itself

app_id

String

ID of the app from which the message was sent

metadata

String

Custom string passed to the Send API as the metadata field. Only present if the metadata property was set in the original message.

mid

String

Message ID

Text message

Example

{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<USER_ID>"
  },
  "timestamp":1457764197627,
  "message":{
    "is_echo":true,
    "app_id":1517776481860111,
    "metadata": "<DEVELOPER_DEFINED_METADATA_STRING>",
    "mid":"mid.1457764197618:41d102a3e1ae206a38",
    "text":"hello, world!"
  }
}

Properties

message

Property Type Description

text

String

Text of message

Message with image, audio, video or file attachment

Example

{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<USER_ID>"
  },
  "timestamp":1458696618268,
  "message":{
    "is_echo":true,
    "app_id":1517776481860111,
    "metadata": "<DEVELOPER_DEFINED_METADATA_STRING>",
    "mid":"mid.1458696618141:b4ef9d19ec21086067",
    "attachments":[
      {
        "type":"image",
        "payload":{
          "url":"<IMAGE_URL>"
        }
      }
    ]
  }
}

Properties

message.attachments

Properties Type Description

type

String

Type of attachment: image, audio, video or file

payload.url

String

URL of attachment

Message with template attachment

Example

{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<USER_ID>"
  },
  "timestamp":1458696618268,
  "message":{
    "is_echo":true,
    "app_id":1517776481860111,
    "metadata": "<DEVELOPER_DEFINED_METADATA_STRING>",
    "mid":"mid.1458696618141:b4ef9d19ec21086067",
    "attachments":[
      {
        "type":"template",
        "payload":{
          "template_type":"button",
          "buttons":[
            {
              "type":"web_url",
              "url":"https:\/\/www.messenger.com\/",
              "title":"Visit Messenger"
            }
          ]
        }
      }
    ]
  }
}

Properties

message.attachments

Property Type Description

type

String

template

payload

String

Template payload as described in the Send API Reference

Note that in the case of a payload with attachments, the attachment id sent is a number not a string. See example 2

This does not match the format of Send API that needs the attachment id to be sent as a string.

Message with fallback attachment

A fallback attachment is any attachment not currently recognized or supported by the Message Echo feature.

Example

{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<USER_ID>"
  },
  "timestamp":1458696618268,
  "message":{
    "is_echo":true,
    "app_id":1517776481860111,
    "metadata": "<DEVELOPER_DEFINED_METADATA_STRING>",
    "mid":"mid.1458696618141:b4ef9d19ec21086067",
    "attachments":[
      {
        "title":"Legacy Attachment",
        "url":"https:\/\/www.messenger.com\/",
        "type":"fallback",
        "payload":null
      }
    ]
  }
}

Properties

message.attachments

Property Type Description

type

String

fallback

title

String

Title of attachment (optional)

url

String

URL of attachment (optional)

payload

String

Payload of attachment (optional)

Message with products

Message with products echo webhook is only available on Graph API v8.0+

App will need to have catalog_management permission approved to receive product details in webhooks.

Example

{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<USER_ID>"
  },
  "timestamp":1458696618268,
  "message":{
    "is_echo":true,
    "app_id":1517776481860111,
    "metadata": "<DEVELOPER_DEFINED_METADATA_STRING>",
    "mid":"mid.1458696618141:b4ef9d19ec21086067",
    "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",
               },
               {...},
             ]
            }

          ]
        }
      }
    ]
  }
}

Properties

product.elements

Property Type Description

id

String

Product ID from Facebook product catalog

retailer_id

String

External ID that is associated with the Product. (ex: SKU/ Content ID)

image_url

String

URL of product image

title

String

Title of product

subtitle

String

Subtitle of product