O adapter contract dos conectores: canais e limites

Os canais onde os seus clientes já estão

Um workspace AI é mais útil onde a conversa acontece de qualquer forma. Para muitas organizações, esse lugar não é a interface web que vocês implantam; são os canais de mensagens que as pessoas abrem sem pensar - os grupos de WhatsApp, as conversas de Telegram, os servidores de Discord, os espaços de Slack. O Simmetric Chat trata esses canais como superfícies de primeira classe da mesma base de conhecimento: um conector vincula um canal a um workspace e a um arquivo documental, e cada pergunta que chega por esse canal é respondida pela mesma pipeline de retrieval do chat interno.

A palavra do título - adapter contract - nomeia a regra de projeto que torna isso seguro. Cada plataforma fala um protocolo diferente com semânticas de credenciais diferentes; cada uma corre atrás de um adapter dedicado, e tudo o que o adapter compartilha é um vocabulário fixo de campos e limites. O resultado lê-se como uma política de segurança: um conector por canal, um binding por conector, um corpus por binding.

Este artigo percorre o contract do lado do operador: o que você configura ao criar um conector, quais superfícies mudam na era v0.28 (o ramo de edição), como os limites protegem o workspace do tráfego externo e o que acontece quando o corpus não tem resposta citável.

Somente edição Enterprise: connectors_enabled é false na licença Community, a registry de adapters está vazia aí e o painel admin mostra o aviso de upgrade em vez do formulário. O fato: FACT-CENSUS.md F-CONN-1.

O que você configura ao criar

O formulário de criação vive em Settings → Conversations → Connectors e pede duas classes de campos. Os campos de binding nomeiam a integração: um name que identifica a instância, a platform (uma entre telegram, discord, slack, whatsapp), o token secreto do canal e o workspace que ele atende. Os campos de comportamento dão forma à conversa: o binding do arquivo documental que determina o corpus, a mensagem de boas-vindas para quem abre a conversa, a mensagem de fallback com a sua fallbackLocale quando a busca não produz fontes citáveis, e os dois limites - rate limit e sessões diárias, onde 0 significa ilimitado.

Três desses campos imutáveis depois da criação, e essa imutabilidade não é um detalhe de implementação - é o modelo de confiança. A plataforma e o token secreto definem quem pode falar com o corpus; o workspace define o que ele alcança. Se qualquer um mudar, a identidade da integração muda, e o contract responde com um conector novo em vez de uma mutação. O schema da série v0.28 carrega essas regras à letra: as mensagens de boas-vindas e de fallback capam em 4000 caracteres, plataforma e token são create-only, e a PUT nunca os toca.

As credenciais ficam do lado do servidor por projeto. A app chama as APIs do canal com as credenciais que o administrador forneceu; o token secreto nunca volta a aparecer na interface depois da criação, e o routing do conector vive na sua própria infraestrutura - o canal fala com o seu servidor, o seu servidor fala com a sua base de conhecimento.

A camada de adapters

Cada plataforma corre atrás de um adapter dedicado, e o registro de cada um corresponde ao que a plataforma realmente exige:

• Telegram - um bot token de @BotFather, com suporte ao polling e ao webhook (o cartão traz os botões do modo).
• Discord - um bot token do Developer Portal mais os intents de mensagem; o adapter lê os canais em que o bot é autorizado.
• Slack - um bot token e o signing secret da app Slack; os eventos de mensagem chegam pelo webhook configurado.
• WhatsApp - o token secreto da Business API do provedor; o adapter chama a API do provedor.

A camada de adapters é onde morrem as diferenças entre plataformas. Verificação de webhook, escopo de intents, laços de polling, normalização do formato das mensagens - tudo vive atrás do adapter da sua plataforma, e o resto do produto vê uma única forma de registro de conector. A registry de adapters está gated: na Community está vazia por construção, então uma instância Community falha fechada antes de um tráfego externo alcançar o workspace.

Edição: a superfície mutável da v0.28.1

Antes da v0.28.1, ajustar um conector significava apagá-lo e recriá-lo. As mudanças da série v0.28 acrescentam um ramo de edição: o menu de overflow do cartão traz o item Edit que abre um diálogo pre-carregado sobre exatamente a superfície mutável - via PUT /api/connectors/:id:

• Mutável - o nome, o binding do arquivo, as mensagens de boas-vindas e de fallback, a fallback locale e os dois limites (vazio = null; 0 = ilimitado).
• Imutável - a plataforma, o bot token, o workspace.

A chave isEnabled fica no cartão (suspende o routing sem apagar a configuração), e a mutação é auditada como toda ação admin: o endpoint registra o evento chat_connector.updated, em paridade com o ramo DELETE e o seu chat_connector.deleted. O ramo de edição importa para a história do operador por razão concreta: religar o canal a um arquivo reconstruído, ou apertar um limite depois de um incidente, já não custa a identidade do conector.

O caminho da resposta e o fallback

Toda pergunta que chega de um canal passa pela mesma pipeline de um chat interno: busca híbrida no arquivo vinculado, citação das fontes, síntese - e a resposta citada volta pelo canal de origem. O binding do arquivo é o núcleo silencioso do contract: o que torna fundada uma conversação externa.

Quando a busca não produz elementos citáveis válidos, a resposta do contract é a mensagem de fallback - uma resposta configurada na fallbackLocale configurada. Um canal externo nunca recebe uma geração sem fundamento com o fallback em pé; o visitante lê o fallback em vez de uma afirmação segura sem nada por trás.

Os limites como eclusa do workspace

O rate limit e o daily session limit são a proteção do contract contra o tráfego externo:

• 0 = ilimitado (o valor sentinela do router).
• N = o máximo por conector para as requisições, e para as sessões por dia.

Junto com isEnabled, deixam expor a base de conhecimento a um canal público mantendo o raio de ação limitado: um bot fora de controle, um canal raspado ou uma audiência inesperada consome no máximo a parte configurada do workspace. Desativar, apertar ou religar - cada um é agora uma edição única (o ramo v0.28.1), sem recriação.

Para continuar

A guia leva o procedimento completo do operador - o formulário campo por campo, a tabela de adapters por plataforma, o comportamento de audit - em /pt/docs/connectors:

• Conectores - a guia
• Fatos deste post: linhas FACT-CENSUS.md F-CONN-1 (a barreira de edição), F-CONN-2 (o ramo de edição v0.28.1), F-LIC-1 (a ativação colando a chave - sem tocar no servidor)

Provenance: pacotes Simmetric Chat connector.schema.ts (formas dos campos + limites), routes/connectors.ts (o router + o limiter), CHANGELOG.md v0.28.1, license.ts (connectors_enabled) no estado documental fixado pelo census v0.28.1 (SHA aca5b8ff).