# Crie uma integração de ponta a ponta

Este guia percorre tudo o que você precisa para executar o <span data-t="appName">Your AI Connector</span> a partir do seu próprio código, sem nunca abrir o painel. Ao final, você terá criado uma integração mínima que:

1. Autentica com uma chave de API
2. Cria um Agente de IA e configura o comportamento do seu assistente
3. Conecta um canal de mensagens (usamos o WhatsApp Web como exemplo prático) e o aponta para o Agente
4. Importa contatos
5. Envia e lê mensagens
6. Lê análises
7. Assina webhooks para eventos em tempo real

Cada etapa contém links para o guia de recursos completo, para que você possa se aprofundar nos detalhes quando precisar. Esta página é o mapa; os guias de recursos são o território.

> **Antes de começar.** O acesso à API é um recurso pago. Se o seu plano não o incluir, cada solicitação retornará `403`. Consulte [Acesso à API](../integrations/api-access.md) para confirmar se ele está habilitado e [Autenticação](authentication.md) para conhecer todas as formas de enviar sua chave.

Todos os caminhos abaixo são relativos à URL base:

```
https://api.youraiconnector.com/v1
```

---

## Etapa 1 — Obtenha uma chave de API e faça sua primeira solicitação

Sua chave de API fica no aplicativo em **Configurações → Integrações → Chave de API** — sua própria seção em Integrações, separada de Webhooks, que só aparece quando o acesso à API está disponível no plano. Gere uma, copie-a e armazene-a em um local seguro (um armazenamento de segredos no lado do servidor ou variável de ambiente — nunca no código do navegador). Instruções completas estão em [Acesso à API](../integrations/api-access.md).

Assim que tiver uma chave, confirme se ela funciona chamando o endpoint de integridade. Existem várias maneiras de enviar a chave; a mais simples é o parâmetro de consulta `?apiKey=`, mas para código real, prefira o cabeçalho `X-API-Key` para que a chave nunca termine nos logs do servidor ou no histórico do navegador.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const BASE = "https://api.youraiconnector.com/v1";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };

const res = await fetch(`${BASE}/health`, { headers });
const data = await res.json();
console.log(data); // { "success": true, ... }
```

**Python**

```python
import requests

BASE = "https://api.youraiconnector.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

res = requests.get(f"{BASE}/health", headers=HEADERS)
print(res.json())  # { "success": true, ... }
```

Toda resposta bem-sucedida é envolvida no mesmo envelope — um campo `success: true` mais os dados do resultado. Erros retornam `success: false` com uma mensagem `error` e um `error_code`. Consulte [Erros e Paginação](errors-and-pagination.md) para obter a lista completa e saber como os endpoints de lista paginam com `?limit` e `?cursor`.

> **Limite de taxa.** Requisições autenticadas são limitadas a **300 por minuto** (com um teto maior de 1.200/minuto por conta). Exceder esse limite retorna `429`; aguarde e tente novamente.

---

## Passo 2 — Criar um Agente de IA

Um **Agente de IA** é a unidade que contém o comportamento do seu assistente: suas instruções, seu objetivo, seu horário de funcionamento e como ele fala com os contatos. É ele quem responde a uma conversa, portanto, esta é a primeira coisa natural a se criar.

Crie um com `POST /agents`. `name` é o único campo que vale a pena enviar inicialmente; todo o resto pode ser definido com a chamada de configuração do bot abaixo.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbound WhatsApp Leads",
    "language": "en"
  }'
```

**JavaScript**

```javascript
const res = await fetch(`${BASE}/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Inbound WhatsApp Leads",
    language: "en",
  }),
});
const { agent_id } = await res.json();
```

**Python**

```python
res = requests.post(
    f"{BASE}/agents",
    headers=HEADERS,
    json={"name": "Inbound WhatsApp Leads", "language": "en"},
)
agent_id = res.json()["agent_id"]
```

Uma criação bem-sucedida retorna `201` com o novo ID:

```json
{
  "success": true,
  "agent_id": "abc123agent"
}
```

**Salve o `agent_id`** — você fará referência a ele ao rotear canais.

### Configurar o assistente

`PUT /agents/{agentId}/bot-config` define o comportamento do assistente. Ele *mescla* os campos que você envia com a configuração existente, portanto, tudo o que você omitir será preservado:

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Greet warmly, answer questions about our services, and offer to book a call.",
    "goal": "Book a discovery call.",
    "ai_speed": "balanced"
  }'
```

