Skip to main content
As rotas de lead ficam em /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.id e lead.wa_id de cada evento recebido. Ver Webhooks de saída.
Para a mesma ação em muitos leads (pôr tag, mover), as ações em massa de Contatos costumam ser mais simples. Se for pela API, espace as chamadas (Limites).

GET /leads/{numero}

Devolve os dados do lead.
200
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 campo property_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.
Número grande vai como texto. Um número JSON que não cabe com exatidão (inteiro acima de 9007199254740991 em módulo, ou que vira notação científica, como 1e21 ou 0.0000001) já chega arredondado ao servidor e dá 400. Mande como string: "12345678901234567890".

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:
Para completar, repita o mesmo 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.
200
closed_at: null é a conversa aberta. Use o thread_id em GET /messages/history.

PATCH /leads/{numero}/notes

Escreve na anotação do lead.
200 { "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.
200 { "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.
200
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

  • PUT com tags.mode: "replace" tira as tags que não vieram. Para só acrescentar, use o padrão "add".
  • No PUT, null e "" 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 PUT nã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/trigger depois (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 esse error como 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: true se a nota for “estado atual”.
  • Responsável fora do departamento dá 404. Adicione o usuário ao departamento no painel antes.

Para saber mais