Toda chamada é um POST por HTTPS com corpo JSON. O corpo sempre traz os mesmos cinco campos, e só o conteúdo de payload muda conforme o evento. Os valores abaixo são exemplos.

Corpo da chamada

{
  "retailerId": "aB3dE5gH7j",
  "origin": "conversational",
  "type": "chat-routed",
  "traceId": "6710a3f2c9e77b0012ab34cd",
  "payload": {}
}

Campo	Tipo	Descrição
`retailerId`	string	ID da sua loja na OmniChat.
`origin`	string	Origem do evento: `conversational` (atendimentos) ou `campaign` (campanhas).
`type`	string	Tipo do evento.
`traceId`	string	ID do evento. Uma nova tentativa repete o mesmo valor: use-o para ignorar eventos repetidos.
`payload`	object	Dados do evento. O conteúdo muda conforme o tipo.

Um evento é identificado pelo par origin + type. O tipo message-status existe nas duas origens, com conteúdos diferentes.

Datas em texto seguem ISO 8601 em UTC. Nos eventos de campanha, timestamp vem em milissegundos desde 01/01/1970 (UTC). Campos marcados como opcionais podem não vir no JSON.

Campos comuns dos eventos de atendimento

Campo	Tipo	Descrição
`payload.timeStamp`	string	Data e hora do evento, em ISO 8601 (UTC).
`payload.objectId`	string	ID da conversa na OmniChat.
`payload.chatId`	string	Identificador do contato no canal, como o número no WhatsApp.
`payload.csrId`	string, opcional	ID do atendimento.
`payload.internalState`	string	Estado da conversa: `INITIAL`, `BOT`, `BOT_V2`, `USER`, `TEAM`, `UNASSIGNED` ou `FINISHED`.
`payload.platform`	string	Canal da conversa, como `WHATSAPP`, `WAB`, `INSTAGRAM` ou `WEBCHAT`.

`conversational` / `chat-routed`: Atendimento roteado

{
  "timeStamp": "2026-10-13T14:32:05.120Z",
  "objectId": "Qw3Er5Ty7U",
  "chatId": "5511999990000",
  "csrId": "Zx9Cv8Bn7M",
  "routedBy": {
    "id": "Us3rAn41D",
    "name": "Ana Souza",
    "username": "ana.souza@lojabella.com.br",
    "userType": "USER"
  },
  "fromType": "TEAM",
  "to": {
    "id": "Us3rJ0a01",
    "name": "João Pereira",
    "username": "joao.pereira@lojabella.com.br",
    "userType": "USER"
  },
  "toType": "USER",
  "routeType": "USER",
  "platform": "WHATSAPP"
}

Campo	Tipo	Descrição
`payload.routedBy`	object, opcional	Quem encaminhou: `id`, `name`, `username` e `userType` (`BOT`, `API` ou `USER`). Não vem quando o encaminhamento é automático, como por SLA.
`payload.fromType`	string, opcional	Com quem a conversa estava: `USER` (pessoa), `TEAM` (time) ou `UNASSIGNED` (sem responsável).
`payload.to`	object, opcional	Para quem a conversa foi: `id` e `name`. Para uma pessoa, também `username` e `userType`.
`payload.toType`	string	Destino: `USER` (pessoa), `TEAM` (time) ou `UNASSIGNED` (sem responsável).
`payload.routeType`	string	Motivo do encaminhamento: `BOT`, `USER`, `MASSIVE_TRANSFER`, `SLA`, `INACTIVITY`, `DEFAULT_TEAM` ou `HANDOFF`.

Também traz timeStamp, objectId, chatId, csrId e platform (campos comuns).

`conversational` / `chat-finished`: Atendimento encerrado

{
  "timeStamp": "2026-10-13T14:32:05.120Z",
  "objectId": "Qw3Er5Ty7U",
  "chatId": "5511999990000",
  "internalState": "FINISHED",
  "platform": "WHATSAPP",
  "csrId": "Zx9Cv8Bn7M",
  "finishedBy": {
    "id": "Us3rAn41D",
    "name": "Ana Souza",
    "username": "ana.souza@lojabella.com.br",
    "userType": "USER"
  },
  "closingReason": "Compra concluída",
  "finishType": "USER",
  "from": {
    "id": "Us3rAn41D",
    "userType": "USER"
  },
  "fromType": "USER",
  "isReplied": true
}

