Eventos de conversa

Esses eventos cobrem o ciclo de vida completo de uma conversa — desde a abertura até o encerramento, passando por atribuições e reabertura. Use-os para manter seu CRM sincronizado, acionar SLAs ou gerar relatórios de atendimento.

Lista de eventos

Evento	Quando dispara
`conversation.created`	Uma nova conversa é iniciada por um contato ou criada manualmente
`conversation.assigned`	A conversa é atribuída a um atendente ou agente de IA
`conversation.closed`	A conversa é marcada como encerrada
`conversation.reopened`	Uma conversa encerrada volta ao status aberto

`conversation.created`

Quando dispara

Uma nova conversa começa — seja porque um contato enviou a primeira mensagem, seja porque um atendente ou automação criou a conversa manualmente via API.

Payload

{
  "event": "conversation.created",
  "event_id": "evt_01HX3B2K8MFQR4YZDNV7P9WCE",
  "timestamp": "2026-04-19T14:30:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "conversation_id": "conv_01HX3B2K",
    "contact_id": "cont_456",
    "channel_id": "chan_789",
    "channel_type": "whatsapp",
    "status": "open",
    "assigned_to": null,
    "assigned_type": null,
    "tags": [],
    "created_at": "2026-04-19T14:30:00Z"
  }
}

Campos principais

Campo	Tipo	Descrição
`conversation_id`	string	ID único da conversa
`contact_id`	string	ID do contato que iniciou
`channel_id`	string	ID do canal por onde a conversa chegou
`channel_type`	enum	`whatsapp`, `instagram`, `widget`, `telegram`, `slack`
`status`	enum	`open`, `closed`
`assigned_to`	string \| null	ID do atendente ou agente atribuído
`assigned_type`	enum \| null	`agent` (IA) ou `attendant` (humano)
`tags`	array	Tags aplicadas na conversa

Exemplo de uso

Use conversation.created para registrar novas conversas no seu CRM ou disparar uma notificação para o time de vendas quando um lead novo entrar.

`conversation.assigned`

Quando dispara

A conversa é atribuída (ou reatribuída) a um atendente humano ou a um agente de IA. Isso inclui atribuições automáticas via regras de roteamento e atribuições manuais pelo inbox.

Payload

{
  "event": "conversation.assigned",
  "event_id": "evt_01HX3C5N2PGTS6YADOV8Q1XDF",
  "timestamp": "2026-04-19T14:31:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "conversation_id": "conv_01HX3B2K",
    "contact_id": "cont_456",
    "channel_id": "chan_789",
    "channel_type": "whatsapp",
    "assigned_to": "usr_321",
    "assigned_type": "attendant",
    "previous_assigned_to": null,
    "previous_assigned_type": null,
    "assigned_at": "2026-04-19T14:31:00Z"
  }
}

Campos principais

Campo	Tipo	Descrição
`assigned_to`	string	ID do atendente ou agente que recebeu
`assigned_type`	enum	`agent` \| `attendant`
`previous_assigned_to`	string \| null	Quem estava responsável antes, se houver
`previous_assigned_type`	enum \| null	Tipo do responsável anterior
`assigned_at`	string	Timestamp ISO 8601 da atribuição

Exemplo de uso

Use para calcular tempo médio de primeira resposta (FRT) — registre o assigned_at e compare com o timestamp da primeira mensagem do atendente.

`conversation.closed`

Quando dispara

A conversa é marcada como encerrada, seja pelo atendente manualmente, por uma automação de tempo limite de inatividade ou via API.

Payload

{
  "event": "conversation.closed",
  "event_id": "evt_01HX3D7P4RHTW7ZBEPV9S2YEG",
  "timestamp": "2026-04-19T16:45:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "conversation_id": "conv_01HX3B2K",
    "contact_id": "cont_456",
    "channel_id": "chan_789",
    "channel_type": "whatsapp",
    "closed_by": "usr_321",
    "closed_by_type": "attendant",
    "resolution": "resolved",
    "duration_seconds": 8700,
    "message_count": 24,
    "closed_at": "2026-04-19T16:45:00Z"
  }
}

Campos principais

Campo	Tipo	Descrição
`closed_by`	string	ID de quem encerrou
`closed_by_type`	enum	`attendant`, `agent`, `automation`, `api`
`resolution`	enum	`resolved`, `unresolved`, `spam`
`duration_seconds`	integer	Duração total da conversa em segundos
`message_count`	integer	Total de mensagens trocadas
`closed_at`	string	Timestamp ISO 8601 do encerramento

Exemplo de uso

Use conversation.closed com duration_seconds e resolution para alimentar dashboards de qualidade de atendimento e calcular CSAT automaticamente.

`conversation.reopened`

Quando dispara

Uma conversa que estava fechada volta ao status open. Isso acontece quando um contato envia nova mensagem numa conversa encerrada ou quando um atendente reabre manualmente.

Payload

{
  "event": "conversation.reopened",
  "event_id": "evt_01HX3E9Q5SJUW8ZCFQWA3ZFH",
  "timestamp": "2026-04-20T09:10:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "conversation_id": "conv_01HX3B2K",
    "contact_id": "cont_456",
    "channel_id": "chan_789",
    "channel_type": "whatsapp",
    "reopened_by": null,
    "reopened_reason": "new_message",
    "reopened_at": "2026-04-20T09:10:00Z"
  }
}

Campos principais

Campo	Tipo	Descrição
`reopened_by`	string \| null	ID de quem reopenou (null se foi por nova mensagem)
`reopened_reason`	enum	`new_message`, `manual`, `api`
`reopened_at`	string	Timestamp ISO 8601 da reabertura

Exemplo de uso

Monitore conversation.reopened com reopened_reason: "new_message" para identificar padrões de contatos que retornam — pode indicar resolução insatisfatória na primeira vez.

Sempre use o event_id para garantir idempotência. Em caso de retentativa, o mesmo evento pode ser entregue mais de uma vez com o mesmo event_id.

​Lista de eventos

​conversation.created

​Quando dispara

​Payload

​Campos principais

​Exemplo de uso

​conversation.assigned

​Quando dispara

​Payload

​Campos principais

​Exemplo de uso

​conversation.closed

​Quando dispara

​Payload

​Campos principais

​Exemplo de uso

​conversation.reopened

​Quando dispara

​Payload

​Campos principais

​Exemplo de uso

Lista de eventos

`conversation.created`

Quando dispara

Payload

Campos principais

Exemplo de uso

`conversation.assigned`

Quando dispara

Payload

Campos principais

Exemplo de uso

`conversation.closed`

Quando dispara

Payload

Campos principais

Exemplo de uso

`conversation.reopened`

Quando dispara

Payload

Campos principais

Exemplo de uso