API e Integrações

A Ledio se integra ao seu sistema nos dois sentidos. Você avisa a Ledio quando algo acontece do seu lado (alguém se cadastrou, alguém comprou) e a Ledio avisa você quando algo acontece na conversa (um contato novo apareceu, um contato virou cliente).

Todos os endpoints partem de https://api.ledio.ai e recebem e devolvem JSON.

Toda chamada precisa de dois cabeçalhos. Os dois são gerados no painel, em Configurações → API e Webhooks.

Faltando ou errado, a resposta é 401 com uma mensagem dizendo qual dos dois falhou.

Os endpoints respondem 200 com o mesmo formato. Confira sempre o campo success: um 200 com success: false significa que autenticamos você, mas a ação não aconteceu (número inexistente no WhatsApp, contato não encontrado, canal desconectado).

{
  "success": true,
  "message": "Welcome message sent",
  "contactId": "1f5c2a10-2b3c-4d5e-6f70-8a9b0c1d2e3f"
}

Avisa que alguém se cadastrou no seu sistema. A Ledio cria o contato, confere se o número existe no WhatsApp e, existindo, o agente de IA inicia a conversa no fluxo escolhido.

curl -X POST https://api.ledio.ai/webhook/external/new-user \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-webhook-secret: whsec_SEU_SECRET" \
  -d '{
    "phone": "5511999999999",
    "name": "João Silva",
    "externalId": "usr_abc123",
    "flow": "CONVERSION",
    "context": { "source": "landing_page", "campaign": "black_friday" }
  }'

Avisa que a pessoa assinou ou comprou. O agente para de vender e passa a tratá-la como cliente. Mande isso assim que o pagamento confirmar: sem esse aviso, o agente continua oferecendo o que ela já comprou.

curl -X POST https://api.ledio.ai/webhook/external/user-converted \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-webhook-secret: whsec_SEU_SECRET" \
  -d '{
    "phone": "5511999999999",
    "context": { "plan": "pro", "value": 2990, "currency": "BRL" }
  }'

Muda como o agente se comporta com um contato que já existe. Útil quando a pessoa abre um chamado de suporte no seu sistema e você quer que a conversa no WhatsApp acompanhe.

curl -X POST https://api.ledio.ai/webhook/external/change-flow \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-webhook-secret: whsec_SEU_SECRET" \
  -d '{ "phone": "5511999999999", "flow": "SUPPORT" }'

Envia um texto pelo WhatsApp para um contato que já conversou com você.

curl -X POST https://api.ledio.ai/webhook/external/send-message \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-webhook-secret: whsec_SEU_SECRET" \
  -d '{
    "phone": "5511999999999",
    "message": "Oi! Posso te ajudar?"
  }'

Envia um código de verificação pelo WhatsApp usando um template de autenticação aprovado pela Meta.

curl -X POST https://api.ledio.ai/webhook/external/otp \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-webhook-secret: whsec_SEU_SECRET" \
  -d '{
    "phone": "5511999999999",
    "code": "123456",
    "expiresInMinutes": 5
  }'

O caminho inverso. Cadastre uma URL em Configurações → API e Webhooks e a Ledio envia um POST para ela quando algo acontece na conversa.

Todos os eventos chegam no mesmo envelope:

{
  "id": "5f1c2a10-2b3c-4d5e-6f70-8a9b0c1d2e3f",
  "type": "contact.converted",
  "createdAt": "2026-08-14T18:22:05.412Z",
  "data": {
    "businessSlug": "sua-empresa",
    "contactId": "1f5c2a10-2b3c-4d5e-6f70-8a9b0c1d2e3f",
    "phone": "5511999999999",
    "name": "João Silva",
    "status": "CONVERTED",
    "flow": "ONBOARDING",
    "engagement": "HOT"
  }
}

Use o id para descartar repetições: em caso de falha na entrega a Ledio tenta de novo, então o mesmo evento pode chegar duas vezes. Trate o recebimento como idempotente.

Conferindo a assinatura

Cada requisição vai assinada no cabeçalho x-ledio-signature, no formato sha256=<hex>. É um HMAC-SHA256 do corpo exatamente como recebido, usando o segredo que você cadastrou.

import crypto from 'node:crypto'

// rawBody = o corpo como string, sem parse
function assinaturaConfere(rawBody, header, segredo) {
  const esperado =
    'sha256=' +
    crypto.createHmac('sha256', segredo).update(rawBody).digest('hex')

  const a = Buffer.from(esperado)
  const b = Buffer.from(header ?? '')
  // Comparação em tempo constante evita vazar a assinatura por timing
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Responda 2xx rápido. Se o seu endpoint demorar ou responder erro, a Ledio considera falha e tenta de novo mais tarde.

Guarde o contactId que volta na primeira chamada. Ele é a chave para correlacionar a conversa na Ledio com o registro no seu sistema, e evita depender do telefone, que muda.

Mande sempre o telefone no mesmo formato, com DDI e apenas números. A Ledio normaliza, mas manter o padrão de um lado só facilita a conferência quando algo não bate.

Trate success: false como resposta esperada, não como exceção. Número que não existe no WhatsApp é situação comum e não deveria quebrar a sua fila de processamento.

Se algo aqui não bater com o que você está vendo na prática, fale com a gente pelo suporte no painel. Documentação divergente do comportamento é bug, e a gente quer saber.