Crie uma integração de ponta a ponta

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

Autentica com uma chave de API
Cria um Agente de IA e configura o comportamento do seu assistente
Conecta um canal de mensagens (usamos o WhatsApp Web como exemplo prático) e o aponta para o Agente
Importa contatos
Envia e lê mensagens
Lê análises
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 para confirmar se ele está habilitado e Autenticação 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.

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

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

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

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

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

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

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:

{
  "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:

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.

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

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

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" }'

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

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.

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

{
  "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.

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)

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:

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

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

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

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:

{
  "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.

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

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

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

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

{
  "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.

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

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

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

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();

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.

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:

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

{
  "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

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

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

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"]

{
  "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 e a página de Webhooks 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 · Contatos · FAQs · Mensagens · Agendamentos
Canais · Modelos · Análises · Webhooks · Chaves de API
Novo por aqui? Primeiros passos · Autenticação · Erros & Paginação

Stuck on something this guide does not cover? Email hi@youraiconnector.com.

Crie uma integração de ponta a ponta #

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

Passo 2 — Criar um Agente de IA #

Configurar o assistente #

Passo 3 — Conectar um canal #

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

Roteie o canal para o seu Agente #

Etapa 4 — Importe seus contatos #

Etapa 5 — Envie e leia mensagens #

Envie uma mensagem #

Leia uma conversa #

Passo 6 — Ler análises #

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

Juntando tudo #

Crie uma integração de ponta a ponta

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

Passo 2 — Criar um Agente de IA

Configurar o assistente

Passo 3 — Conectar um canal

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

Roteie o canal para o seu Agente

Etapa 4 — Importe seus contatos

Etapa 5 — Envie e leia mensagens

Envie uma mensagem

Leia uma conversa

Passo 6 — Ler análises

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

Juntando tudo