messenger.inbound_message.received

Use messenger.inbound_message.received para processar este evento no seu endpoint de webhook.

Gatilhos

Ocorre quando uma mensagem de texto comum do Messenger é recebida de um cliente. Inscreva-se em messenger.inbound_message.received ao configurar seu endpoint de webhook. from é o ID com escopo da Página (PSID) do cliente, e to é o ID da Página do Facebook. Esses identificadores não são números de telefone. Preserve os espaços em branco à esquerda e à direita em text.body.

Sintaxe

A YCloud envia uma solicitação HTTP POST para a URL de webhook configurada. A estrutura a seguir mostra uma variante do payload. Os valores entre colchetes angulares são marcadores de posição; seus tipos estão listados em Parâmetros. Campos opcionais e outras variantes são descritos abaixo.

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

Parâmetros

Valide o cabeçalho HTTP YCloud-Signature antes de processar o corpo JSON. Consulte validação de assinatura.

Envelope do evento

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID exclusivo do evento. Comprimento mínimo: `6`. Comprimento máximo: `128`.
`type`	string	Sim	Sempre `messenger.inbound_message.received`.
`apiVersion`	string	Sim	A versão da API usada para renderizar este evento.
`createTime`	string (date-time)	Sim	O momento em que este evento foi criado, formatado em RFC 3339. Por exemplo, `2022-06-01T12:00:00.000Z`.

Payload do evento

Parâmetro	Tipo	Obrigatório	Descrição
`messengerInboundMessage`	object	Não	Payload do `messengerInboundMessage` específico do evento.

Os quatro campos comuns do envelope são obrigatórios. Os campos do payload dependem da variante do evento. Em cada tabela de objeto, Obrigatório se aplica quando o objeto pai estiver presente. Campos opcionais podem ser omitidos; um exemplo não torna um campo obrigatório.

messengerInboundMessage

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID da mensagem recebida da YCloud como uma string decimal.
`metaMessageId`	string	Sim	ID da mensagem da Meta.
`from`	string	Sim	PSID do cliente com escopo definido para a Página do Facebook.
`to`	string	Sim	ID da Página do Facebook.
`type`	string	Sim	Valores: `text`.
`text`	object	Sim	Os campos do objeto estão listados abaixo.
`sendTime`	string (date-time)	Sim	Horário salvo do evento de origem em UTC RFC 3339 com precisão de milissegundos.
`createTime`	string (date-time)	Sim	Horário de persistência local em UTC RFC 3339 com precisão de milissegundos.
`editCount`	integer	Não	Contagem cumulativa de edições fornecida pela Meta. Omitido antes da primeira edição.
`editTime`	string (date-time)	Não	Horário salvo da edição na plataforma em UTC RFC 3339 com precisão de milissegundos. Omitido antes da primeira edição.

messengerInboundMessage.text

Parâmetro	Tipo	Obrigatório	Descrição
`body`	string	Sim	Texto não vazio. Espaços à esquerda e à direita são preservados e incluídos ao comparar uma solicitação repetida. Comprimento mínimo: `1`.

Exemplo

O JSON a seguir é o corpo entregue ao seu receptor. IDs, números de telefone e outros valores de conta são ilustrativos. Use messengerInboundMessage.id para correlacionar mensagens repetidas de clientes; preserve os espaços em branco do texto.

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

Depois de verificar a assinatura e aceitar o evento de forma duradoura, retorne uma resposta 2xx. Processe tarefas lentas de forma assíncrona.

HTTP/1.1 200 OK

Primeiros passos

Guias

Endpoints

Webhook reference

messenger.inbound_message.received

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

messengerInboundMessage

Exemplo

​Gatilhos

​Sintaxe

​Parâmetros

​Envelope do evento

​Payload do evento

​messengerInboundMessage

​Exemplo

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

messengerInboundMessage

Exemplo