Acesso à API #

Uma API (Interface de Programação de Aplicações) é uma maneira de diferentes sistemas de software se comunicarem. A API Your AI Connector permite que você (ou seu desenvolvedor) crie contatos automaticamente, envie mensagens, gerencie listas e receba mensagens de entrada de canais personalizados — tudo sem usar o painel de controle.

Por que usar a API? Se você deseja conectar o aplicativo a uma ferramenta que não possui uma integração nativa, ou se precisa automatizar tarefas repetitivas em escala, a API é o caminho a seguir.

Gerando sua Chave de API #

1. Na barra lateral esquerda, clique em Configurações (ícone de engrenagem).
2. Na barra lateral de Configurações, sob o grupo Integrações, clique em Chave de API.

3. Se você ainda não possui uma chave, clique em Generate API key.
4. Se você já possui uma, ela será exibida mascarada em Your key. Se sua chave permitir, clique em Show para revelá-la e, em seguida, em Copy para copiá-la — você verá uma notificação de confirmação.
5. Armazene a chave em um local seguro — você precisará dela para cada solicitação de API.

Membros da equipe: a chave de API pertence ao proprietário da conta, portanto, se você estiver conectado como um membro convidado da equipe (incluindo um Administrador), a seção exibirá uma nota em vez da chave. Entre como proprietário da conta para visualizar, copiar ou regenerar a chave — isso também se aplica a chaves com escopo definido.

Onde encontrá-la: Chave de API é uma seção própria em Configurações → Integrações, separada de Webhooks. Se um guia ou um colega disser para você procurar a chave em “Webhooks”, procure na seção ao lado.

URL Base #

Todas as solicitações de API usam o seguinte endereço web base:

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

Autenticação #

Cada solicitação deve incluir sua chave de API para que a plataforma saiba que é você. A maneira mais simples é adicioná-la ao final do endereço web:

https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY

Você também pode enviar a chave como um cabeçalho de solicitação em vez de na URL (recomendado para produção, para que a chave não acabe nos logs do servidor):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

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

Procurando pelos guias completos para desenvolvedores? Esta página é uma introdução rápida que cobre as operações mais comuns. Para guias completos e passo a passo — com todos os recursos, incluindo exemplos em cURL, JavaScript e Python — consulte Introdução à API e a Referência da API.

Operações Comuns de API #

Criar um Contato #

Solicitação:

POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

Campos obrigatórios: um phoneNumber (com código do país) é sempre necessário para criar um contato. Apenas um endereço de e-mail não é suficiente — uma solicitação sem um número de telefone válido será rejeitada. O e-mail é opcional.

Resposta:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

Salve o data.contactId — você precisará dele para a chamada “Adicionar um Contato a uma Lista”.

Adicionar um Contato a uma Lista #

POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

Encontre o ID de uma lista no aplicativo em Contatos → Listas, no menu da linha da lista (Copiar ID da lista).

Atualizar um contato #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

Apenas os campos que você incluir serão alterados. Esta também é a maneira de carregar em massa valores de campos personalizados após uma importação — consulte Campos Personalizados, Perfil do Lead e Notas. Detalhes completos na API de Contatos.

Enviar uma Mensagem (Canal Personalizado) #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

Receber Mensagens de Entrada (Canal Personalizado) #

Aceite mensagens de sistemas externos como um canal personalizado. É assim que integrações como o GoHighLevel enviam mensagens para o Your AI Connector. Veja Canais Personalizados para detalhes completos.

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}

Visão Geral das Operações Disponíveis #

Limitação de Taxa (Rate Limiting) #

The API enforces rate limits to ensure platform stability. Exceeding your limit returns 429 Too Many Requests — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in import feature or email hi@youraiconnector.com for guidance.

Melhores práticas #

• Armazene sua chave de API com segurança — use um gerenciador de senhas ou configuração do lado do servidor, nunca código do lado do cliente que um visitante do navegador possa ler.
• Sempre inclua o código do país nos números de telefone (+1 para EUA, +44 para Reino Unido, +31 para Holanda).
• Trate erros de forma elegante — verifique os códigos de status e leia quaisquer mensagens de erro retornadas.
• Trate duplicatas — um número de telefone duplicado retorna { "success": false, "error_code": 409 } em vez de um novo contato. Procure o contato primeiro se precisar trabalhar com ele.
• Teste com um pequeno conjunto de dados antes de executar operações em massa.

Respostas de Erro #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

Próximos passos #

• Webhooks — receba notificações em tempo real do aplicativo (uma seção separada da sua chave de API).
• Conectar assistentes de IA (MCP) — use a mesma chave de API para permitir que o Claude gerencie sua conta.
• Formulários de lead do Facebook — use a API com plataformas de automação para capturar leads.
• Integração com GoHighLevel — um exemplo completo de integração de API bidirecional.