Inbox Webhooks

Events for direct messages on Facebook and Instagram, with receipts, reactions, button taps and unsent messages.

Keep your inbox live for your Facebook Pages and Instagram accounts. Subscribe to these events, with no other setup. Each example is the payload's data.

Events

Event	Fires when	`senderId`	`recipientId`
`message.received`	Someone messages your account	The person	Your account
`message.sent`	Your account sends, here or on the platform	Your account	The person
`message.delivered`	Your messages reach the person	The person	Your account
`message.read`	The person reads your messages	The person	Your account
`message.reaction`	The person adds or removes a reaction	The person	Your account
`message.postback`	The person taps a button, menu item or ice breaker	The person	Your account
`message.deleted`	The person unsends a message, Instagram only	The person	Your account

Both ids are platform user ids. Your side is the Page or Instagram account id. The person's side is their page-scoped or Instagram-scoped id.

Every event has a conversationId. Use it with Send Message, Get Conversation and List Messages. See Inbox. Bluesky sends no inbox events.

Common Fields

Every event has these fields in data.object.

Prop

Type

message.received

{
  "object": {
    "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDUyOTA2MzE4Mjc0OjM0MDI4MjM2Njg0",
    "accountId": "acc_YOUR_INSTAGRAM_ACCOUNT_ID",
    "platform": "instagram",
    "conversationId": "cnv_sd3sE35Ae5QCQzR1AQWlKnfhbDnWJzlN7APMNxzAVnnlApQTAelwzTs2lziEqBjlT0YF4l1kmfGfnjxqELLhb4o5BPK5qNmAAw6MP5LpuDHNpTfiGIhK71qJdPeLh27PU6pQmQWsG0Hcx93oWUmna8cIRJ7TORfCh8PE",
    "senderId": "6845123987456321",
    "recipientId": "17841452906318274",
    "text": "Hi, is the large size back in stock?",
    "hasAttachments": false,
    "sentAt": "2027-03-15T14:05:11.000Z"
  }
}

id is the message's platform id, as in the inbox endpoints.
conversationId is the id Create Conversation returns. List Conversations may return another cnv_ id for it, and both work everywhere.
text is null for an attachment-only message. A quick reply tap arrives here, with its title as text.
hasAttachments is true for an image or other file. Read it with List Messages.

message.sent

{
  "object": {
    "id": "m_Xy7Tq2Lk9PzR4vWbN1sA8dE3fG6hJ0cM5uV2iO7yK4lB9nQ1rS6tU3wX8zC5aD2e",
    "accountId": "acc_YOUR_FACEBOOK_ACCOUNT_ID",
    "platform": "facebook",
    "conversationId": "cnv_8hWTlNv5W91f8vG9PyTrMWblwkWGiiSNXTNABrUoRpfy84mEKvN0dcP5HHKaz568DOcMk",
    "senderId": "104857392017465",
    "recipientId": "7012345678901234",
    "text": "Yes, it ships tomorrow.",
    "hasAttachments": false,
    "sentAt": "2027-03-15T14:07:30.000Z"
  }
}

The fields match message.received, with the sides reversed. senderId is your account. conversationId is the same.

message.delivered

{
  "object": {
    "accountId": "acc_YOUR_FACEBOOK_ACCOUNT_ID",
    "platform": "facebook",
    "conversationId": "cnv_8hWTlNv5W91f8vG9PyTrMWblwkWGiiSNXTNABrUoRpfy84mEKvN0dcP5HHKaz568DOcMk",
    "senderId": "7012345678901234",
    "recipientId": "104857392017465",
    "messageIds": [
      "m_Xy7Tq2Lk9PzR4vWbN1sA8dE3fG6hJ0cM5uV2iO7yK4lB9nQ1rS6tU3wX8zC5aD2e"
    ],
    "watermark": 1805119651000,
    "sentAt": "2027-03-15T14:07:31.000Z"
  }
}

messageIds lists the delivered messages. When it is empty, use watermark.
watermark is Unix milliseconds. Everything you sent before it was delivered. It can be null.

message.read

{
  "object": {
    "accountId": "acc_YOUR_FACEBOOK_ACCOUNT_ID",
    "platform": "facebook",
    "conversationId": "cnv_8hWTlNv5W91f8vG9PyTrMWblwkWGiiSNXTNABrUoRpfy84mEKvN0dcP5HHKaz568DOcMk",
    "senderId": "7012345678901234",
    "recipientId": "104857392017465",
    "watermark": 1805119712000,
    "sentAt": "2027-03-15T14:08:32.000Z"
  }
}

watermark is Unix milliseconds. Everything you sent in the conversation before it was read. It can be null. A read receipt names no message ids.

message.reaction

{
  "object": {
    "messageId": "m_Xy7Tq2Lk9PzR4vWbN1sA8dE3fG6hJ0cM5uV2iO7yK4lB9nQ1rS6tU3wX8zC5aD2e",
    "accountId": "acc_YOUR_FACEBOOK_ACCOUNT_ID",
    "platform": "facebook",
    "conversationId": "cnv_8hWTlNv5W91f8vG9PyTrMWblwkWGiiSNXTNABrUoRpfy84mEKvN0dcP5HHKaz568DOcMk",
    "senderId": "7012345678901234",
    "recipientId": "104857392017465",
    "action": "react",
    "reaction": "love",
    "emoji": "❤",
    "sentAt": "2027-03-15T14:09:02.000Z"
  }
}

messageId is the message the person reacted to.
action is react or unreact.
reaction names it, such as love, and emoji shows it. Both can be null, mostly on unreact.

message.postback

{
  "object": {
    "messageId": null,
    "accountId": "acc_YOUR_FACEBOOK_ACCOUNT_ID",
    "platform": "facebook",
    "conversationId": "cnv_8hWTlNv5W91f8vG9PyTrMWblwkWGiiSNXTNABrUoRpfy84mEKvN0dcP5HHKaz568DOcMk",
    "senderId": "7012345678901234",
    "recipientId": "104857392017465",
    "title": "Order status",
    "payload": "ORDER_STATUS",
    "sentAt": "2027-03-15T14:10:44.000Z"
  }
}

payload is the value you set on the button, menu item or ice breaker.
title is the text the person tapped.
messageId is the tap's id on Instagram, null on Facebook.

You set each payload where you create the item. Buttons come from Rich Messages, and the menu and ice breakers come from the Messenger Profile.

message.deleted

{
  "object": {
    "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDUyOTA2MzE4Mjc0OjM0MDI4MjM2Njg0",
    "accountId": "acc_YOUR_INSTAGRAM_ACCOUNT_ID",
    "platform": "instagram",
    "conversationId": "cnv_sd3sE35Ae5QCQzR1AQWlKnfhbDnWJzlN7APMNxzAVnnlApQTAelwzTs2lziEqBjlT0YF4l1kmfGfnjxqELLhb4o5BPK5qNmAAw6MP5LpuDHNpTfiGIhK71qJdPeLh27PU6pQmQWsG0Hcx93oWUmna8cIRJ7TORfCh8PE",
    "senderId": "6845123987456321",
    "recipientId": "17841452906318274",
    "sentAt": "2027-03-15T14:12:20.000Z"
  }
}

id is the unsent message, as in message.received. Remove your copy of it.

EventsCopy Anchor Link

Common FieldsCopy Anchor Link

message.receivedCopy Anchor Link

message.sentCopy Anchor Link

message.deliveredCopy Anchor Link

message.readCopy Anchor Link

message.reactionCopy Anchor Link

message.postbackCopy Anchor Link

message.deletedCopy Anchor Link

On this page