API externa

A API deixa o seu site, landing page ou CRM conversar com o Tesseract:

• cadastrar leads (com nome, e-mail, campos e UTMs);
• iniciar os fluxos dos gatilhos Lead cadastrado e Parâmetro UTM;
• listar contatos e fluxos;
• rodar um fluxo para um contato.

Cada conta tem as próprias chaves e só enxerga os próprios dados.

Chaves

Em Configurações › API externa:

• Criar chave: dê um nome (ex.: Site, CRM). A chave inteira (tsk_...) aparece uma vez; copie e guarde no servidor que vai chamar a API. O Tesseract guarda só um resumo (hash) dela.
• Revogar: a chave para de funcionar na hora.
• Até 10 chaves ativas por conta e 120 requisições por minuto por chave (acima disso a resposta é 429).

Mande a chave em todo pedido, no cabeçalho:

Authorization: Bearer tsk_SUA_CHAVE

(X-Api-Key: tsk_SUA_CHAVE também vale.) Nunca coloque a chave no código que roda no navegador: chame a API do seu servidor.

Endereço: https://app.tesseract-ai.com.br/api/v1 (o card mostra o da sua instalação). Tudo é JSON, e os erros vêm como { "error": "mensagem" }.

Código	Quando
400	O corpo não é um JSON
401	Sem chave, chave inválida ou revogada
404	Contato ou fluxo não encontrado
409	O fluxo não pôde rodar (o motivo vem na mensagem)
422	Algum campo inválido (o motivo vem na mensagem)
429	Mais de 120 requisições por minuto com a mesma chave

Conferir a chave

GET /api/v1/ping → { "ok": true, "account": "Nome da conta" }

Cadastrar um lead

POST /api/v1/leads

{
  "phone": "11987654321",
  "name": "Maria Souza",
  "email": "[email protected]",
  "fields": { "plano": "anual", "cidade": "Campinas" },
  "utm": { "source": "facebook", "medium": "cpc", "campaign": "black-friday" }
}

Campo	Obrigatório	O que é
phone	sim	Com DDD. Sem o código do país, vale o do Brasil (55)
name	não	Nome do contato
email	não	Fica no campo email do contato
fields	não	Campos do contato ({chave} nos textos). Chaves com letras minúsculas, números e _
utm	não	source, medium, campaign, content, term. Também aceita utm_source... no nível de cima
start_flow	não	false só cadastra, sem iniciar fluxo

O que acontece:

• O contato: é encontrado pelo telefone ou criado. Os dados enviados são atualizados, e as UTMs ficam guardadas e aparecem nos textos como {utm_source}, {utm_campaign} etc.
• O fluxo: começa no máximo um, entre os fluxos ativos com os gatilhos Parâmetro UTM e Lead cadastrado. Vale o de maior prioridade e, na mesma prioridade, o de UTM. Um fluxo de UTM só entra se o cadastro trouxer as UTMs das regras dele.
• Quando o fluxo não começa: valem as mesmas proteções dos outros gatilhos, e o motivo volta em flow.reason:
  • a pessoa pediu para não receber;
  • a conversa está com a equipe;
  • a conversa já está em outro fluxo;
  • o mesmo fluxo já começou para o contato por um cadastro há menos de 10 minutos (formulário enviado duas vezes);
  • a automação está desligada;
  • na API oficial do WhatsApp, a pessoa está fora da janela de 24h.
• Quem nunca conversou com o bot: recebe só no WhatsApp conectado por QR Code, até 200 contatos novos por dia pela API, para proteger o número. Números sem WhatsApp ficam cadastrados, mas sem fluxo.

Resposta (201 quando o contato é novo, 200 quando já existia):

{
  "lead": {
    "id": "8c0e...",
    "name": "Maria Souza",
    "phone": "5511987654321",
    "email": "[email protected]",
    "stage": "novo",
    "handler": "ia",
    "opted_out": false,
    "purchased_at": null,
    "fields": { "plano": "anual", "cidade": "Campinas", "email": "[email protected]" },
    "utm": { "source": "facebook", "medium": "cpc", "campaign": "black-friday" },
    "created_at": "2026-10-21T12:00:00.000Z",
    "registered_at": "2026-10-21T12:00:00.000Z",
    "last_message_at": null
  },
  "created": true,
  "flow": { "started": true, "flow_id": "3f1a...", "flow_name": "Boas-vindas Black Friday", "reason": null }
}

Exemplo com curl:

curl -X POST https://app.tesseract-ai.com.br/api/v1/leads \
  -H "Authorization: Bearer tsk_SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"phone":"11987654321","name":"Maria","utm_campaign":"black-friday"}'

Listar e ver contatos

• GET /api/v1/leads?page=1&limit=20: os contatos da conta, os mais novos primeiro (até 100 por página).
  • Filtros: phone=11987654321 e registered=1 (só os cadastrados pela API).
  • Resposta: { "data": [...], "total": 42, "page": 1, "limit": 20 }.
• GET /api/v1/leads/{id}: um contato.

Fluxos

• GET /api/v1/flows: os fluxos da conta, com id, name, enabled, trigger_type e trigger_label. Os de grupo ficam de fora.
• POST /api/v1/flows/{id}/start com { "lead_id": "..." } ou { "phone": "11987654321" }: roda um fluxo ativo para um contato que já existe.
  • Tem as mesmas regras do botão Rodar fluxo da conversa.
  • Para quem ainda não existe, cadastre antes em POST /api/v1/leads.
  • Responde { "ok": true }, ou 409 com o motivo.

Gatilhos no editor de fluxos

No widget Iniciar quando:

• Lead cadastrado pela API (site, CRM): começa a cada cadastro.
  • Desmarque Também quem já conversou com o bot para valer só no primeiro cadastro de cada telefone.
• Lead cadastrado com parâmetro UTM: começa quando o cadastro traz as UTMs das regras.
  • São até 5 regras, e todas precisam valer.
  • Cada regra pode ser "igual a" ou "contém". Maiúsculas e acentos não contam.
  • Uma regra sem valor só pede que a UTM venha preenchida.