API de Pontos de Entrada #

Um Ponto de Entrada é uma regra de roteamento: “quando isso acontecer neste canal, entregue a conversa a este Agente”. Conectar um canal faz com que as mensagens cheguem à conta e criar um Agente lhe dá algo que pode responder, mas nenhum dos dois decide quem responde à primeira mensagem de um estranho. Os Pontos de Entrada decidem. Para o produto em si, consulte o guia de Pontos de Entrada.

• URL Base — https://api.youraiconnector.com/v1
• Autenticação — sua chave de API (veja Autenticação)
• Erros e paginação — veja Erros e Paginação

Todos os exemplos abaixo mostram a forma de consulta ?apiKey= em cURL e o cabeçalho X-API-Key em JavaScript e Python — ambos funcionam em todos os endpoints.

No explorador de API. Cada endpoint nesta página está na especificação OpenAPI publicada, para que você possa navegar pelos seus campos exatos e executar solicitações ao vivo no explorador de API.

A única chamada que a maioria das integrações precisa #

Conecte um canal, crie um Agente e, em seguida, aponte o canal para o Agente:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

Essa é toda a configuração para “este Agente responde ao WhatsApp”. Todo o resto nesta página é para regras mais específicas (palavras-chave, comentários, novos seguidores), vários números em um canal e para ler o que está configurado.

Como o roteamento é decidido #

Quando uma mensagem chega, a plataforma percorre uma hierarquia fixa e o primeiro passo que decidir vence:

1. Um humano assumiu a conversa — sem IA.
2. O contato já está atribuído a um Agente, manualmente ou porque uma conversa com esse Agente está em andamento — o mesmo Agente a mantém. Os Pontos de Entrada nunca movem uma conversa existente; para entregar um chat a um Agente diferente, atribua-o (no aplicativo ou com a ação Automações).
3. O contato está respondendo a uma transmissão — o Agente da transmissão responde, ou ninguém se a transmissão não tiver um.
4. Um Ponto de Entrada específico corresponde. Regras de palavra-chave superam regras de comentário, que superam regras de seguidor. Entre duas regras do mesmo tipo, a mais recentemente atualizada vence.
5. O padrão do canal para o canal no qual a mensagem chegou. Um padrão definido para o número específico para o qual o contato escreveu supera o padrão de todo o canal.
6. Nada correspondeu — a mensagem cai na caixa de entrada da sua equipe e nenhum assistente responde.

Duas coisas suavizam o passo 6. Uma conta com exatamente um Agente ativo e nenhum padrão configurado para o canal ainda recebe esse Agente como o responsável pela resposta, portanto, uma conta nova que conecta o WhatsApp e envia uma mensagem de teste não fica em silêncio. Esse limite nunca se aplica a um canal que possui uma regra de palavra-chave (lá, uma mensagem que não corresponde a nenhuma palavra-chave é deixada deliberadamente para um humano) e nunca substitui um canal que você definiu como ninguém (consulte Deixar um canal sem ninguém respondendo).

Se a hierarquia está ativa para uma conta é relatado por GET /entry-points/routing-status. Ela está ativada para todas as contas hoje; a chamada existe para que uma integração possa verificar em vez de presumir.

O objeto Ponto de Entrada #

{
  "id": "ep3KmQ8vTzXr5nWd",
  "type": "keyword",
  "channels": ["whatsapp", "instagram"],
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "enabled": true,
  "match_config": {
    "keywords": ["pricing", "quote"]
  },
  "first_response_mode": null,
  "first_response_exact_text": null,
  "public_comment_reply_exact_text": null,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Tipos de regra #

Uma regra de palavra-chave em um canal sem um padrão de canal também funciona como um filtro: mensagens que não correspondem a nenhuma das palavras-chave não recebem resposta automática e simplesmente vão para sua caixa de entrada, mesmo em uma conta com um único Agente.

Direcione um canal para um Agente #

PUT /entry-points/channel-defaults — torna um Agente o responsável por responder a novos contatos em um canal. Qualquer outro Agente definido atualmente como padrão desse canal é removido na mesma chamada, para que um canal sempre tenha exatamente um responsável. Definir o Agente que já é o padrão não altera nada.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ channel: "instagram", agent_id: "ag7HkQ2ZpLxR3mNb" }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb"},
)
data = res.json()

Resposta

{
  "success": true,
  "entry_point_id": "ep3KmQ8vTzXr5nWd",
  "disabled_entry_point_ids": ["epPrevious1234"]
}

