Como uma conversa é identificada em cada canal, por onde as mensagens saem, quem responde por ela e como notas, agendamentos e etiquetas se ligam a ela.
Uma conversa é o atendimento de um contato num canal: um chat no WhatsApp, uma DM no Instagram, uma troca de e-mails, uma conversa no chat do site. O contato por trás dela é o lead, a pessoa ou empresa cliente, que liga as conversas que ela tem em todos os canais. Um mesmo lead pode ter várias conversas, em canais diferentes ou em contas diferentes do mesmo canal.
Identidade da conversa
Toda conversa é identificada por dois valores juntos:
| Valor | O que é |
|---|---|
entryType | O canal da conversa, um dos valores da tabela abaixo. |
entryId | O identificador da conversa dentro do canal. Não é o id do lead. |
O par sempre anda junto: o mesmo entryId não identifica uma conversa sem o entryType. Ele aparece com nomes diferentes conforme o lugar:
| Onde | Forma |
|---|---|
| Caminho das rotas HTTP | /conversations/{entryType}/{entryId}/..., como GET /conversations/whatsapp/{entryId}/notes |
| Corpo das rotas HTTP | entryType e entryId |
| Mensagens do WebSocket | entry_type e entry_id |
Os canais
entryType | Canal |
|---|---|
whatsapp | WhatsApp oficial (API da Meta) |
unofficial_whatsapp | WhatsApp por QR Code |
instagram | Instagram Direct |
facebook | Messenger da página do Facebook |
telegram | Telegram |
webchat | Chat do site |
mercadolivre | Mercado Livre |
tiktok | TikTok |
email | |
rcs | RCS |
sms | SMS |
Os onze valores valem no WebSocket de conversas, nas etiquetas e nas etapas. Algumas rotas são de um canal só e trazem o canal no próprio caminho, como POST /conversations/whatsapp/{entryId}/forms ou GET /unofficial-whatsapp/conversations/{entryId}/group; a descrição de cada rota na referência diz os canais que ela aceita.
Enviar mensagens
Numa conversa que já existe, as mensagens saem só pelo WebSocket /ws/conversations. Não há rota HTTP para enviar texto, mídia ou botões numa conversa.
- Abra a conexão, como em Tempo real.
- Para anexar um arquivo, envie-o antes por
POST /conversations/{entryType}/{entryId}/media(multipart). A resposta traz o id da mídia. - Envie o evento
send:
{
"type": "send",
"payload": {
"entry_id": "ID_DA_CONVERSA",
"entry_type": "whatsapp",
"text": "Olá! Seu pedido saiu para entrega.",
"request_id": "6b0f2c1e-8d4a-4f7b-9e3c-2a1d0b9c8e7f"
}
}Informe text ou media_id (com media_type image, video, audio, document ou sticker). O request_id, um UUID por envio, torna o envio idempotente: repetir o mesmo request_id na mesma conversa nunca envia de novo. O resultado chega em conversation:message_sent, com a mensagem gravada, ou em conversation:message_error, com code.
Os outros eventos que agem sobre mensagens também são do WebSocket:
| Evento | Para quê |
|---|---|
send_button | Enviar uma mensagem com botões de resposta. |
resend_message | Reenviar uma mensagem que falhou. |
react_message, edit_message, delete_message | Reagir, editar e apagar, nos canais que permitem. conversation:subscribed traz o que o canal da conversa permite em message_capabilities. |
reopen_window | Enviar um modelo do WhatsApp oficial para reabrir a janela de atendimento. |
mark_read | Marcar mensagens do contato como lidas. |
Os formatos completos de cada evento, as respostas e os códigos de erro estão no grupo WebSockets da referência.
O que o HTTP faz
As rotas HTTP cobrem o que acontece fora de uma conversa aberta no socket:
| Rota | O que faz |
|---|---|
POST /whatsapp/outreach/conversations | Inicia uma conversa no WhatsApp oficial enviando um modelo aprovado. |
POST /unofficial-whatsapp/instances/{id}/conversations | Abre, ou reaproveita, a conversa de um número no WhatsApp por QR Code. |
POST /email/outreach/conversations | Envia um e-mail individual e abre, ou reaproveita, a conversa de e-mail do contato. |
POST /conversations/{entryType}/{entryId}/scheduled-messages | Agenda uma mensagem para um horário futuro. |
POST /conversations/whatsapp/{entryId}/forms | Envia um formulário do WhatsApp na conversa, com a janela de 24 horas aberta. |
Ao iniciar uma conversa por essas rotas, ela fica com quem a iniciou, para que o agente ou o fluxo da conta não responda ao contato enquanto essa pessoa for a responsável.
Mensagens interativas
O atendente envia botões de resposta com send_button: um texto em body_text, de 1 a 3 botões em buttons (cada um com id e title) e, se quiser, header_type, header_text e footer_text.
Toda mensagem enviada com opções, por qualquer remetente (atendente, agente de IA, fluxo, campanha ou modelo do WhatsApp oficial), chega no histórico com o campo interactive, que traz o que o contato recebeu depois dos limites do canal:
interactive.kind | Mensagem |
|---|---|
buttons | Botões de resposta. |
list | Lista de opções em seções, aberta pelo rótulo de button_label. |
cta_url | Botão que abre um endereço. |
template | Modelo do WhatsApp oficial, com o nome em template_name. |
Cada botão tem um kind: reply, url, phone, copy_code ou flow. Quando o contato escolhe uma opção, a mensagem dele traz interactive_reply, com kind (button, list, template_button, option, quick_reply ou postback), option_id e title, e replyToMessageId aponta para a mensagem com as opções quando o canal informa.
Quem responde pela conversa
Cada conversa tem um responsável, em assigned_user_id. Ele pode ser:
| Valor | Quem é |
|---|---|
| O id de um usuário | Uma pessoa da equipe. |
ai:<id do agente> | Um agente de IA. |
workflow:<id do fluxo> | Um fluxo. |
| Vazio | Ninguém: a conversa está na fila da equipe. |
Quando a conta, o número ou a campanha da conversa tem um agente ou um fluxo ativo, ele passa a ser o responsável e responde ao contato. Enquanto um agente ou fluxo é o responsável, as mensagens novas do contato não tocam aviso para ninguém da equipe (alert de conversation:entry_update). Na busca da caixa de entrada, responsible_kind igual a ai ou workflow lista as conversas com um agente ou um fluxo.
Atribuir, delegar e pausar
| Ação | Como |
|---|---|
| Passar para uma pessoa | Evento assign_to do WebSocket, com user_id. A pessoa recebe conversation:assigned_to_you. |
| Delegar a um agente ou fluxo | PUT /conversations/{entryType}/{entryId}/delegation. O escolhido passa a responder só esta conversa e vira o responsável, mesmo que o canal não tenha automação ativa. A delegação termina quando a conversa é finalizada. |
| Pausar ou religar a automação | PATCH /conversations/{entryType}/{entryId}/automation. Desligar devolve à fila da equipe uma conversa que o agente ou o fluxo detinha; ligar devolve ao agente ou fluxo da conversa; null volta a herdar a configuração da conta ou da campanha. Sem agente ou fluxo para assumir, a resposta é 409 nothing_to_return_to. |
| Saber qual fluxo responde | GET /conversations/{entryType}/{entryId}/responsible-workflow. |
Passagem para a equipe
Um agente ou um fluxo passa a conversa para a equipe (o hand-off) de duas formas: para uma pessoa escolhida, ou para a distribuição do departamento. Na distribuição, a conversa vai primeiro para quem tem o cliente na carteira; sem carteira, para a próxima pessoa da roleta do departamento; sem ninguém para receber, fica na fila da equipe, sem responsável. Em todos os casos a automação sai da conversa e a nova responsável é avisada por conversation:assigned_to_you.
Status da conversa
O status vai em conversation_status: new, ongoing ou finished. O atendente muda para ongoing ou finished com o evento set_conversation_status; uma conversa volta a new, ou reabre depois de finalizada, só quando o contato manda uma mensagem nova. Se o workspace exige um desfecho, envie outcome_code ao finalizar.
Notas, agendamentos, etiquetas e etapas
Esses recursos se ligam à conversa pelo mesmo par entryType e entryId:
| Recurso | Como se liga | Rotas |
|---|---|---|
| Notas internas | Comentários da equipe na conversa, com menções e imagens. Nunca vão para o contato, a IA, a análise, os fluxos, as exportações ou o chat do site. Os inscritos na conversa recebem conversation:note e conversation:note_deleted. | GET e POST /conversations/{entryType}/{entryId}/notes, DELETE /conversation-notes/{id} |
| Mensagens agendadas | Mensagens programadas por uma pessoa, um agente ou um fluxo. Texto e mídia precisam cair na janela de atendimento aberta; no WhatsApp oficial, um modelo pode ser agendado com a janela fechada, até 30 dias à frente. Quando sai, a mensagem aparece no histórico como qualquer outra. | GET e POST /conversations/{entryType}/{entryId}/scheduled-messages, GET /scheduled-messages, PATCH e DELETE /scheduled-messages/{id} |
| Etiquetas | Marcas coloridas do workspace associadas à conversa. A mudança chega em conversation:label_update. | GET /labels/entries/{entryType}/{entryId}, POST e DELETE /labels/entries |
| Etapas | A posição da conversa num funil de conversas. A mudança chega em conversation:stage_update. | GET /stages/entries/{entryType}/{entryId}, POST e DELETE /stages/entries |
Etiquetas, etapas, responsável, status e origem também servem para escolher conversas no quadro do CRM, com o filtro estruturado.
Veja também
- Tempo real: como abrir e manter as conexões WebSocket.
- Na Referência da API: WebSockets, Conversas, Notas internas, Mensagens agendadas, Etiquetas, Etapas e CRM.