Guias
Eventos
O registro de eventos do workspace, a ordem garantida pelo seq e como ler os eventos pela API sem perder nenhum.
O que é o registro de eventos
Cada mudança importante do workspace vira um evento: uma mensagem que chega ou sai, uma conversa atribuída ou finalizada, um lead cadastrado, uma oportunidade ganha, uma campanha que começa a enviar, um e-mail entregue. O evento é gravado na mesma transação da mudança. Se a mudança não acontece, o evento também não existe, e o contrário também vale.
Cada workspace tem a própria sequência. O campo seq começa em 1 e só cresce, sem repetir: um evento com seq maior aconteceu depois, na ordem em que as mudanças foram confirmadas no banco. Guarde o seq do último evento que você processou; é com ele que você continua de onde parou.
Os eventos ficam guardados por 7 dias.
Uma conversa nova chega como conversation.created, com o canal e, nas conversas de campanha, a campanha. Um destinatário que entra em lote numa campanha de WhatsApp, ao criar a campanha ou ao trocar o público dela, ainda não é uma conversa: o conversation.created dele chega uma única vez, junto com a primeira mensagem da conversa (normalmente o envio da campanha) e logo antes do evento dessa mensagem. O createdAt continua sendo a hora em que o destinatário entrou na campanha. Um destinatário que nunca recebe mensagem não gera conversation.created.
Cada mudança de situação de um destinatário de campanha chega como campaign.entryStatusUpdated, com a situação nova, a anterior e, quando houver, o motivo, como o código do erro ou o motivo de o destinatário ter sido pulado. Quando uma campanha é reenviada, cada destinatário que volta para pending também gera um evento. É o tipo de maior volume do catálogo.
Formato de um evento
{
"id": "evt_184467",
"type": "message.received",
"seq": 1042,
"createdAt": "2026-11-04T15:00:00Z",
"workspaceId": "6b1f0f8e-4a2c-4f7e-9a51-0c3d2b1e7f90",
"departmentId": "2c9e7b14-5d3a-4e8f-b6a1-7f0e9d2c4b58",
"data": {
"messageId": "3c7e9a42-1d5b-4f8e-b0a6-9e2d4c8f1a57",
"conversationId": "8d3a1f5e-2b9c-4c71-a0e4-6f2d9b7c1e33",
"channel": "whatsapp",
"direction": "inbound",
"messageType": "user_message",
"text": "Olá, quero saber o preço",
"mediaId": null,
"sender": { "kind": "contact", "id": "" },
"createdAt": "2026-11-04T15:00:00Z"
}
}| Campo | O que é |
|---|---|
id | Identificador único do evento. Use para descartar uma entrega repetida. |
type | O tipo do evento, do catálogo abaixo. |
seq | A posição do evento na sequência do workspace. |
createdAt | Quando a mudança aconteceu, em UTC. |
workspaceId | O workspace do evento. |
departmentId | O departamento do recurso no momento do evento, ou null quando o recurso não tem departamento. |
data | Os dados do recurso no momento da mudança. O formato depende do type. |
O data traz o que mudou e os identificadores para buscar o resto pela API, por exemplo conversationId e messageId. Os eventos de lead trazem só identificadores e os nomes dos campos alterados (changedFields), nunca os valores pessoais.
Ler os eventos pela API
GET /v1/events devolve os eventos do workspace do cabeçalho X-Workspace-ID em ordem de seq. Serve a integrações que não mantêm um WebSocket aberto, como uma rotina que roda de tempos em tempos. Exige a permissão events:read; para uma integração, marque Eventos nas permissões dela.
| Parâmetro | O que faz |
|---|---|
since | O seq do último evento que você já processou. Vêm os seguintes. Sem ele, a leitura começa no evento mais antigo guardado. |
cursor | O meta.nextCursor da página anterior. Use since ou cursor, nunca os dois. |
types | Os tipos que interessam, separados por vírgula, por exemplo message.received,lead.created. Até 20 tipos. |
limit | Eventos por página, de 1 a 100. O padrão é 50. |
A resposta segue o formato das listas com cursor:
{
"data": [ { "id": "evt_184467", "type": "message.received", "seq": 1042 } ],
"meta": { "nextCursor": "MjAyNi0xMS0wNFQxNTowMDowMFp8MTA0Mg", "hasMore": true }
}- Com
hasMoreigual atrue, chame de novo com onextCursorlogo em seguida. - Com
hasMoreigual afalse, você chegou ao fim. Guarde onextCursor(ou oseqdo último evento) e volte daqui a alguns segundos. - Uma página sem eventos mantém a posição: o
nextCursordela continua de onde você estava.
A leitura é idempotente: pedir a mesma posição de novo devolve os mesmos eventos. Processe cada evento uma única vez guardando o seq só depois de processá-lo.
Receber os eventos por WebSocket
Quem mantém uma conexão aberta recebe os mesmos eventos assim que são registrados, no WebSocket de conversas com o parâmetro since: primeiro os guardados depois de since, depois os novos, cada um num quadro workspace_event. Uma posição mais antiga que a janela chega como o quadro resync_required com o oldestSeq. Uma integração também abre essa conexão, com um ticket pedido pela chave dela. Veja Tempo real.
Quem vê cada evento
Um evento só aparece para quem pode ler o recurso dele, com as mesmas regras da rota que lê esse recurso: a permissão, os departamentos e, nas conversas, a visibilidade de quem não vê as conversas dos colegas. Uma integração enxerga exatamente o que as permissões e os departamentos dela permitem.
| Recurso do evento | Permissão de leitura | Departamento |
|---|---|---|
| Conversas e mensagens | conversations:read | O da conversa, com as conversas atribuídas a quem lê |
| Leads | leads:read | Não se aplica |
| Oportunidades | conversations:read | O do responsável pela oportunidade |
| Campanhas de WhatsApp | whatsapp_campaigns:read | O da campanha |
| Disparos de WhatsApp (não oficial) | unofficial_whatsapp_campaigns:read | O do disparo |
| Campanhas de e-mail | email_marketing:read | Não se aplica |
| E-mails da API de e-mail transacional | transactional_email:read ou email_marketing:read | Não se aplica |
| Campanhas de RCS e SMS | carrier_messaging:read | Não se aplica |
Por isso a sequência que você recebe pode pular números: os eventos entre eles são de recursos que você não pode ler.
Janela de 7 dias
Os eventos com mais de 7 dias são apagados. Se o since ou o cursor pedir uma posição de onde já faltam eventos, a resposta é 410 com o código resync_required e o seq mais antigo ainda guardado:
{ "error": true, "code": "resync_required", "message": "...", "details": { "oldestSeq": 98211 } }Nesse caso, busque o estado atual dos recursos pela API e recomece a leitura sem since.
Erros
| Status | Código | Quando |
|---|---|---|
400 | events_since_invalid | since não é um número inteiro a partir de 0. |
400 | events_position_conflict | since e cursor vieram juntos. |
400 | event_type_unknown | Um dos types não existe no catálogo. |
400 | event_types_too_many | Mais de 20 tipos em types. |
400 | pagination_invalid | limit fora de 1 a 100. |
400 | cursor_invalid | O cursor não veio desta API. |
403 | read_permission_required | Falta a permissão events:read. |
410 | resync_required | A posição pedida já saiu da janela de 7 dias. |
Catálogo de tipos
Esta tabela é gerada a partir do próprio catálogo de eventos da API, o mesmo que valida o filtro types.
| Tipo | Grupo | Quando chega |
|---|---|---|
message.received | Mensagens | O contato enviou uma mensagem em qualquer canal. |
message.sent | Mensagens | A empresa enviou uma mensagem: pessoa, agente de IA, fluxo, campanha ou integração. |
message.statusUpdated | Mensagens | Uma mensagem enviada mudou de situação: entregue, lida ou com falha. |
conversation.created | Conversas | Uma conversa nova foi aberta. |
conversation.assigned | Conversas | A conversa foi atribuída a um responsável. |
conversation.unassigned | Conversas | A conversa ficou sem responsável. |
conversation.statusChanged | Conversas | A situação da conversa mudou, incluindo finalizar e reabrir. |
conversation.stageChanged | Conversas | A conversa mudou de etapa no funil. |
conversation.departmentChanged | Conversas | A conversa foi encaminhada para outro departamento. |
lead.created | Leads | Um lead foi cadastrado, à mão, por importação, por integração ou ao chegar por um canal. |
lead.updated | Leads | Campos do lead mudaram; data.changedFields lista quais. |
lead.anonymized | Leads | Os dados pessoais do lead foram apagados a pedido do titular. |
lead.deleted | Leads | O lead foi excluído. |
opportunity.created | Oportunidades | Uma oportunidade foi criada. |
opportunity.updated | Oportunidades | Campos da oportunidade mudaram. |
opportunity.stageChanged | Oportunidades | A oportunidade mudou de etapa no funil. |
opportunity.won | Oportunidades | A oportunidade foi ganha. |
opportunity.lost | Oportunidades | A oportunidade foi perdida. |
campaign.started | Campanhas | Uma campanha começou a enviar, em qualquer canal. |
campaign.paused | Campanhas | A campanha foi pausada. |
campaign.resumed | Campanhas | A campanha voltou a enviar depois de uma pausa. |
campaign.stopped | Campanhas | A campanha foi encerrada antes de terminar. |
campaign.completed | Campanhas | A campanha terminou de enviar. |
campaign.entryStatusUpdated | Campanhas | Um destinatário da campanha mudou de situação. Volume alto: só chega a quem pedir este tipo. |
email.sent | E-mails | Um e-mail da API de e-mail transacional foi aceito pelo provedor. |
email.delivered | E-mails | O e-mail chegou ao servidor do destinatário. |
email.deliveryDelayed | E-mails | A entrega do e-mail está atrasada e será tentada de novo. |
email.bounced | E-mails | O e-mail voltou. |
email.complained | E-mails | O destinatário marcou o e-mail como spam. |
email.opened | E-mails | O destinatário abriu o e-mail. |
email.clicked | E-mails | O destinatário clicou em um link do e-mail. |
email.failed | E-mails | O e-mail não pôde ser enviado. |