Introdução à API #

A API REST do Your AI Connector permite que você crie sua própria integração com sua conta. Você pode criar e pesquisar contatos, gerenciar campanhas, FAQs, tarefas e agendamentos, enviar mensagens, registrar webhooks, ler análises e conectar canais de mensagens — tudo o que o painel faz, controlado por código.

Esta é a página central da documentação da API. Se você estiver conectando o Your AI Connector a uma ferramenta que já possui uma integração integrada, talvez você nem precise da API. A API é destinada a integrações personalizadas e automação em escala.

URL Base #

Todas as solicitações vão para o mesmo endereço web base, e todos os caminhos nestes documentos são relativos a ele:

https://api.youraiconnector.com/v1

Portanto, o endpoint de campanhas é https://api.youraiconnector.com/v1/campaigns, o endpoint de contatos é https://api.youraiconnector.com/v1/contacts, e assim por diante.

Todas as solicitações devem usar uma conexão segura (HTTPS). Solicitações HTTP simples são rejeitadas.

Obtendo uma chave de API #

O acesso à API é um recurso pago. Se o seu plano não o incluir, cada solicitação retornará um 403 com este corpo:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

Assim que o acesso à API estiver habilitado em seu plano, gere uma chave a partir do painel. O passo a passo completo está em Acesso à API — em resumo: vá para Configurações → Integrações → Chave de API para gerar ou regenerar sua chave. A Chave de API é uma seção própria em Integrações, separada de Webhooks, e ela só aparece quando o acesso à API está habilitado em seu plano. Trate a chave como uma senha: ela concede acesso total à sua conta.

Autenticação #

Você pode enviar sua chave de API de quatro maneiras. Todas funcionam em todos os endpoints que aceitam autenticação por chave de API.

Para produção, prefira uma das formas de cabeçalho para que sua chave nunca apareça em um log de servidor ou histórico do navegador. A forma de parâmetro de consulta sempre funciona e é a mais simples para um teste rápido.

Consulte Autenticação para uma análise completa de cada método, com exemplos e orientações sobre quando usar cada um.

Sua primeira solicitação #

Aqui está uma chamada completa e funcional que lista as campanhas em sua conta. Ela usa sua chave de API e retorna as campanhas mais recentes primeiro.

cURL

curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.campaigns);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])

Uma resposta bem-sucedida tem esta aparência:

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": null
}

Respostas de sucesso e erro #

Toda resposta JSON contém uma flag success para que você possa ramificar a lógica sem precisar analisar códigos de status.

Uma resposta bem-sucedida é success: true mais os dados para aquele endpoint (o nome do campo varia — campaigns, contacts, data, e assim por diante):

{
  "success": true,
  "campaigns": []
}

Uma resposta com falha é success: false com uma mensagem error legível por humanos e um error_code numérico que corresponde ao status HTTP:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

Sempre verifique success (ou o status HTTP) antes de ler os dados. Consulte Erros e Paginação para ver a tabela completa de códigos de status e como paginar grandes conjuntos de resultados.

Limites de taxa #

Requisições autenticadas são limitadas a 300 requisições por minuto por chave de API. Há também um limite mais amplo de 1.200 requisições por minuto por conta, contando cada requisição autenticada feita para essa conta.

Se você exceder qualquer um dos limites, receberá uma resposta 429:

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

Aguarde e tente novamente após um curto intervalo. Você também pode verificar seu uso atual a qualquer momento com GET https://api.youraiconnector.com/v1/api-keys/usage, que retorna quantas requisições você usou na janela atual e quando ela será redefinida — útil para criar limitação de taxa (throttling) no lado do cliente. Consulte Chaves de API.

Guias de recursos #

Os grupos de recursos abaixo possuem cada um seu próprio guia com os caminhos exatos, campos de solicitação e formatos de resposta.

Agentes, Pontos de Entrada e Transmissões #

Agentes de IA, Pontos de Entrada e Transmissões estão todos na especificação OpenAPI publicada, para que você possa navegar pelos seus campos exatos e executar solicitações ao vivo no explorador de API. Cada um tem seu próprio guia: Agentes de IA, Pontos de Entrada e Transmissões.

Lendo esta documentação como Markdown #

Cada página nesta documentação possui um equivalente em Markdown simples: pegue o endereço da página e adicione /index.md ao final. Portanto, esta página também está disponível em https://docs.youraiconnector.com/api/getting-started/index.md, e ela é retornada como texto simples em vez de uma página da web — útil quando você deseja colar uma página em um assistente de IA ou importá-la para um script.

Para percorrer todo o conjunto, comece em https://docs.youraiconnector.com/sitemap.xml, que lista todas as páginas que publicamos. Observe que a documentação é mantida deliberadamente fora dos mecanismos de busca, portanto, buscar esses endereços diretamente é a maneira de acessá-la via código.

Não há um endpoint de documentação protegido por chave nem download em massa disponível ainda — os equivalentes em Markdown e o mapa do site são toda a interface, e nenhum deles requer uma chave de API.

Próximos passos #

• Autenticação — escolha o método de autenticação correto para sua integração.
• Erros e Paginação — lide com falhas e pagine através dos resultados.
• Acesso à API — gere sua chave e veja exemplos práticos.