Messenger Platform

messages 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 to your page. You may receive text messages or messages with attachments (template, image, audio, video, file, or location). You may also receive fallback attachments, which are attachments in Messenger other than the ones mentioned above. A common example is attachments created from link scraping. Messages are always sent in order.

You can subscribe to this callback by selecting message when setting up your webhook.

Examples

Text Message

{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp":1458692752478,
  "message":{
    "mid":"mid.1457764197618:41d102a3e1ae206a38",
    "text":"hello, world!",
    "quick_reply": {
      "payload": "<DEVELOPER_DEFINED_PAYLOAD>"
    }
  }
}

Message with blob attachment

{
  "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 with fallback attachment from link scraping


{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp":1458692752478,
  "message":{
    "mid":"mid.1458696618141:b4ef9d19ec21086067",
    "text":"<URL_SENT_BY_THE_USER>",
    "attachments":[
      {
        "type":"fallback",
        "payload":null,
      	"title":"<TITLE_OF_THE_URL_ATTACHMENT>",
      	"URL":"<URL_OF_THE_ATTACHMENT>",
      }
    ]
  }
}

Properties

sender

PropertyTypeDescription

id

String

The PSID of the user that triggered the webhook event.

recipient

PropertyTypeDescription

id

String

Your Page ID.

message

Property Type Description

mid

String

Message ID

text

String

Text of message

attachments

Array<attachment>

Array containing attachment data

quick_reply

Object

Optional custom data provided by the sending app

message.attachments

Property Type Description

type

String

template, audio, fallback, file, image, location or video

payload

String

multimedia or location payload

message.quick_reply

Property Type Description

payload

String

Custom data provided by the app

A quick_reply payload is only provided with a text message when the user tap on a Quick Replies button.

image, audio, video or file payload

Property Type Description

url

String

URL of the file

location payload

Property Type Description

coordinates.lat

Number

Latitude

coordinates.long

Number

Longitude

attachment.fallback object

Property Type Description

title

String

Title of the attachment

url

URL

URL to the attachment

payload

null

null

type

String

fallback