Guia de conversas e canais

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:

ValorO que é
entryTypeO canal da conversa, um dos valores da tabela abaixo.
entryIdO 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:

OndeForma
Caminho das rotas HTTP/conversations/{entryType}/{entryId}/..., como GET /conversations/whatsapp/{entryId}/notes
Corpo das rotas HTTPentryType e entryId
Mensagens do WebSocketentry_type e entry_id

Os canais

entryTypeCanal
whatsappWhatsApp oficial (API da Meta)
unofficial_whatsappWhatsApp por QR Code
instagramInstagram Direct
facebookMessenger da página do Facebook
telegramTelegram
webchatChat do site
mercadolivreMercado Livre
tiktokTikTok
emailE-mail
rcsRCS
smsSMS

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.

  1. Abra a conexão, como em Tempo real.
  2. Para anexar um arquivo, envie-o antes por POST /conversations/{entryType}/{entryId}/media (multipart). A resposta traz o id da mídia.
  3. 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:

EventoPara quê
send_buttonEnviar uma mensagem com botões de resposta.
resend_messageReenviar uma mensagem que falhou.
react_message, edit_message, delete_messageReagir, editar e apagar, nos canais que permitem. conversation:subscribed traz o que o canal da conversa permite em message_capabilities.
reopen_windowEnviar um modelo do WhatsApp oficial para reabrir a janela de atendimento.
mark_readMarcar 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:

RotaO que faz
POST /whatsapp/outreach/conversationsInicia uma conversa no WhatsApp oficial enviando um modelo aprovado.
POST /unofficial-whatsapp/instances/{id}/conversationsAbre, ou reaproveita, a conversa de um número no WhatsApp por QR Code.
POST /email/outreach/conversationsEnvia um e-mail individual e abre, ou reaproveita, a conversa de e-mail do contato.
POST /conversations/{entryType}/{entryId}/scheduled-messagesAgenda uma mensagem para um horário futuro.
POST /conversations/whatsapp/{entryId}/formsEnvia 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.kindMensagem
buttonsBotões de resposta.
listLista de opções em seções, aberta pelo rótulo de button_label.
cta_urlBotão que abre um endereço.
templateModelo 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:

ValorQuem é
O id de um usuárioUma pessoa da equipe.
ai:<id do agente>Um agente de IA.
workflow:<id do fluxo>Um fluxo.
VazioNingué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çãoComo
Passar para uma pessoaEvento assign_to do WebSocket, com user_id. A pessoa recebe conversation:assigned_to_you.
Delegar a um agente ou fluxoPUT /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çãoPATCH /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 respondeGET /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:

RecursoComo se ligaRotas
Notas internasComentá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 agendadasMensagens 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}
EtiquetasMarcas coloridas do workspace associadas à conversa. A mudança chega em conversation:label_update.GET /labels/entries/{entryType}/{entryId}, POST e DELETE /labels/entries
EtapasA 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