entry_point_id é a regra agora em vigor; disabled_entry_point_ids lista quaisquer regras removidas para abrir espaço para ela (vazia quando não havia nada para substituir). Apenas contatos com os quais você nunca falou são afetados — qualquer pessoa que já esteja em uma conversa com um Agente mantém esse Agente.

Um 400 significa que channel ou agent_id está faltando, o Agente pertence a outra conta ou phone_number não é um dos seus números conectados.

Veja quem responde a cada canal #

GET /entry-points/channel-defaults — todos os padrões de canal na conta, do mais novo para o mais antigo, incluindo os removidos (enabled: false) e um canal deliberadamente definido como ninguém (agent_id: ""). Filtre por enabled para ver o cenário atual.

cURL

curl "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": {},
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    },
    {
      "id": "epAEnhHoozpoGVze",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "agRotterdamBranch",
      "enabled": true,
      "match_config": { "phone_numbers": ["+31685101091"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Esta é a leitura de toda a conta. Listar as regras de um Agente com GET /agents/{agentId}/entry-points não pode mostrar um canal definido como ninguém, porque essa regra não pertence a nenhum Agente.

Deixe um canal sem ninguém respondendo #

DELETE /entry-points/channel-defaults?channel=instagram — remove o padrão de todo o canal para um canal. O canal é nomeado como um parâmetro de consulta, não no corpo. Adicione &phone_number=%2B31685101091 para limpar apenas o padrão daquele número e permitir que o número volte para quem responde ao canal.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    params={"channel": "instagram"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{ "success": true, "disabled_entry_point_ids": ["ep3KmQ8vTzXr5nWd"] }

Seguro para repetir: limpar um canal que não tem padrão é um 200 com uma lista vazia. Limpar significa desdefinir, não silenciar — em uma conta com exatamente um Agente ativo, um canal não configurado ainda recorre a esse Agente. Para manter a IA fora de um canal completamente, escolha Ninguém está respondendo para ele no painel Quem responde a novas conversas do aplicativo (isso grava um padrão explícito de “ninguém” que o fallback nunca substitui), ou pause o Agente com PATCH /agents/{agentId}/active.

Um Agente por número de WhatsApp #

O roteamento é por canal por padrão: todos os seus números de WhatsApp compartilham um responsável. Com dois ou mais números conectados no WhatsApp Business ou WhatsApp Web, um padrão pode ser definido para um único número, para que uma empresa com um número por filial ou marca possa dar a cada um seu próprio Agente dentro de uma única conta.

Envie phone_number com a chamada set:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "agent_id": "agRotterdamBranch",
    "phone_number": "+31685101091"
  }'

• O número deve ser um dos seus números conectados nesse canal, escrito como aparece em números conectados (E.164 com o +); qualquer outra coisa é um 400.
• A regra é armazenada como um padrão de canal com match_config.phone_numbers: ["+31685101091"]. Uma mensagem que chega nesse número vai para seu Agente; todos os outros números continuam seguindo o padrão de todo o canal.
• Definir ou limpar o padrão de todo o canal não altera as regras com escopo de número, e vice-versa. Limpe a regra própria de um número com DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091.
• As respostas sempre saem do número para o qual o contato escreveu, para que o contato continue falando com o mesmo número e o mesmo Agente.

Adicionar uma regra mais específica #

POST /agents/{agentId}/entry-points — cria uma regra de palavra-chave, comentário ou seguidor (ou um padrão de canal, embora PUT /entry-points/channel-defaults seja a melhor opção para isso, pois ele desativa o respondente anterior para você). O Agente no caminho sempre vence: uma regra nunca pode ser criada para um Agente diferente daquele na URL.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "keyword",
      channels: ["whatsapp", "instagram"],
      match_config: { keywords: ["pricing", "quote"] },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "type": "keyword",
        "channels": ["whatsapp", "instagram"],
        "match_config": {"keywords": ["pricing", "quote"]},
    },
)
data = res.json()

Resposta (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Uma regra de comentário para DM que reage apenas a comentários dizendo “LINK” em duas postagens específicas, aguarda dois minutos e envia uma primeira mensagem fixa:

{
  "type": "instagram_comment",
  "channels": ["instagram"],
  "match_config": {
    "keywords": ["LINK"],
    "post_ids": ["17895695668004550", "17841400008460056"],
    "delay_minutes": 2
  },
  "first_response_mode": "exact_text",
  "first_response_exact_text": "Hi {{first_name}}, here is the link you asked for: https://example.com/guide",
  "public_comment_reply_exact_text": "Sent you a DM!"
}

Deixe keywords vazio para enviar DM a todos que comentarem nas postagens monitoradas, e post_ids vazio para monitorar todas as postagens. Um 400 aponta o que está errado: um type desconhecido, um channels vazio, uma regra de palavra-chave sem palavras-chave ou uma regra de comentário que não lista seu próprio canal.

Listar as regras de um Agente #

GET /agents/{agentId}/entry-points — as regras que enviam conversas para este Agente, da mais recente para a mais antiga: seus padrões de canal, regras de palavra-chave, regras de comentário e regras de seguidor. Regras desativadas também aparecem, com enabled: false.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "keyword",
      "channels": ["whatsapp", "instagram"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": { "keywords": ["pricing", "quote"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Alterar uma regra #

PUT /entry-points/{entryPointId} — altera uma regra. Envie apenas os campos que você está alterando; configurações aninhadas podem ser endereçadas folha por folha com uma chave pontuada, como "match_config.keywords". Sempre que a alteração toca em type, channels ou match_config, a regra inteira é verificada novamente, portanto, uma edição parcial nunca pode deixar uma regra inutilizável (mudar type para keyword sem fornecer palavras-chave é rejeitado). Enviar agent_id transfere a regra para outro de seus Agentes; um campo em branco é rejeitado. Campos de propriedade e identidade são ignorados.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "match_config": { "keywords": ["pricing", "quote", "demo"] } }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ match_config: { keywords: ["pricing", "quote", "demo"] } }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"match_config": {"keywords": ["pricing", "quote", "demo"]}},
)
data = res.json()

