`messages` Webhook Event Reference

New Feature

On 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.

October 29, 2019 Announcement

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.

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>"
    }
  }
}

Reply Message

{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp":1458692752478,
  "message":{
    "mid":"m_1457764197618:41d102a3e1ae206a38",
    "text":"hello, world!",
    "reply_to": {
      "mid":"m_1fTq8oLumEyIp3Q2MR-aY7IfLZDamVrALniheU"
    }
  }
}

Message with 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

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"
                                }
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Properties

`sender`

Property	Type	Description
`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`

Property	Type	Description
`id`	String	Your Page ID.

`message`

March 4th, 2020 Announcement

For +v6.0 sticker_id was moved from message, to message.attachments.payload

Property	Type	Description
`mid`	String	Message ID
`text`	String	Text of message
`quick_reply`	Object	Optional custom data provided by the sending app
`reply_to`	Object	Reference to the message id (mid) that this message is replying to
`attachments`	Array<`attachment`>	Array containing attachment data

`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
`payload`	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
`mid`	String	Reference to the message ID that this message is replying to

`message.attachments`

Property	Type	Description
`type`	String	`audio`, `file`, `image`, `location`, `video` or `fallback`
`payload`	String	`message.attachments.payload`

`message.attachments.payload`

Property	Type	Description
`url`	String	URL of the attachment type. Applicable to attachment type: `audio`, `file`, `image`, `location`, `video`, `fallback`
`title`	String	Title of the attachment. Applicable to attachment type: `fallback`
`sticker_id`	String	Persistent id of this sticker, for example `369239263222822` references the Like sticker. Applicable to attachment type: `image` only if a sticker is sent.
`coordinates.lat`	Number	Latitude. Applicable to attachment type: `location`
`coordinates.long`	Number	Longitude. Applicable to attachment type: `location`

messages Webhook Event Reference