Quickstart

Pré-requisitos

Uma conta ativa na Cordialy
Uma API key gerada em Integrações → API Keys
Um número de WhatsApp conectado na plataforma

Passo 1 — Crie um lead

Um lead é o contato que receberá a mensagem. Se ele já existe na plataforma, a API retorna o registro existente sem criar duplicata.

curl -X POST https://api.cordialy.ai/integrations/v1/leads \
  -H "X-API-Key: SUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_phone": "5511999998888",
    "name": "João Silva"
  }'

const lead = await fetch('https://api.cordialy.ai/integrations/v1/leads', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CORDIALY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customer_phone: '5511999998888',
    name: 'João Silva',
  }),
}).then(r => r.json());

console.log(lead.id); // salve este ID

import requests

lead = requests.post(
    'https://api.cordialy.ai/integrations/v1/leads',
    headers={'X-API-Key': 'SUA_KEY'},
    json={'customer_phone': '5511999998888', 'name': 'João Silva'}
).json()

print(lead['id'])  # salve este ID

Resposta:

{
  "id": "a1b2c3d4-...",
  "name": "João Silva",
  "customer_phone": "5511999998888",
  "status": "pending",
  "created_at": "2026-06-19T10:00:00.000Z"
}

Passo 2 — Envie uma mensagem

Use o id retornado no passo anterior:

curl -X POST https://api.cordialy.ai/integrations/v1/leads/LEAD_ID/messages \
  -H "X-API-Key: SUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Olá João! Seu pedido #1234 foi aprovado e está sendo preparado."}'

await fetch(`https://api.cordialy.ai/integrations/v1/leads/${lead.id}/messages`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CORDIALY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Olá João! Seu pedido #1234 foi aprovado e está sendo preparado.',
  }),
});

requests.post(
    f'https://api.cordialy.ai/integrations/v1/leads/{lead["id"]}/messages',
    headers={'X-API-Key': 'SUA_KEY'},
    json={'message': 'Olá João! Seu pedido #1234 foi aprovado e está sendo preparado.'}
)

Resposta:

{ "sent": true }

A mensagem é entregue ao lead via WhatsApp e aparece na plataforma destacada em roxo com a tag Via API.

Passo 3 — Acompanhe o histórico

curl https://api.cordialy.ai/integrations/v1/leads/LEAD_ID/messages \
  -H "X-API-Key: SUA_KEY"

Você verá a mensagem enviada com "source": "api" junto com as demais mensagens do lead.

Tratamento de erros

Sempre verifique o status HTTP da resposta:

const res = await fetch('...', { method: 'POST', ... });

if (!res.ok) {
  const error = await res.json();
  console.error(`Erro ${res.status}:`, error.message);
  // ex: "Lead não encontrado", "Mensagem não pode ser vazia"
}

Status	Significado
`200` / `201`	Sucesso
`400`	Dados inválidos na requisição
`401`	API key ausente ou inválida
`404`	Recurso não encontrado
`429`	Limite de requisições atingido
`500`	Erro interno — tente novamente

Próximos passos

Automatizar follow-ups

Programe mensagens automáticas de reativação.

Receber respostas via Webhook

Seja notificado quando o lead responder.

Sincronizar leads do CRM

Estratégias para manter leads sincronizados.

Entender os agentes de IA

Como a IA decide qual agente responde.

Início

Guias

Exemplos

Pré-requisitos

Passo 1 — Crie um lead

Passo 2 — Envie uma mensagem

Passo 3 — Acompanhe o histórico

Tratamento de erros

Próximos passos

Automatizar follow-ups

Receber respostas via Webhook

Sincronizar leads do CRM

Entender os agentes de IA

​Pré-requisitos

​Passo 1 — Crie um lead

​Passo 2 — Envie uma mensagem

​Passo 3 — Acompanhe o histórico

​Tratamento de erros

​Próximos passos

Automatizar follow-ups

Receber respostas via Webhook

Sincronizar leads do CRM

Entender os agentes de IA

Pré-requisitos

Passo 1 — Crie um lead

Passo 2 — Envie uma mensagem

Passo 3 — Acompanhe o histórico

Tratamento de erros

Próximos passos