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

PropertyTypeDescription

id

String

The PSID of the user that triggered the webhook event.

recipient

PropertyTypeDescription

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