Defina o horário de funcionamento com `PUT /agents/{agentId}/active-hours` para que o assistente responda apenas durante o horário comercial; fora dessas janelas, ele não responde automaticamente.

> **Base de conhecimento.** Para fazer com que o assistente responda com base no seu próprio conteúdo, anexe FAQs. Veja o [guia de FAQs](faqs.md).

> **Legado: campanhas clássicas.** Contas que ainda possuem uma página de **Campanhas** criam o mesmo comportamento de assistente em uma campanha (usando `POST /campaigns` com um objeto `type` e um `bot`, depois `PUT /campaigns/{campaignId}/bot-config`). A lista completa de campos de campanha e controles de ciclo de vida estão no [guia de Campanhas](campaigns.md). Se você estiver criando algo novo, crie um Agente.

---

## Passo 3 — Conectar um canal

Um Agente precisa de uma maneira de enviar e receber mensagens. Sete fluxos de conexão podem ser controlados pela API: WhatsApp Business, WhatsApp Web, Instagram e Messenger juntos (um fluxo Meta compartilhado), contas pessoais do Instagram, Telegram, LINE e Viber. Os canais restantes — SMS, e-mail, widget de chat e canais personalizados, entre outros — são configurados no painel em vez de via REST, e uma vez conectados, os endpoints de mensagens, contatos e roteamento funcionam exatamente da mesma maneira neles. `GET /channels` é a fonte da verdade em tempo real sobre o que uma determinada conta realmente tem conectado:

```bash
curl "https://api.youraiconnector.com/v1/channels?apiKey=YOUR_API_KEY"
```

O conjunto completo de fluxos de conexão/desconexão para cada canal está documentado no [Guia de Canais](channels.md). Abaixo, percorremos o **WhatsApp Web** de ponta a ponta, pois ele mostra o padrão mais interessante: um fluxo de pareamento por código QR que seu wrapper precisa renderizar e consultar.

### Exemplo prático: parear WhatsApp Web por código QR

O pareamento do WhatsApp Web é uma dança de três chamadas — **iniciar**, **buscar o QR**, **consultar até conectar**.

**1. Inicie a sessão de pareamento.** Passe o número que deseja conectar no formato E.164.

```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'
```

```javascript
await fetch(`${BASE}/channels/whatsapp-web/connections`, {
  method: "POST",
  headers,
  body: JSON.stringify({ phone_number: "+15551230000" }),
});
```

```python
requests.post(
    f"{BASE}/channels/whatsapp-web/connections",
    headers=HEADERS,
    json={"phone_number": "+15551230000"},
)
```

**2. Busque o código QR e mostre-o ao usuário.** Consulte este endpoint a cada 10–15 segundos. A resposta inclui o payload `qr_code` bruto (renderize-o você mesmo como uma imagem QR) e um `qr_data_url` pronto para exibição.

```bash
curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"
```

```json
{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@abc...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo..."
}
```

Na interface do seu wrapper, insira o `qr_data_url` diretamente em um `<img src="...">` e peça ao usuário que o escaneie em **WhatsApp → Aparelhos conectados** no telefone dele. Se o QR expirar (uma resposta `410`), reinicie a partir do passo 1 para obter um novo.

**3. Consulte o status até que ele se conecte.** Após o usuário escanear, continue consultando o endpoint de status até que ele reporte `connected` (o serviço também pode reportar `open`). Trate `disconnected` e `not_initialized` como falhas terminais.

```python
import time

PHONE = "+15551230000"
while True:
    res = requests.get(
        f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status",
        headers=HEADERS,
    )
    status = res.json()["status"]
    if status in ("connected", "open"):
        print("Connected!")
        break
    if status in ("disconnected", "not_initialized"):
        raise RuntimeError(f"Pairing failed: {status}")
    time.sleep(5)
```

