# message_echoes Webhook Event Reference



This callback occurs when your page sends a message. You may receive `text` messages or messages with attachments (`image`, `video`, `audio`, `sticker`, `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](https://developers.facebook.com/documentation/business-messaging/messenger-platform/webhooks#setup) your webhook.

Multiple types of messages are supported:

* [Text message](#text)
* [Message with image, audio, video, file, or sticker attachment](#binary)
* [Message with appointment booking](#appointment)
* [Message with template attachment](#template)
* [Message with fallback attachment](#fallback)
* [Message with products](#products)
* [Message which is a reply to another message](#reply)

## Common format {#format}

### Example 1

```json
{
  "sender":{
    "id":"<PAGE_ID>"
  },
  "recipient":{
    "id":"<PSID>"
  },
  "timestamp":1457764197627,
  "message":{
    "is_echo":true,
    "app_id":1517776481860111,
    "metadata": "<DEVELOPER_DEFINED_METADATA_STRING>",
    "mid":"mid.1457764197618:41d102a3e1ae206a38",
    ...
  }
}
```

### Example 2 {#example_2}

```json
{
    "object": "page",
    "entry": [
        {
            "id": "<PAGE_ID>",
            "time": 1570053170926,
            "standby": [
                {
                    "sender": {
                        "id": "<PAGE_ID>"
                    },
                    "recipient": {
                        "id": "<PSID>"
                    },
                    "timestamp": 1570053170673,
                    "message": {
                        "mid": "qT7ywaKpO9kkQR7Gv-nM8LIfLZDamVrALniheUYEDdHJXjDXEAyaS1xxONzb2Iv-DFzmTihfWJV012P5pK0AhQ",
                        "is_echo": true,
                        "app_id": <APPID>,
                        "attachments": [
                            {
                                "title": "",
                                "url": "https:\/\/www.facebook.com\/commerce\/update\/",
                                "type": "template",
                                "payload": {
                                    "template_type": "media",
                                    "elements": [
                                        {
                                            "media_type": "image",
                                            "attachment_id": 2457235337685388
                                        }
                                    ]
                                }
                            }
                        ]
                    }
                }
            ]
        }
    ]
}
```

### Properties {#properties}

### `sender`
| `sender` Field | Description |
| --- | --- |
| `id` *string* | The ID for your Facebook Page |

### `recipient`

| `recipient` Field | Description |
| --- | --- |
| `id` *string* | The Page-scoped ID for the person who received a message from your business |

### `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. Starting Graph API `v12.0`+, `app_id` field will return Facebook Page inbox app id (`26390203743090`) whenever the message is sent via Facebook Page inbox. |
| `metadata` | String | Custom string passed to the [Send API](https://developers.facebook.com/documentation/business-messaging/messenger-platform/reference/send-api#request) as the `metadata` field. Only present if the `metadata` property was set in the original message. |
| `mid` | String | Message ID |

## Text message {#text}

### Example

```json
{
  "sender":{
    "id":"<PAGE_ID>"
  },
  "recipient":{
    "id":"<PSID>"
  },
  "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, file, or sticker attachment {#binary}

### Example

```json
{
  "sender":{
    "id":"<PAGE_ID>"
  },
  "recipient":{
    "id":"<PSID>"
  },
  "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`, `file` or `sticker` |
| `payload.url` | String | URL of attachment |

## Message with appointment booking {#appointment}

### Example

```json
{
  "sender":{
    "id":"<PAGE_ID>"
  },
  "recipient":{
    "id":"<PSID>"
  },
  "timestamp":1458696618268,
  "message":{
    "is_echo":true,
    "app_id":1517776481860111,
    "metadata": "<DEVELOPER_DEFINED_METADATA_STRING>",
    "mid":"mid.1458696618141:b4ef9d19ec21086067",
    "attachments":[
      {
        "type":"appointment_booking",
        "payload": {
           "booking_id": "<BOOKING_ID>"
           "status": "<requested|confirmed|declined|cancelled>",
           "start_time": 1739612400,
           "end_time": 1739616000,
           "timezone": "America/Los_Angeles"
        }
      }
    ]
  }
}
```

### Properties

### `message.attachments`

| Properties | Type | Description |
| --- | --- | --- |
| `type` | String | Type of attachment: `appointment_booking` |
| `payload.booking_id` | String | ID of the booking associated with the appointment |
| `payload.status` | String | Current status of the appointment. Can be `requested`, `confirmed`, `declined`, `cancelled` |
| `payload.start_time` | Integer | Appointment start time as a Unix timestamp (seconds). |
| `payload.end_time` | Integer | Appointment end time as a Unix timestamp (seconds). |
| `payload.timezone` | String | IANA timezone identifier (e.g., `America/Los_Angeles`) |

## Message with template attachment {#template}

### Example

```json
{
  "sender":{
    "id":"<PAGE_ID>"
  },
  "recipient":{
    "id":"<PSID>"
  },
  "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](https://developers.facebook.com/documentation/business-messaging/messenger-platform/reference/send-api#request) |

**Note:** Note that in the case of a `payload` with attachments, the attachment id sent is a number not a string. See [example 2](#example_2)

This does not match the format of [Send API](https://developers.facebook.com/documentation/business-messaging/messenger-platform/reference/send-api#request) that needs the attachment id to be sent as a string.

## Message with fallback attachment {#fallback}

A fallback attachment is any attachment not currently recognized or supported by the Message Echo feature.

### Example

```json
{
  "sender":{
    "id":"<PAGE_ID>"
  },
  "recipient":{
    "id":"<PSID>"
  },
  "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) |

## Message with products {#products}

**Warning:** Message with products echo webhook is only available on Graph API v8.0+

App will need to have [`catalog_management`](https://developers.facebook.com/docs/permissions/reference/catalog_management) permission approved to receive product details in webhooks.

### Example

```json
{
  "sender":{
    "id":"<PAGE_ID>"
  },
  "recipient":{
    "id":"<PSID>"
  },
  "timestamp":1458696618268,
  "message":{
    "is_echo":true,
    "app_id":1517776481860111,
    "metadata": "<DEVELOPER_DEFINED_METADATA_STRING>",
    "mid":"mid.1458696618141:b4ef9d19ec21086067",
    "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",
               },
               {...},
             ]
            }

          ]
        }
      }
    ]
  }
}
```

### Properties

### `product.elements`

| Property | Type | Description |
| --- | --- | --- |
| `id` | String | Product ID from [product catalog](https://developers.facebook.com/documentation/ads-commerce/catalog/overview) |
| `retailer_id` | String | External ID that is associated with the Product. (ex: SKU/ Content ID) |
| `image_url` | String | URL of product image |
| `title` | String | Title of product |
| `subtitle` | String | Subtitle of product |

## Message which is a reply to another message {#reply}

A fallback attachment is any attachment not currently recognized or supported by the Message Echo feature.

### Example

```json
{
  "sender":{
    "id":"<PAGE_ID>"
  },
  "recipient":{
    "id":"<PSID>"
  },
  "timestamp":1458696618268,
  "message":{
    "is_echo":true,
    "app_id":1517776481860111,
    "metadata": "<DEVELOPER_DEFINED_METADATA_STRING>",
    "mid":"mid.1458696618141:b4ef9d19ec21086067",
    "reply_to": {
      "mid": "QUOTED-MESSAGE-ID",
      "is_self_reply" : false
     }
   }
}
```

### Properties

### `message.reply_to`

| Property | Type | Description |
| --- | --- | --- |
| `mid` | String | Reference to the message id that this message is replying to |
| `is_self_reply` | Boolean | Indicates whether the message is a self reply or not. |