API de Pontos de Entrada #

Um Ponto de Entrada é uma regra de encaminhamento: “quando isto acontece neste canal, entregue a conversa a este Agente”. Ligar um canal faz com que as mensagens cheguem à conta e criar um Agente dá-lhe algo que pode responder, mas nenhum dos dois decide quem responde à primeira mensagem de um desconhecido. Os Pontos de Entrada fazem-no. Para o produto em si, consulte o guia de Pontos de Entrada.

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

Todos os exemplos abaixo mostram o formato de consulta ?apiKey= em cURL e o cabeçalho X-API-Key em JavaScript e Python — qualquer um funciona em todos os endpoints.

No explorador da API. Todos os endpoints nesta página estão na especificação OpenAPI publicada, pelo que pode consultar os seus campos exatos e executar pedidos em tempo real no explorador da API.

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

Ligue 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”. Tudo o resto nesta página serve para regras mais específicas (palavras-chave, comentários, novos seguidores), vários números num único canal e para ler o que está configurado.

Como é decidido o encaminhamento #

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

1. Um humano assumiu o controlo da conversa — sem IA.
2. O contacto já está atribuído a um Agente, manualmente ou porque uma conversa com esse Agente está em curso — o mesmo Agente mantém-na. Os Pontos de Entrada nunca movem uma conversa existente; para entregar um chat a um Agente diferente, atribua-o (na aplicação ou com a ação Automações).
3. O contacto está a responder a uma difusão — o Agente da difusão responde, ou ninguém se a difusão não tiver nenhum.
4. Um Ponto de Entrada específico corresponde. As regras de palavras-chave superam as regras de comentários, que superam as regras de seguidores. Entre duas regras do mesmo tipo, ganha a que foi atualizada mais recentemente.
5. O padrão do canal para o canal onde a mensagem chegou. Um padrão limitado ao número específico para o qual o contacto escreveu supera o padrão de todo o canal.
6. Nada correspondeu — a mensagem cai na caixa de entrada da sua equipa e nenhum assistente responde.

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

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

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 num canal sem predefinição de canal também funciona como um filtro: as mensagens que não correspondem a nenhuma das palavras-chave não recebem resposta automática e vão simplesmente para a sua caixa de entrada, mesmo numa conta com um único Agente.

Direcionar um canal para um Agente #

PUT /entry-points/channel-defaults — torna um Agente o responsável por responder a novos contactos num canal. Qualquer outro Agente atualmente definido como predefinição desse canal é removido na mesma chamada, pelo que um canal tem sempre exatamente um responsável pelas respostas. Definir o Agente que já é a predefiniçã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 dar lugar a esta (vazio quando não havia nada para substituir). Apenas os contactos com quem nunca falou são afetados — qualquer pessoa que já esteja numa conversa com um Agente mantém esse Agente.

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

Ver quem responde a cada canal #

GET /entry-points/channel-defaults — predefinição de todos os canais na conta, do mais recente para o mais antigo, incluindo os desativados (enabled: false) e um canal deliberadamente definido como ninguém (agent_id: ""). Filtre por enabled para obter a imagem 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 ao nível da conta. Listar as regras de um Agente com GET /agents/{agentId}/entry-points não permite mostrar um canal definido como ninguém, porque essa regra não pertence a nenhum Agente.

Sair de um canal sem ninguém a responder #

DELETE /entry-points/channel-defaults?channel=instagram — desativa a predefinição de todo o canal para um canal específico. O canal é nomeado como um parâmetro de consulta, não no corpo. Adicione &phone_number=%2B31685101091 para limpar apenas a predefinição desse número e permitir que o número volte para quem responder 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 predefinição é um 200 com uma lista vazia. Limpar significa remover a definição, não silenciar — numa conta com exatamente um Agente ativo, um canal não configurado continua a recorrer a esse Agente. Para manter a IA totalmente fora de um canal, selecione Ninguém responde no painel Quem responde a novas conversas da aplicação (isso escreve uma predefinição explícita de “ninguém” que o recurso nunca substitui), ou pause o Agente com PATCH /agents/{agentId}/active.