```javascript
async function waitForConnection(phone) {
  while (true) {
    const res = await fetch(
      `${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`,
      { headers }
    );
    const { status } = await res.json();
    if (status === "connected" || status === "open") return;
    if (status === "disconnected" || status === "not_initialized") {
      throw new Error(`Pairing failed: ${status}`);
    }
    await new Promise((r) => setTimeout(r, 5000));
  }
}
```

> **Atenção.** Cada número de WhatsApp Web conectado acarreta uma cobrança mensal recorrente de manutenção até que você o desconecte (`DELETE /channels/whatsapp-web/connections/{phoneNumber}`).

### Roteie o canal para o seu Agente

Conectar um canal faz com que ele funcione; roteá-lo diz à plataforma *qual Agente de IA* deve responder a novas conversas recebidas nele. Defina o Ponto de Entrada padrão do canal, nomeando o Agente que você criou no Passo 2:

```bash
curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }'
```

Repita a chamada uma vez por canal — um padrão de canal por canal. Para deixar um canal sem um Agente respondendo, chame `DELETE /entry-points/channel-defaults?channel=whatsapp_web`; para verificar se a hierarquia de Pontos de Entrada está ativa para a conta, chame `GET /entry-points/routing-status`. O mapa `POST /channels/campaign` mais antigo é mantido apenas para reversão e não é mais consultado para roteamento de entrada. Veja o [guia de Canais](channels.md) para os outros tipos de canal e para o fluxo OAuth do WhatsApp Business.

---

## Etapa 4 — Importe seus contatos

Com um canal ativo, carregue as pessoas que você deseja alcançar. O endpoint de importação aceita até **500 registros por chamada**. Cada registro precisa de um `phone_number` em formato internacional; todo o resto é opcional. Registros com números inválidos, canais não suportados ou números que já existem são ignorados — e cada omissão é relatada com seu índice e motivo, para que você possa tentar novamente apenas as falhas.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "defaultChannel": "whatsapp_web"
  }'
```

**JavaScript**

```javascript
const res = await fetch(`${BASE}/contacts/import`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    defaultChannel: "whatsapp_web",
  }),
});
const result = await res.json();
console.log(`${result.imported} imported, ${result.skipped.length} skipped`);
```

**Python**

```python
res = requests.post(
    f"{BASE}/contacts/import",
    headers=HEADERS,
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "defaultChannel": "whatsapp_web",
    },
)
result = res.json()
print(f"{result['imported']} imported, {len(result['skipped'])} skipped")
```

A resposta informa exatamente o que aconteceu:

```json
{
  "success": true,
  "imported": 2,
  "contact_ids": ["contactId1", "contactId2"],
  "skipped": []
}
```

Para criação individual, listagem/consulta, listas, tags e campos personalizados, consulte o [Guia de contatos](contacts.md).

---

## Etapa 5 — Envie e leia mensagens

### Envie uma mensagem

O envio mais simples é **agnóstico ao canal**: forneça a identidade do contato e o corpo da mensagem, e a plataforma a entrega em qualquer canal em que o contato esteja. Você pode direcionar por `contact_id`, ou por `channel` mais o campo de identidade correspondente (`phone_number` para WhatsApp/WhatsApp Web/SMS, `instagram_id` para Instagram, e assim por diante).

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "phone_number": "+12025551234",
    "body": "Hi Ann! Thanks for reaching out."
  }'
```

**JavaScript**

```javascript
const res = await fetch(`${BASE}/contacts/send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    channel: "whatsapp_web",
    phone_number: "+12025551234",
    body: "Hi Ann! Thanks for reaching out.",
  }),
});
const { message_id } = await res.json();
```

**Python**

```python
res = requests.post(
    f"{BASE}/contacts/send",
    headers=HEADERS,
    json={
        "channel": "whatsapp_web",
        "phone_number": "+12025551234",
        "body": "Hi Ann! Thanks for reaching out.",
    },
)
message_id = res.json()["message_id"]
```

A entrega é **assíncrona** — um `201` significa que a mensagem foi *aceita e colocada na fila*, ainda não entregue. (Contatos com modo não perturbe ou modo privado ativado são rejeitados com um `422`.)

```json
{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp_web"
}
```

### Leia uma conversa

Para ler as mensagens de volta, liste-as por contato, da mais recente para a mais antiga, com paginação por cursor. Passe o `next_cursor` de uma resposta como o `cursor` da próxima para percorrer o histórico.

```bash
curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"
```

```python
res = requests.get(
    f"{BASE}/contacts/contact123/messages",
    headers=HEADERS,
    params={"limit": 50},
)
page = res.json()
for msg in page["messages"]:
    print(msg)