Campo	Tipo	Descrição
`payload.finishedBy`	object, opcional	Quem encerrou: `id`, `name`, `username` e `userType`. Não vem quando o encerramento é automático.
`payload.closingReason`	string, opcional	Motivo de encerramento informado.
`payload.finishType`	string	`USER` (encerramento de uma conversa) ou `MASSIVE_FINISH` (encerramento em massa).
`payload.from`	object, opcional	Com quem a conversa estava antes do encerramento: pessoa ou time.
`payload.fromType`	string, opcional	`USER` (pessoa), `TEAM` (time) ou `UNASSIGNED` (sem responsável).
`payload.isReplied`	boolean, opcional	Indica se o contato recebeu resposta desde o último encaminhamento.

Também traz os campos comuns.

`conversational` / `chat-pipeline-stage-changed`: Mudança de etapa no funil

{
  "timeStamp": "2026-10-13T14:32:05.120Z",
  "objectId": "Qw3Er5Ty7U",
  "chatId": "5511999990000",
  "internalState": "USER",
  "stageId": "St4g3N3g0c",
  "stageName": "Negociação",
  "stagePosition": 2,
  "pipelineId": "P1p3l1n3Vd"
}

Campo	Tipo	Descrição
`payload.stageId`	string	ID da nova etapa do funil.
`payload.stageName`	string	Nome da nova etapa do funil.
`payload.stagePosition`	number	Posição da nova etapa no funil.
`payload.pipelineId`	string, opcional	ID do funil.

Também traz timeStamp, objectId, chatId e internalState. Este evento não traz platform.

`conversational` / `message-received`: Mensagem recebida

{
  "timeStamp": "2026-10-13T14:32:05.120Z",
  "objectId": "Qw3Er5Ty7U",
  "chatId": "5511999990000",
  "csrId": "Zx9Cv8Bn7M",
  "internalState": "USER",
  "platform": "WHATSAPP",
  "teamId": "T3amP0s1D",
  "to": {
    "id": "Us3rAn41D",
    "name": "Ana Souza",
    "username": "ana.souza@lojabella.com.br",
    "userType": "USER"
  },
  "customer": {
    "id": "Cu5t0m3r1",
    "name": "Maria Lima"
  },
  "phone": {
    "number": "999990000",
    "areaCode": "11",
    "countryCode": "55"
  },
  "message": {
    "id": "M3ss4g3Id1",
    "externalId": "wamid.EXEMPLO1",
    "text": "Olá, meu pedido já saiu?",
    "content": "Olá, meu pedido já saiu?",
    "type": "TEXT",
    "status": "INCOMING_RECEIVED",
    "platform": "WHATSAPP",
    "createdAt": "2026-10-13T14:32:04.870Z",
    "updatedAt": "2026-10-13T14:32:04.870Z",
    "isNewChat": false
  }
}

Campo	Tipo	Descrição
`payload.teamId`	string, opcional	ID do time responsável pela conversa.
`payload.botInteractionOwnerId`	string, opcional	ID de quem passou a conversa para o bot.
`payload.to`	object, opcional	Responsável atual pela conversa: `id` e `name`. Para uma pessoa, também `username` e `userType`.
`payload.customer`	object	Contato: `id` e `name`. Pode vir `null`.
`payload.phone`	object	Telefone do contato: `number`, `areaCode` e `countryCode`. Pode vir `null`.
`payload.message.id`	string	ID da mensagem na OmniChat.
`payload.message.externalId`	string, opcional	ID da mensagem no canal.
`payload.message.text`	string, opcional	Texto da mensagem.
`payload.message.content`	string, opcional	URL do anexo ou, se não houver anexo, o texto.
`payload.message.type`	string	Tipo da mensagem, como `TEXT`, `IMAGE`, `AUDIO`, `DOCUMENT`, `TEMPLATE` ou `BUTTON`.
`payload.message.status`	string	Status da mensagem, como `INCOMING_RECEIVED`.
`payload.message.contactOrigin`	object, opcional	De onde veio o contato, como uma campanha ou um anúncio: `id`, `name` e `token`.
`payload.message.systemMessageDetails`	object, opcional	Detalhes de mensagens geradas pelo sistema.
`payload.message.platform`	string, opcional	Canal da mensagem.
`payload.message.createdAt`	string	Criação da mensagem, em ISO 8601 (UTC).
`payload.message.updatedAt`	string	Última atualização da mensagem, em ISO 8601 (UTC).
`payload.message.structuredData`	object, opcional	Dados estruturados, como a resposta de um WhatsApp Flow ou de um pagamento.
`payload.message.isNewChat`	boolean, opcional	Indica se a mensagem abriu uma nova conversa.

Também traz os campos comuns.

`conversational` / `message-sent`: Mensagem enviada

Notas internas não geram este evento.

