/leads/{numero}, em que {numero} é o número do WhatsApp
do lead, só dígitos, com DDI (ver Identificar o lead). Se o
lead não existe no projeto da chave, toda rota daqui responde 404
Lead with number … not found, menos o PUT /leads/{numero}, que cria o lead.
Ligar ou desligar a IA e encerrar o atendimento ficam em Controle da IA.
Notificar o responsável fica em Notificar responsável.
Como obter uma lista de leads?
Não existe endpoint para listar ou buscar leads. A API age sobre um lead que você já conhece. Para trabalhar com vários leads:- Exportação: Contatos → Exportar gera um CSV com nome, telefone, coluna e tags de
todos os contatos. Filtre a planilha e use a coluna
telefone. Ver Contatos. - Do seu sistema: os números ou ids que o seu CRM, ERP ou planilha já tem.
- Dos webhooks: guarde
lead.idelead.wa_idde cada evento recebido. Ver Webhooks de saída.
GET /leads/{numero}
Devolve os dados do lead.
Campos sem valor não aparecem no JSON. Trate ausência como vazio.
PUT /leads/{numero}
Cria o lead se o número ainda não existe no projeto; se existe, atualiza. Numa chamada
só: nome, várias propriedades e tags. Serve para trazer contatos de outro sistema (um
CRM, um formulário) sem enviar mensagem.
A busca do lead existente aceita o número com ou sem o 9º dígito (ver
Identificar o lead). O lead criado guarda o número
exatamente como veio na URL.
O lead nasce sem conversa: não aparece no funil até a primeira conversa, e
Primeira mensagem do lead roda quando o cliente escrever pela primeira vez. Para
falar primeiro com o lead, envie um template.
Campo fora desses três dá 400. Corpo vazio (
{}) cria o lead só com o número, ou não
faz nada se ele já existe. O número segue as mesmas regras das outras rotas: só
dígitos, com DDI, de 10 a 15 dígitos.
Valor de cada tipo de propriedade
O tipo de cada propriedade vem no campoproperty_type de GET /properties
(Catálogos).
null e "" apagam o valor em qualquer tipo, sem passar por essa validação.
Apagar uma propriedade que o lead não tem não dá erro.
Resposta: 200 ou 201
201 quando criou, 200 quando atualizou. O corpo diz o que mudou:Erros
Tudo é validado antes de gravar: um erro de propriedade ou de tag não deixa o lead
criado pela metade. Se uma falha acontecer depois de o lead ser gravado, a resposta de
erro traz
result com o que já foi aplicado, e repetir o PUT é seguro.
Falha no meio: { error, result }
Um 500 ao gravar ou apagar propriedades, ou um 502 nas tags, pode acontecer
depois de o lead ter sido criado ou alterado. O campo result vem no mesmo
formato da resposta de sucesso:
PUT. Ele cai no caminho de atualização (200) e
aplica só o que faltou; o que já está igual volta em unchanged.
O que o PUT dispara
Lead criado assim dispara o webhook LEAD_CREATED e os fluxos Novo lead criado.
O webhook e o fluxo saem em segundo plano: a resposta não espera a entrega. Num
PUT que cria o lead com tags, os eventos de tag saem antes do LEAD_CREATED.
GET /leads/{numero}/threads
Lista as conversas (threads) do lead, da mais nova para a mais antiga.
closed_at: null é a conversa aberta. Use o thread_id em
GET /messages/history.
PATCH /leads/{numero}/notes
Escreve na anotação do lead.
{ "message": "Update note successfully" }
Não dá para apagar a anotação pela API (note vazio é 400). Para zerar, substitua por um
texto curto ou limpe no painel.
PATCH /leads/{numero}/properties
Preenche uma propriedade do lead.
{ "message": "Update property successfully" }
Para mudar várias propriedades numa chamada só, ou apagar um valor, use o
PUT /leads/{numero} (acima).
POST e DELETE /leads/{numero}/tag
Põe (POST) ou tira (DELETE) uma tag. O corpo é o mesmo nos dois.
O 409 quer dizer “já está como você queria”. Trate como sucesso numa sincronização.
PATCH /leads/{numero}/kanban
Move o lead para uma coluna do funil.
PATCH /leads/{numero}/assignee
Põe o lead num departamento e escolhe o responsável, ou deixa o rodízio escolher.
Sem
user_email e sem user_id, o rodízio do departamento escolhe: recebe quem
está há mais tempo sem receber, entre os membros com Receber Leads ligado. Quem já é o
responsável fica fora do sorteio.
changed: false quer dizer que o lead já estava com esse responsável nesse
departamento: nada foi gravado e ninguém perdeu a vez no rodízio.
O que cada mudança dispara
O gatilho Propriedade alterada está indisponível hoje (em breve), também pela API:
preencher uma propriedade não roda fluxo nenhum. Mover e pôr tag já rodam os fluxos
sozinhos: não chame
/flows/trigger de novo para o
mesmo evento, ou o fluxo roda duas vezes. Para agendar automações, chame
/automations/trigger (só na conexão oficial).
Armadilhas
PUTcomtags.mode: "replace"tira as tags que não vieram. Para só acrescentar, use o padrão"add".- No
PUT,nulle""apagam. Uma integração que manda campo vazio “por padrão” apaga a propriedade. Tire do corpo o que não quer mudar. - Lead criado pelo
PUTnão tem conversa. Texto e mídia pela API exigem a janela de 24h aberta na conexão oficial: comece com um template. - Tag e coluna vão pelo id; propriedade vai pelo slug. Nome não funciona em nenhum dos três. Pegue os ids em Catálogos.
- Mover para coluna com “Desativar IA” desliga a IA do lead. Diga isso a quem pediu.
- Mover pela API não dispara automações. Se precisar, chame
POST /automations/triggerdepois (só na conexão oficial). - Propriedade pela API não roda fluxos. O gatilho Propriedade alterada está em breve. Mover e pôr ou tirar tag já rodam os fluxos de Kanban e de tag.
- Propriedade com o mesmo valor volta 200 com
error. Não trate esseerrorcomo falha. ai_status: "inactive"não diz se é pausa ou desligamento.- Nota acrescenta por padrão. Uma integração que reenvia a mesma nota a cada evento
vai repetir o texto. Use
delete_previous_note: truese a nota for “estado atual”. - Responsável fora do departamento dá 404. Adicione o usuário ao departamento no painel antes.
Para saber mais
- Catálogos: ids de colunas e tags, slugs de propriedades
- Controle da IA, Notificar responsável
- Funil (Kanban), Tags, Propriedades, Departamentos, Contatos
- Termos para buscar: “PATCH vs POST REST”, “409 Conflict idempotent”, “round-robin assignment”.