> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cordialy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Envie sua primeira mensagem via API em menos de 5 minutos

## 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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```typescript Node.js theme={null}
  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
  ```

  ```python Python theme={null}
  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
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "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:

<CodeGroup>
  ```bash cURL theme={null}
  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."}'
  ```

  ```typescript Node.js theme={null}
  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.',
    }),
  });
  ```

  ```python Python theme={null}
  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.'}
  )
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{ "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

```bash theme={null}
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:

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="Automatizar follow-ups" icon="clock" href="/guides/followups">
    Programe mensagens automáticas de reativação.
  </Card>

  <Card title="Receber respostas via Webhook" icon="webhook" href="/guides/webhooks">
    Seja notificado quando o lead responder.
  </Card>

  <Card title="Sincronizar leads do CRM" icon="users" href="/guides/leads">
    Estratégias para manter leads sincronizados.
  </Card>

  <Card title="Entender os agentes de IA" icon="robot" href="/guides/agents">
    Como a IA decide qual agente responde.
  </Card>
</CardGroup>