{
  "timeStamp": "2026-10-13T14:32:05.120Z",
  "objectId": "Qw3Er5Ty7U",
  "chatId": "5511999990000",
  "csrId": "Zx9Cv8Bn7M",
  "internalState": "USER",
  "platform": "WHATSAPP",
  "teamId": "T3amP0s1D",
  "from": {
    "id": "Us3rAn41D",
    "name": "Ana Souza",
    "username": "ana.souza@lojabella.com.br",
    "userType": "USER"
  },
  "customer": {
    "id": "Cu5t0m3r1",
    "name": "Maria Lima"
  },
  "phone": {
    "number": "999990000",
    "areaCode": "11",
    "countryCode": "55"
  },
  "message": {
    "id": "M3ss4g3Id2",
    "text": "Já saiu, sim. Chega amanhã.",
    "content": "Já saiu, sim. Chega amanhã.",
    "type": "TEXT",
    "status": "OUTGOING_CREATED",
    "createdAt": "2026-10-13T14:33:10.402Z",
    "updatedAt": "2026-10-13T14:33:10.402Z"
  }
}

Campo	Tipo	Descrição
`payload.teamId`	string, opcional	ID do time responsável pela conversa.
`payload.botInteractionOwnerId`	string, opcional	ID de quem passou a conversa para o bot.
`payload.from`	object, opcional	Quem enviou: `id`, `name`, `username` e `userType` (`BOT`, `API`, `SUPPORT` ou `USER`).
`payload.customer`	object	Contato: `id` e `name`. Pode vir `null`.
`payload.phone`	object	Telefone do contato: `number`, `areaCode` e `countryCode`. Pode vir `null`.
`payload.message.id`	string	ID da mensagem na OmniChat.
`payload.message.externalId`	string, opcional	ID da mensagem no canal.
`payload.message.text`	string, opcional	Texto da mensagem.
`payload.message.content`	string	URL do anexo ou, se não houver anexo, o texto.
`payload.message.type`	string	Tipo da mensagem, como `TEXT`, `IMAGE`, `AUDIO`, `DOCUMENT`, `TEMPLATE` ou `BUTTON`.
`payload.message.status`	string	Status da mensagem, como `OUTGOING_CREATED`.
`payload.message.templateId`	string, opcional	ID do template usado no envio.
`payload.message.contactOrigin`	object, opcional	De onde veio o contato: `id`, `name` e `token`.
`payload.message.createdAt`	string	Criação da mensagem, em ISO 8601 (UTC).
`payload.message.updatedAt`	string	Última atualização da mensagem, em ISO 8601 (UTC).
`payload.message.assistedByFeature`	string, opcional	Recurso de IA que ajudou a escrever a mensagem.
`payload.message.apiMetaData`	object, opcional	Dados do envio pela API do WhatsApp.

Também traz os campos comuns.

`conversational` / `message-status`: Status da mensagem

Este evento sai quando muda o status de entrega de uma mensagem enviada por campanha ou por outra origem registrada no contato, como um disparo pela API (contactOrigin). Mensagens enviadas pelos agentes no atendimento não geram este evento. Ele também sai com OUTGOING_ERROR quando um envio de campanha falha antes de a mensagem existir: nesse caso, objectId e chatId não vêm.

{
  "timeStamp": "2026-10-13T14:32:05.120Z",
  "objectId": "Qw3Er5Ty7U",
  "chatId": "5511999990000",
  "csrId": "Zx9Cv8Bn7M",
  "internalState": "USER",
  "platform": "WHATSAPP",
  "message": {
    "id": "M3ss4g3Id3",
    "externalId": "wamid.EXEMPLO3",
    "type": "TEMPLATE",
    "status": "OUTGOING_DELIVERED",
    "contactOrigin": {
      "id": "C4mp4nh41D",
      "name": "Volta às aulas",
      "token": "CAMPAIGN"
    },
    "dispatchId": "D1sp4tch01"
  }
}

Campo	Tipo	Descrição
`payload.timeStamp`	string	Data e hora do evento, em ISO 8601 (UTC).
`payload.objectId`, `chatId`, `csrId`, `internalState`, `platform`	string, opcionais	Como nos campos comuns. Neste evento, todos podem não vir.
`payload.message.id`	string, opcional	ID da mensagem na OmniChat.
`payload.message.externalId`	string, opcional	ID da mensagem no canal.
`payload.message.type`	string, opcional	Tipo da mensagem.
`payload.message.status`	string	Status da mensagem, como `OUTGOING_SENT`, `OUTGOING_DELIVERED`, `OUTGOING_READ` ou `OUTGOING_ERROR`.
`payload.message.contactOrigin`	object	De onde veio o contato: `id`, `name` e `token`.
`payload.message.dispatchId`	string, opcional	ID do disparo de campanha ou da API.
`payload.message.context`	object, opcional	Contexto enviado junto com o disparo.
`payload.message.error`	object, opcional	Erro de entrega: `code` e `message`.
`payload.message.apiMetaData`	object, opcional	Dados do envio pela API do WhatsApp.

