Desenvolvedores

Mensagem - Atualização

Configure um webhook de saída em /integration, ative-o e selecione MESSENGER / Mensagem: Criação e/ou Atualização. Recebe uma mensagem persistida por POST, com room, project, eventName, eventType, eventDt e verifyKey. Inclui mensagens recebidas e enviadas, de agentes, bots e disparos; Atualização inclui edições e mudanças de status realizadas pelo serviço. Só integrações ativas do mesmo projeto e inscritas neste evento recebem a entrega. Em atualização em lote, cada mensagem gera uma entrega. Não há filtro de room no cadastro; o consumidor pode filtrar pelo room recebido. O limite de 500 e as 300 consultas/minuto são exclusivos da listagem REST e não limitam estes eventos. files inclui downloadUrl, downloadUrlExpiresAt (null) e downloadRequiresAuth. Nenhum arquivo é baixado, consultado no storage ou assinado ao preparar o webhook. URLs temporárias já recebidas de Facebook/Instagram podem ser reutilizadas sem chamada adicional; demais anexos usam as mesmas rotas sob demanda da API. Quando downloadRequiresAuth=true, chame a URL relativa no host da API com X-API-Key de uma chave do mesmo projeto e siga redirecionamentos. Download revalida projeto e arquivo. Responda 200 rapidamente; o timeout é de 30 segundos. Falhas usam o registro e job de reenvio existentes, executado aproximadamente a cada 12 minutos. A entrega pode se repetir: deduplique por eventName, _id e updatedAt. A integração é desativada após 10 falhas consecutivas em até uma hora; sucesso limpa o contador.

Desenvolvedor

Evento

POST messenger/chat/message/patch

Como receber

Configure uma URL HTTPS pública para receber este evento e responda rapidamente com status de sucesso após aceitar o payload.

Payload

Content-Type: application/json

Campo	Tipo	Obrigatório	Valores / Exemplo	Descrição
header	object	Não
footer	object	Não
btns	object	Não
message	string	Não
reaction	boolean	Não
files	MessengerChatMessageDownloadFile	Não
user	string	Não
tl	string	Não
templateId	string	Não
templateVars	object	Não
event	string	Não
evtData	object	Não
room	string	Sim		Sala à qual a mensagem pertence.
fromBot	boolean	Não
isOpt	boolean	Não
isInternal	boolean	Não
chMsgId	string	Não
chProfile	object	Não
mentions	object	Não
meta	object	Não
status	number	Não
editedAt	string (date-time)	Não
replyTo	string	Não
isDel	boolean	Não
updatedAt	string (date-time)	Não
createdAt	string (date-time)	Não
_id	string	Sim		ID persistido da mensagem; use junto de eventName e updatedAt para deduplicar entregas.
project	string	Sim		Projeto da mensagem e da integração.
eventName	string	Sim	Aceita: messenger/chat/message/create, messenger/chat/message/patch
eventType	string	Sim
eventDt	string (date-time)	Não		Data da tentativa de envio.
verifyKey	string	Sim		Compare com a chave de verificação do cadastro da integração.

Estruturas internas

files

[
  {
    "downloadUrl": [
      "string",
      "null"
    ],
    "downloadUrlExpiresAt": "string,null (date-time)",
    "downloadRequiresAuth": "boolean"
  }
]

Exemplo básico recebido:

{
  "_id": "665f1f0d6b4b2f00127a0001",
  "room": "665f1f0d6b4b2f00127a0002",
  "project": "665f1f0d6b4b2f00127a0003",
  "message": "Segue o documento",
  "eventName": "messenger/chat/message/patch",
  "eventType": "db",
  "eventDt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:00:00.000Z",
  "verifyKey": "CHAVE_DE_VERIFICACAO_DO_WEBHOOK",
  "files": [
    {
      "name": "documento.pdf",
      "mimetype": "application/pdf",
      "downloadUrl": "/messenger/chat/downloadMessageFile/665f1f0d6b4b2f00127a0001/0",
      "downloadUrlExpiresAt": null,
      "downloadRequiresAuth": true
    }
  ]
}

Respostas

Status	Descrição	Conteúdo
200	Evento recebido pelo consumidor.

Boas práticas

Trate reenvios como possibilidade real.
Valide o payload antes de executar regras de negócio.
Registre o identificador do evento ou do registro recebido para auditoria.