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 product template

Message webhook with product template is only available on Graph API v8.0+

This webhook applies to the scenario when user shares products from other threads or sharing flow to the page. This webhook is limited to only products that are owned by the page. App will need to have catalog_management permission approved to receive product details in webhooks.

{
  "id": "682498302938465",
  "time": 1518479195594,
  "messaging": [
    {
      "sender": {
        "id": "<PSID>"
      },
      "recipient": {
        "id": "<PAGE_ID>"
      },
      "timestamp": 1518479195308,
      "message": {
        "mid": "mid.$cAAJdkrCd2ORnva8ErFhjGm0X_Q_c",
        "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",
                 },
                 {...},
               ]
            }
          }
        ]
      }
    }
  ]
}

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

Message from Facebook Shops Product Detail Page

Message webhook from Facebook Shops product detail page is only available on Graph API v8.0+

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

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

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

referral

Object

Referral of the message from Facebook Shops product details page.

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

message.attachments.payload.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

title

String

Title of product

subtitle

String

Subtitle of product

message.referral

referral payload is only provided when the user sends a message from Facebook Shops product detail page.

Property Type Description

product

Object

Product information

message.referral.product

Property Type Description

id

String

Product ID