Um Agente por número de WhatsApp #

O encaminhamento é por canal, por predefinição: todos os seus números de WhatsApp partilham um responsável pelas respostas. Com dois ou mais números ligados no WhatsApp Business ou WhatsApp Web, uma predefinição pode ser limitada a um único número, para que uma empresa com um número por sucursal ou marca possa atribuir a cada um o 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 tem de ser um dos seus números ligados nesse canal, escrito tal como aparece em números ligados (E.164 com o +); qualquer outra coisa é um 400.
• A regra é guardada como predefinição de canal com match_config.phone_numbers: ["+31685101091"]. Uma mensagem que chegue a esse número vai para o seu Agente; todos os outros números continuam a seguir a predefinição de todo o canal.
• Definir ou limpar a predefinição de todo o canal não altera as regras específicas de cada 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 saem sempre do número para o qual o contacto escreveu, para que o contacto continue a falar 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 uma predefinição de canal, embora PUT /entry-points/channel-defaults seja a melhor opção para isso, pois retira o responsável anterior por si). O Agente no caminho ganha sempre: uma regra nunca pode ser criada para um Agente diferente daquele que está no 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 mensagem direta (DM) que apenas reage a comentários que digam “LINK” em duas publicações 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 uma DM a todos os que comentarem nas publicações monitorizadas, e post_ids vazio para monitorizar todas as publicações. Um 400 indica 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 o 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: as suas predefinições de canal, regras de palavra-chave, regras de comentário e regras de seguidor. As regras retiradas também regressam, 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 está a alterar; as definições aninhadas podem ser endereçadas folha a folha com uma chave pontuada, como "match_config.keywords". Sempre que a alteração toca em type, channels ou match_config, a regra completa é reavaliada, pelo que uma edição parcial nunca pode deixar uma regra inutilizável (mudar type para keyword sem fornecer palavras-chave é rejeitado). Enviar agent_id entrega a regra a outro dos seus Agentes; uma regra em branco é rejeitada. Os 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 } retira uma regra sem a eliminar, e { "agent_id": "agOtherAgent" } move-a para um Agente diferente. Um corpo vazio devolve 400 com "No fields to update".

Eliminar uma regra #

DELETE /entry-points/{entryPointId} — remove a regra permanentemente. Nada mais faz referência a um Ponto de Entrada, por isso não há nada para destacar 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 ativada, mas mantê-la guardada, defina enabled como false. As predefinições de canal, em particular, são normalmente retiradas em vez de eliminadas, que é o que DELETE /entry-points/channel-defaults faz.

Verificar se o encaminhamento está ativo #

GET /entry-points/routing-status — devolve se a hierarquia de Pontos de Entrada decide quem responde nesta conta. Legível com acesso de visualização, para que um membro da equipa 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 alguém de que a sua alteração de encaminhamento está ativa, em vez de assumir que está.

As chamadas mais antigas, em forma de campanha #

Dois endpoints de antes dos Agentes continuam a funcionar para contas organizadas em torno de campanhas. As novas integrações devem utilizar as chamadas de predefinições de canal acima.

• PUT /channel-routing/{channel} com { "campaignId": "cp5NbV8xQrT2wYzA" } — nomeia uma campanha e o Agente dessa campanha torna-se 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 para oferecer.
• POST /channel-routing/clear com { "channels": ["whatsapp", "instagram"] } — liberta vários canais do Agente que lhes responde numa única chamada, normalmente antes de os direcionar para outro local. A resposta lista released_channels, aqueles que tinham efetivamente um responsável por responder.

Ambos anulam a definição em vez de silenciar: numa conta com exatamente um Agente ativo, um canal libertado continua a recorrer a esse Agente.

Erros da API de Pontos de Entrada #

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

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

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

Próximos passos #

• Pontos de Entrada — o conceito, os tipos de regras e o painel Quem Responde a Novas Conversas na aplicação.
• API de Agentes de IA — crie e configure os Agentes para os quais estas regras encaminham.
• API de Canais — ligue os próprios canais.
• Automação de Comentário para DM — o que as regras de comentário fazem assim que são acionadas.