`campaign` / `message-replies`: Resposta de campanha

{
  "campaign": {
    "id": "C4mp4nh41D",
    "name": "Volta às aulas"
  },
  "dispatch": {
    "id": "D1sp4tch01"
  },
  "template": {
    "id": "T3mpl4t301"
  },
  "message": {
    "id": "M3ss4g3Id4",
    "text": "Quero saber mais",
    "type": "BUTTON",
    "status": "INCOMING_RECEIVED",
    "replyType": "QUICK_REPLY"
  },
  "contact": {
    "phoneNumber": "5511999990000"
  },
  "timestamp": 1791902525120
}

Campo	Tipo	Descrição
`payload.campaign`	object	Campanha respondida: `id` e `name`.
`payload.dispatch`	object	Disparo da campanha: `id`.
`payload.template`	object	Template da mensagem de campanha: `id`.
`payload.message.id`	string	ID da mensagem na OmniChat.
`payload.message.text`	string, opcional	Texto da mensagem.
`payload.message.type`	string, opcional	Tipo da mensagem.
`payload.message.status`	string, opcional	Status da mensagem.
`payload.message.replyType`	string	`QUICK_REPLY` (clique em botão), `FREEFORM_REPLY` (texto livre) ou `LINK_REPLY` (clique em link).
`payload.message.url`	string, opcional	Link da campanha que o contato clicou.
`payload.message.queryParams`	array, opcional	Parâmetros do link de destino, em pares `name` e `value`. Vem vazio quando não há parâmetros.
`payload.message.context`	object, opcional	Contexto da mensagem de campanha respondida.
`payload.contact`	object	Contato que respondeu: `phoneNumber`, o identificador no canal (no WhatsApp, o número).
`payload.type`	string, opcional	`LINK_REPLY`, quando o evento vem de um clique em link.
`payload.timestamp`	number	Data e hora do envio do evento, em milissegundos desde 01/01/1970 (UTC).

Quando o contato clica num link da campanha, o evento vem sem message.text, message.type e message.status, e traz message.url, message.queryParams e payload.type igual a LINK_REPLY.

`campaign` / `message-status`: Status da mensagem de campanha

{
  "campaign": {
    "id": "C4mp4nh41D"
  },
  "dispatch": {
    "id": "D1sp4tch01"
  },
  "message": {
    "id": "M3ss4g3Id3",
    "status": "OUTGOING_DELIVERED"
  },
  "contact": {
    "phoneNumber": "5511999990000"
  },
  "timestamp": 1791901925120
}

Campo	Tipo	Descrição
`payload.campaign`	object	Campanha da mensagem: `id`.
`payload.dispatch`	object	Disparo da campanha: `id`.
`payload.message.id`	string, opcional	ID da mensagem na OmniChat.
`payload.message.status`	string	Status da mensagem, como `OUTGOING_SENT`, `OUTGOING_DELIVERED`, `OUTGOING_READ` ou `OUTGOING_ERROR`.
`payload.message.context`	object, opcional	Contexto enviado junto com o disparo.
`payload.message.error`	object, opcional	Erro de entrega: `code` e `message`.
`payload.contact`	object	Contato que recebeu a mensagem: `phoneNumber`, o identificador no canal (no WhatsApp, o número).
`payload.timestamp`	number	Data e hora do envio do evento, em milissegundos desde 01/01/1970 (UTC).

Referência de eventos e campos

Corpo da chamada

Campos comuns dos eventos de atendimento

conversational / chat-routed: Atendimento roteado

conversational / chat-finished: Atendimento encerrado

conversational / chat-pipeline-stage-changed: Mudança de etapa no funil

conversational / message-received: Mensagem recebida

conversational / message-sent: Mensagem enviada

conversational / message-status: Status da mensagem

campaign / message-replies: Resposta de campanha

campaign / message-status: Status da mensagem de campanha

`conversational` / `chat-routed`: Atendimento roteado

`conversational` / `chat-finished`: Atendimento encerrado

`conversational` / `chat-pipeline-stage-changed`: Mudança de etapa no funil

`conversational` / `message-received`: Mensagem recebida

`conversational` / `message-sent`: Mensagem enviada

`conversational` / `message-status`: Status da mensagem

`campaign` / `message-replies`: Resposta de campanha

`campaign` / `message-status`: Status da mensagem de campanha