next_cursor = page["next_cursor"]  # pass back as ?cursor= for the next page
```

Você também pode filtrar por tipo de conteúdo (`?filter=text|media|tool_use`) ou direção (`?direction=inbound|outbound`). O [Guia de mensagens](messages.md) aborda anexos de mídia, marcação de mensagens como lidas e as visualizações de mensagens por sessão.

> **Não faça polling para verificar respostas.** Listar mensagens com um temporizador funciona, mas desperdiça requisições e adiciona atraso. Para mensagens recebidas, use webhooks — essa é a Etapa 7.

---

## Passo 6 — Ler análises

Assim que as mensagens começarem a fluir, o resumo de análise fornece contagens agregadas em um intervalo de datas: enviadas, entregues, lidas, respondidas, agendadas, contatos criados e créditos gastos/recarregados. Você obtém tanto os totais do intervalo quanto uma série diária preenchida com zeros — perfeito para um gráfico de painel. Opcionalmente, limite-o a uma única campanha com `campaign_id` (os exemplos abaixo usam um ID de campanha de espaço reservado, `abc123campaign`); deixe o parâmetro de fora para obter totais de toda a conta.

```bash
curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"
```

```javascript
const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  campaign_id: "abc123campaign",
});
const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers });
const { totals, by_date } = await res.json();
```

```python
res = requests.get(
    f"{BASE}/analytics/summary",
    headers=HEADERS,
    params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"},
)
data = res.json()
totals = data["totals"]
by_date = data["by_date"]
```

O intervalo padrão é de 30 dias e é limitado a 366. Para registros de uso crédito a crédito e detalhamentos de custos de IA, consulte o [Guia de análises](analytics.md).

---

## Passo 7 — Inscrever-se em webhooks para eventos em tempo real

O polling é aceitável para um script rápido, mas uma integração real deve ser **baseada em push**. Os webhooks permitem que a plataforma chame *seu* servidor no momento em que algo acontece — um novo contato, uma resposta, um agendamento, um chat concluído.

Primeiro, descubra os nomes exatos dos eventos aos quais você pode se inscrever:

```bash
curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"
```

```json
{
  "success": true,
  "events": [
    "Contact Created",
    "Human Alerted",
    "Appointment Booked",
    "Replies",
    "New Message",
    "Chat Concluded",
    "Task Created",
    "Daily Summary Created"
  ]
}
```

Em seguida, crie uma inscrição apontando para uma URL HTTPS em seu servidor. Use as strings de evento exatas da chamada acima.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Lead updates hook"
  }'
```

**JavaScript**

```javascript
const res = await fetch(`${BASE}/webhooks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Lead updates hook",
  }),
});
const { webhook_id } = await res.json();
```

**Python**

```python
res = requests.post(
    f"{BASE}/webhooks",
    headers=HEADERS,
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Lead updates hook",
    },
)
webhook_id = res.json()["webhook_id"]
```

```json
{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Lead updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}
```

A URL deve usar HTTPS e ser publicamente acessível. A partir daqui, seu servidor recebe um POST para cada evento inscrito. Você pode enviar um teste de entrega, verificar a integridade de uma inscrição e reativar uma inscrição que foi desativada automaticamente após falhas repetidas — consulte o [Guia de webhooks](webhooks.md) e a página de [Webhooks](../integrations/webhooks.md) no nível de integrações para formatos de payload e verificação.

---

## Juntando tudo

Aqui está todo o fluxo em resumo:

| Passo | Objetivo | Chamada principal |
|---|---|---|
| 1 | Autenticar | `GET /health` |
| 2 | Criar + ajustar o assistente | `POST /agents`, `PUT /agents/{id}/bot-config`, `PUT /agents/{id}/active-hours` |
| 3 | Conectar um canal e roteá-lo | `POST /channels/whatsapp-web/connections` → verificar QR + status → `PUT /entry-points/channel-defaults` |
| 4 | Carregar contatos | `POST /contacts/import` |
| 5 | Enviar & ler | `POST /contacts/send`, `GET /contacts/{id}/messages` |
| 6 | Medir | `GET /analytics/summary` |
| 7 | Reagir em tempo real | `POST /webhooks` |

Um wrapper mínimo consiste apenas nessas sete chamadas conectadas à sua própria interface. A partir daí, adicione os guias por recurso conforme precisar de mais:

- [Campanhas](campaigns.md) · [Contatos](contacts.md) · [FAQs](faqs.md) · [Mensagens](messages.md) · [Agendamentos](appointments.md)
- [Canais](channels.md) · [Modelos](templates.md) · [Análises](analytics.md) · [Webhooks](webhooks.md) · [Chaves de API](api-keys.md)
- Novo por aqui? [Primeiros passos](getting-started.md) · [Autenticação](authentication.md) · [Erros & Paginação](errors-and-pagination.md)

Stuck on something this guide does not cover? Email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com).