Messenger Platform

message_echoes Webhook Event Reference

Breaking Change Notice

Effective February 19, 2018, this webhook event will no longer be triggered by message sends that use recipient.user_ref or recipient.phone_number to identify the message recipient.

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

{
  "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",
    ...
  }
}

Properties

sender

PropertyTypeDescription

id

String

The PSID of the user that triggered the webhook event.

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

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)