Conectors — canais externos ligados à base de conhecimento

Os conectors ligam os canais de mensageria onde os seus clientes e colegas já estão — WhatsApp, Telegram, Discord, Slack — à mesma base de conhecimento que alimenta o chat interno. As conversas permanecem nos vossos servidores: a aplicação consulta as APIs do canal com as credenciais que o administrador insere, e as respostas provêm da base documental.

Disponível apenas na edição Enterprise (connectors_enabled: false na licença Community — o painel de administração Community mostra o UpgradePrompt; ver Administration). Referências: packages/shared/src/schemas/connector.schema.ts (os campos do formulário), packages/server/src/routes/connectors.ts (os limites + o router), CHANGELOG.md v0.28.1, packages/shared/src/constants/license.ts. Linhas de proveniência: FACT-CENSUS.md F-CONN-1, F-CONN-2, F-LIC-1.

Criar um conector

Caminho: Settings → Conversations → Connectors (o botão New connector). O formulário exige:

A ligação ao arquivo determina o corpus: cada pergunta que chega do canal atravessa a mesma pipeline RAG dos chats internos (pesquisa híbrida, citação de fontes, síntese) — a resposta citada é devolvida pelo canal de origem.

Editar um conector (v0.28.1)

O cartão do conector no painel de administração tem um menu de overflow com a entrada Edit (a primeira): abre um diálogo pré-preenchido sobre a superfície mutável:

• Mutável via `PUT /api/connectors/:id`: nome, ligação do arquivo, mensagens de boas-vindas/recurso, locale do recurso, rate limit, daily session limit (vazio = null; 0 = ilimitado).
• Imutável por esquema: plataforma, token de bot, workspace. Mudar de canal ou de token = um conector novo.
• O interruptor isEnabled fica no cartão (Switch); o pollMode do Telegram fica nos botões do webhook.
• A PUT registra o evento de auditoria chat_connector.updated (em paridade com o ramo DELETE).

Adaptadores por plataforma

Cada plataforma corre num adaptador dedicado com as suas próprias credenciais de registo:

As credenciais transitam e ficam no servidor; o token secreto nunca aparece na interface depois da criação.

Limites e a mensagem de recurso

O rate limit e o daily session limit protegem o workspace do tráfego externo: 0 = ilimitado; N = o máximo por conector. A mensagem de recurso (com o seu fallback locale configurável) é a resposta quando a pesquisa no corpus não produz elementos citáveis válidos — um canal externo nunca recebe gerações sem fontes quando há um recurso configurado.

Desativação e auditoria

• isEnabled (o Switch do cartão) suspende o encaminhamento sem apagar a configuração.
• O DELETE de um conector é uma ação dedicada e auditada (o evento chat_connector.deleted, em paridade com updated).
• Toda operação de administração sobre conectors acaba no registo de eventos (ver Administration).

Ativação Enterprise sem tocar no servidor

A licença Enterprise aplica-se colando a chave no painel (Settings → Security → License, GET/PUT/DELETE /api/license/instance): verificação probe-first da chave (invalid/expired/plugin_bound/community_tier — uma chave rejeitada nunca persiste), cifra AES-256-GCM em SystemConfig, aplicação em execução via setCachedLicense. Ver API reference; F-LIC-1.

Este guia cobre a superfície operacional dos adaptadores de conectores; a profundidade técnica vive no post gémeo:

• A profundidade técnica

Provenance

---

Referência operacional — Simmetric Chat v0.28.1 (documentos atualizados a 2026-10-02, SHA do census `aca5b8ff`).