messenger.inbound_message.received

Use messenger.inbound_message.received to handle this event at your webhook endpoint.

Triggers

Occurs when an ordinary Messenger text message is received from a customer. Subscribe to messenger.inbound_message.received when you configure your webhook endpoint. from is the customer’s Page-scoped ID (PSID), and to is the Facebook Page ID. These identifiers are not phone numbers. Preserve leading and trailing whitespace in text.body.

Syntax

YCloud sends an HTTP POST request to your configured webhook URL. The following shape shows one payload variant. Angle-bracket values are placeholders; their types are listed under Parameters. Optional fields and other variants are described below.

{
  "id": "<ID>",
  "type": "messenger.inbound_message.received",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "messengerInboundMessage": {
    "id": "<ID>",
    "metaMessageId": "<META_MESSAGE_ID>",
    "from": "<FROM>",
    "to": "<TO>",
    "type": "<TYPE>",
    "text": {
      "body": "<BODY>"
    },
    "sendTime": "<SEND_TIME>",
    "createTime": "<CREATE_TIME>"
  }
}

Parameters

Validate the YCloud-Signature HTTP header before you process the JSON body. See signature validation.

Event envelope

Parameter	Type	Required	Description
`id`	string	Yes	Unique ID for the event. Minimum length: `6`. Maximum length: `128`.
`type`	string	Yes	Always `messenger.inbound_message.received`.
`apiVersion`	string	Yes	The API version used to render this event.
`createTime`	string (date-time)	Yes	The time at which this event was created, formatted in RFC 3339. e.g., `2022-06-01T12:00:00.000Z`.

Event payload

Parameter	Type	Required	Description
`messengerInboundMessage`	object	No	Event-specific `messengerInboundMessage` payload.

The four common envelope fields are required. Payload fields depend on the event variant. In each object table, Required applies when its parent object is present. Optional fields can be omitted; a sample does not make a field required.

messengerInboundMessage

Parameter	Type	Required	Description
`id`	string	Yes	YCloud inbound message ID as a decimal string.
`metaMessageId`	string	Yes	Meta message ID.
`from`	string	Yes	Customer PSID scoped to the Facebook Page.
`to`	string	Yes	Facebook Page ID.
`type`	string	Yes	Values: `text`.
`text`	object	Yes	Object fields are listed below.
`sendTime`	string (date-time)	Yes	Saved source event time in UTC RFC 3339 with millisecond precision.
`createTime`	string (date-time)	Yes	Local persistence time in UTC RFC 3339 with millisecond precision.
`editCount`	integer	No	Cumulative edit count supplied by Meta. Omitted before the first edit.
`editTime`	string (date-time)	No	Saved platform edit time in UTC RFC 3339 with millisecond precision. Omitted before the first edit.

messengerInboundMessage.text

Parameter	Type	Required	Description
`body`	string	Yes	Nonblank text. Leading and trailing spaces are preserved and included when comparing a repeated request. Minimum length: `1`.

Example

The following JSON is the body delivered to your receiver. IDs, phone numbers, and other account values are illustrative. Use messengerInboundMessage.id to correlate repeated customer messages; preserve text whitespace.

{
  "id": "evt_0123456789abcdef01234567",
  "type": "messenger.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:00.000Z",
  "messengerInboundMessage": {
    "id": "1308528868252065793",
    "metaMessageId": "m_EXAMPLE_IN_001",
    "from": "100800000000000",
    "to": "422500000000000",
    "type": "text",
    "text": {
      "body": "  Hello  "
    },
    "sendTime": "2026-10-20T02:00:00.000Z",
    "createTime": "2026-10-20T02:00:00.100Z"
  }
}

After verifying the signature and durably accepting the event, return a 2xx response. Process slow work asynchronously.

HTTP/1.1 200 OK

Getting Started

Guides

Endpoints

Webhook reference

messenger.inbound_message.received

Triggers

Syntax

Parameters

Event envelope

Event payload

messengerInboundMessage

Example

​Triggers

​Syntax

​Parameters

​Event envelope

​Event payload

​messengerInboundMessage

​Example

Triggers

Syntax

Parameters

Event envelope

Event payload

messengerInboundMessage

Example