Conversa e lead são coisas diferentes
O lead é o registro do CRM: de onde a pessoa veio, em que etapa do funil está, quanto comprou. A conversa é a troca de mensagens com ela num canal — WhatsApp ou Instagram —, com o estado do atendimento. Toda conversa aponta para o seu lead (lead_id). As rotas e os webhooks de mensagem
falam em conversa (conversation_id): é nela que se responde, se pausa a IA e se
resolve o atendimento. As de funil e venda falam em lead.
A mesma pessoa no WhatsApp e no Instagram hoje são dois leads, cada um com a sua
conversa. Um agente que responde nos dois canais não deve supor que conhece a pessoa
do outro canal.
Estados de atendimento
O atendimento diz se alguém está falando com a pessoa agora. Não tem relação com a etapa do funil: um lead em “Proposta” pode ter o atendimento resolvido, e um lead “Ganho” pode voltar a conversar.
Como a conversa anda entre eles:
- O lead escreve numa conversa resolvida → ela reabre: volta para
em_atendimentose tinha responsável, ou paraaguardandose não tinha. Cliente que volta nunca some da fila. - Alguém da equipe responde (pelo inbox ou pelo celular) numa conversa
aguardando→ ela passa paraem_atendimento. - Resolver é um clique no inbox ou
POST /v1/conversas/{id}/atendimentocom{"status": "resolvida"}.
O interruptor da IA
Cada conversa tem um interruptor: a IA pode ou não pode responder ali. Ele existe para o humano assumir sem precisar combinar nada com o fluxo do agente — a pausa é do Metricaas, não do seu n8n. Pausa sozinho quando um humano responde, pelo inbox ou pelo celular. A mensagem de um fluxo e a do próprio agente pela API não pausam. Pausa também quando alguém pede:- o agente, com
POST /v1/conversas/{id}/iae{"pausada": true, "motivo": "pediu atendente"}— é como a IA chama um humano; - alguém da equipe, pelo inbox.
- quando alguém da equipe resolve a conversa pelo inbox — resolver devolve a conversa à IA. Se o lead escrever de novo depois, o agente responde;
- pelo inbox, no bloco Agente de IA da conversa;
- com
POST /v1/conversas/{id}/iae{"pausada": false}— só quando quem pausou foi o próprio agente (por: "api"). Pausa de pessoa (humano:…oucelular) devolve409: quem assumiu a conversa é quem a devolve.
POST /v1/conversas/{id}/atendimento) não derruba a pausa de
uma pessoa: a conversa fica resolvida e a IA continua pausada. Assim nem um agente
confuso nem um token vazado tiram a conversa da mão de quem a assumiu.
Pausar o que já está pausado não muda nada — nem a hora, nem quem pausou: a primeira
pessoa que assumiu continua sendo a resposta para “quem tirou a IA daqui?”. A rota
responde {"pausada": true, "mudou": false}.
O estado aparece em três lugares:
O que acontece quando o agente tenta responder numa conversa pausada
POST /v1/conversas/{id}/mensagens responde 409, e o detail diz quem pausou e
quando. Nada é enviado.
Esse 409 é o caso normal de uma corrida: o lead escreveu, o agente começou a pensar,
e nesse meio-tempo alguém da equipe respondeu. Descarte a resposta do agente — o
humano já está na conversa.
A fala da IA e a fila
A mensagem enviada pela API:- aparece no inbox com um selo próprio, para a equipe saber que não foi ninguém dela;
- não assume a conversa — o responsável continua o mesmo;
- não tira a conversa da fila — uma conversa
aguardandocontinuaaguardandodepois que a IA responde; - não conta como primeira resposta do time. O tempo de resposta da IA é medido à parte, para o relatório de atendimento não misturar os dois.
Quem escreveu: source
Toda mensagem tem uma origem, e ela é a mesma nos webhooks e em
GET /v1/conversas/{id}/mensagens:
Um agente que assina
message.sent recebe de volta as próprias mensagens, com
source = api. Filtre por source antes de reagir a qualquer coisa.
Enviar é assíncrono
POST /v1/conversas/{id}/mensagens responde 202 com status: "pending": a
mensagem entrou na fila de envio, não saiu ainda. Depois ela passa a sent,
delivered e read — ou failed.
Para saber o que aconteceu, sem esperar o webhook:
error diz o motivo. Quando dá certo, o webhook
message.sent chega com source = api.
Idempotência
OPOST …/mensagens exige o cabeçalho Idempotency-Key (1 a 200 caracteres) —
sem ele, 400. É a única defesa contra mandar a mesma mensagem duas vezes ao lead: o
WhatsApp não deduplica.
- A mesma chave já usada em outra conversa responde
422e não envia nada. - A mesma chave, na mesma conversa, responde
200com a mensagem original e"duplicate": true. Nada é enviado de novo. - A chave vale para sempre dentro da empresa.
Limites
O dia é o de Brasília: o contador da empresa zera à meia-noite de São Paulo. A
repetição idempotente (
duplicate: true) não conta. O upload de arquivo para enviar
(POST /v1/midia) conta no limite por minuto.
O limite diário existe para limitar o estrago de um token vazado ou de um fluxo em
laço — um agente saudável numa empresa normal não chega perto dele.
Começar a conversa: POST /v1/conversas
Para falar primeiro com quem pediu contato (a recuperação de quem deixou o
telefone num formulário e não comprou):
Se o lead já escreveu nesta conversa, a mensagem sai como a de
POST /v1/conversas/{id}/mensagens, com a mesma recusa da IA pausada (409, e o
forcar). Conversa ligada a outro lead com o mesmo número: 409.
O token precisa de inbox:operate e crm:operate: o de finalidade Agente de
atendimento responde quem escreveu, mas não abre conversa nova (403).
O Idempotency-Key é obrigatório e os limites são os da tabela acima (30 por minuto
por token, 1.000 por dia por empresa). A conversa nasce resolvida e sem dono:
quando o lead responder, ela volta para a fila do time como qualquer outra.
O que a API não faz
- Template e janela de 24 horas da API oficial do WhatsApp — inclusive para começar conversa (ver acima).
- Mandar mídia de uma URL qualquer. O arquivo precisa ser enviado antes por
POST /v1/midia, que devolve a URL a usar emmedia_url. Uma URL de fora responde422. Essa URL abre o arquivo só por 10 minutos, mas segue aceita emmedia_urldepois disso.