Docs
Páginas desta seção

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

json
{
  "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"
  }
}
CampoO que é
idIdentificador único do evento. Use para descartar uma entrega repetida.
typeO tipo do evento, do catálogo abaixo.
seqA posição do evento na sequência do workspace.
createdAtQuando a mudança aconteceu, em UTC.
workspaceIdO workspace do evento.
departmentIdO departamento do recurso no momento do evento, ou null quando o recurso não tem departamento.
dataOs 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âmetroO que faz
sinceO seq do último evento que você já processou. Vêm os seguintes. Sem ele, a leitura começa no evento mais antigo guardado.
cursorO meta.nextCursor da página anterior. Use since ou cursor, nunca os dois.
typesOs tipos que interessam, separados por vírgula, por exemplo message.received,lead.created. Até 20 tipos.
limitEventos por página, de 1 a 100. O padrão é 50.

A resposta segue o formato das listas com cursor:

json
{
  "data": [ { "id": "evt_184467", "type": "message.received", "seq": 1042 } ],
  "meta": { "nextCursor": "MjAyNi0xMS0wNFQxNTowMDowMFp8MTA0Mg", "hasMore": true }
}
  • Com hasMore igual a true, chame de novo com o nextCursor logo em seguida.
  • Com hasMore igual a false, você chegou ao fim. Guarde o nextCursor (ou o seq do último evento) e volte daqui a alguns segundos.
  • Uma página sem eventos mantém a posição: o nextCursor dela 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 eventoPermissão de leituraDepartamento
Conversas e mensagensconversations:readO da conversa, com as conversas atribuídas a quem lê
Leadsleads:readNão se aplica
Oportunidadesconversations:readO do responsável pela oportunidade
Campanhas de WhatsAppwhatsapp_campaigns:readO da campanha
Disparos de WhatsApp (não oficial)unofficial_whatsapp_campaigns:readO do disparo
Campanhas de e-mailemail_marketing:readNão se aplica
E-mails da API de e-mail transacionaltransactional_email:read ou email_marketing:readNão se aplica
Campanhas de RCS e SMScarrier_messaging:readNã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:

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

StatusCódigoQuando
400events_since_invalidsince não é um número inteiro a partir de 0.
400events_position_conflictsince e cursor vieram juntos.
400event_type_unknownUm dos types não existe no catálogo.
400event_types_too_manyMais de 20 tipos em types.
400pagination_invalidlimit fora de 1 a 100.
400cursor_invalidO cursor não veio desta API.
403read_permission_requiredFalta a permissão events:read.
410resync_requiredA 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.

TipoGrupoQuando chega
message.receivedMensagensO contato enviou uma mensagem em qualquer canal.
message.sentMensagensA empresa enviou uma mensagem: pessoa, agente de IA, fluxo, campanha ou integração.
message.statusUpdatedMensagensUma mensagem enviada mudou de situação: entregue, lida ou com falha.
conversation.createdConversasUma conversa nova foi aberta.
conversation.assignedConversasA conversa foi atribuída a um responsável.
conversation.unassignedConversasA conversa ficou sem responsável.
conversation.statusChangedConversasA situação da conversa mudou, incluindo finalizar e reabrir.
conversation.stageChangedConversasA conversa mudou de etapa no funil.
conversation.departmentChangedConversasA conversa foi encaminhada para outro departamento.
lead.createdLeadsUm lead foi cadastrado, à mão, por importação, por integração ou ao chegar por um canal.
lead.updatedLeadsCampos do lead mudaram; data.changedFields lista quais.
lead.anonymizedLeadsOs dados pessoais do lead foram apagados a pedido do titular.
lead.deletedLeadsO lead foi excluído.
opportunity.createdOportunidadesUma oportunidade foi criada.
opportunity.updatedOportunidadesCampos da oportunidade mudaram.
opportunity.stageChangedOportunidadesA oportunidade mudou de etapa no funil.
opportunity.wonOportunidadesA oportunidade foi ganha.
opportunity.lostOportunidadesA oportunidade foi perdida.
campaign.startedCampanhasUma campanha começou a enviar, em qualquer canal.
campaign.pausedCampanhasA campanha foi pausada.
campaign.resumedCampanhasA campanha voltou a enviar depois de uma pausa.
campaign.stoppedCampanhasA campanha foi encerrada antes de terminar.
campaign.completedCampanhasA campanha terminou de enviar.
campaign.entryStatusUpdatedCampanhasUm destinatário da campanha mudou de situação. Volume alto: só chega a quem pedir este tipo.
email.sentE-mailsUm e-mail da API de e-mail transacional foi aceito pelo provedor.
email.deliveredE-mailsO e-mail chegou ao servidor do destinatário.
email.deliveryDelayedE-mailsA entrega do e-mail está atrasada e será tentada de novo.
email.bouncedE-mailsO e-mail voltou.
email.complainedE-mailsO destinatário marcou o e-mail como spam.
email.openedE-mailsO destinatário abriu o e-mail.
email.clickedE-mailsO destinatário clicou em um link do e-mail.
email.failedE-mailsO e-mail não pôde ser enviado.