Resposta

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Outras edições comuns: { "enabled": false } desativa uma regra sem excluí-la, e { "agent_id": "agOtherAgent" } a move para um Agente diferente. Um corpo vazio retorna 400 com "No fields to update".

Excluir uma regra #

DELETE /entry-points/{entryPointId} — remove a regra permanentemente. Nada mais faz referência a um Ponto de Entrada, portanto, não há nada para desvincular primeiro.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Para impedir que uma regra seja disparada, mas mantê-la, defina enabled como false. Padrões de canal, em particular, são normalmente desativados em vez de excluídos, que é o que DELETE /entry-points/channel-defaults faz.

Verificar se o roteamento está ativo #

GET /entry-points/routing-status — retorna se a hierarquia de Pontos de Entrada decide quem responde nesta conta. Legível com acesso de visualização, para que um membro da equipe veja a mesma resposta que o proprietário.

curl "https://api.youraiconnector.com/v1/entry-points/routing-status?apiKey=YOUR_API_KEY"

{ "success": true, "cutover_enabled": true }

Atualmente, é true em todas as contas. A chamada é mantida para que uma integração possa verificar antes de informar a alguém que sua alteração de roteamento está ativa, em vez de presumir isso.

As chamadas mais antigas, baseadas em campanhas #

Dois endpoints de antes dos Agentes ainda funcionam para contas organizadas em torno de campanhas. Novas integrações devem usar as chamadas de padrões de canal acima.

• PUT /channel-routing/{channel} com { "campaignId": "cp5NbV8xQrT2wYzA" } — nomeia uma campanha, e o Agente dessa campanha se torna o responsável por responder ao canal. { "campaignId": null } limpa o canal. Uma campanha apenas de saída é rejeitada porque não tem comportamento de entrada a oferecer.
• POST /channel-routing/clear com { "channels": ["whatsapp", "instagram"] } — libera vários canais de qualquer Agente que os responda em uma única chamada, normalmente antes de apontá-los para outro lugar. A resposta lista released_channels, aqueles que realmente tinham um responsável.

Ambos definem como não definido em vez de silenciar: em uma conta com exatamente um Agente ativo, um canal liberado ainda retorna para esse Agente.

Erros da API de Pontos de Entrada #

Os endpoints de Ponto de Entrada retornam o envelope de erro padrão:

{
  "success": false,
  "error": "Entry point not found"
}

Os códigos compartilhados que todo endpoint pode retornar — 401, 403 (seu plano não inclui acesso à API), 429 (limite de taxa) e 500 — estão listados com orientações de nova tentativa em Erros e Paginação.

Próximos passos #

• Pontos de Entrada — o conceito, os tipos de regra e o painel Quem Responde a Novas Conversas no aplicativo.
• API de Agentes de IA — crie e configure os Agentes para os quais essas regras roteiam.
• API de Canais — conecte os próprios canais.
• Automação de Comentário para DM — o que as regras de comentário fazem quando são acionadas.