Skip to main content

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_atendimento se tinha responsável, ou para aguardando se 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 para em_atendimento.
  • Resolver é um clique no inbox ou POST /v1/conversas/{id}/atendimento com {"status": "resolvida"}.
A mensagem de um fluxo ou de um agente pela API não move o atendimento — ver abaixo.

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}/ia e {"pausada": true, "motivo": "pediu atendente"} — é como a IA chama um humano;
  • alguém da equipe, pelo inbox.
Retoma:
  • 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}/ia e {"pausada": false} — só quando quem pausou foi o próprio agente (por: "api"). Pausa de pessoa (humano:… ou celular) devolve 409: quem assumiu a conversa é quem a devolve.
Resolver pela API (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.
Existe "forcar": true no corpo, que envia mesmo com a IA pausada e fica registrado na trilha de auditoria. Ele serve para um caso desenhado de propósito — por exemplo, a última mensagem do agente avisando que vai chamar alguém, quando você pausou antes de enviar. Não o use como resposta automática ao 409: isso é o agente falando por cima do humano.

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 aguardando continua aguardando depois 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.
É o mesmo tratamento das mensagens de fluxo. Robô falando não é alguém assumindo: se a IA responde e a conversa saísse da fila, ninguém mais olharia para ela.

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:
Quando o envio falha, o campo error diz o motivo. Quando dá certo, o webhook message.sent chega com source = api.

Idempotência

O POST …/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 422 e não envia nada.
  • A mesma chave, na mesma conversa, responde 200 com a mensagem original e "duplicate": true. Nada é enviado de novo.
  • A chave vale para sempre dentro da empresa.
Nunca use uma chave fixa, o id do lead ou o id da conversa como Idempotency-Key. A segunda mensagem da conversa voltaria duplicate: true e não seria enviada, sem erro nenhum. A chave identifica uma tentativa de envio: num agente que reage a webhook, use resposta:<metricaas_message_id> da mensagem que disparou a resposta. O X-Metricaas-Delivery não serve: quando o WhatsApp reentrega o mesmo evento, nós geramos uma entrega nova, com outro id — e a mesma mensagem.

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):
Mensagem que o lead não pediu, em volume, é o que faz o WhatsApp banir o número. Por isso as travas são as mesmas da primeira mensagem dos fluxos, na mesma fila: 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 em media_url. Uma URL de fora responde 422. Essa URL abre o arquivo só por 10 minutos, mas segue aceita em media_url depois disso.