API pública e conversa compartilhada

Duas portas de entrada que não passam pela tela do painel: a API pública e o link de conversa compartilhada. Aqui o recorte é o que muda quando a mensagem entra por elas.

Canal API

Como se diferencia do painel

A entrega de eventos para quem chama de fora recebe cuidado especial: quem consome não está num navegador com reconexão automática, então esse fluxo já nasce pensado para esse caso.

Contrato

Uma chamada inicia a execução do agente; uma chamada separada acompanha o andamento por um fluxo de eventos. Ler e continuar uma conversa já em andamento têm seus próprios pontos de entrada.

O que vale registrar aqui: a chave resolve para um par organização e usuário, e as mesmas regras de acesso da organização decidem o resto — o escopo da chave é teto, nunca concessão.

Uma chamada por chave pode representar duas coisas diferentes (22/08/2026). Nem toda chamada autenticada por chave fala em nome de alguém que está ali naquele momento. Numa chave de serviço comum, quem assina é a pessoa dona da chave — que pode estar dormindo enquanto uma rotina agendada dispara em nome dela. Numa chave nascida do vínculo entre a conta de uma pessoa e uma aplicação externa, quem assina é a pessoa que vinculou a própria conta. A plataforma trata os dois casos como canais distintos, e as ferramentas do agente só agem como pessoa no segundo: tratar a chave de serviço como pessoa faria a automação de um terceiro assinar como o dono da chave, e tratar o vínculo como automação é justamente o que o vínculo veio corrigir.

Canal share

O comportamento de produto deste link — dois níveis de visibilidade, um token que identifica o acesso na própria URL, e uma resposta genérica quando o link não existe ou expirou, para não revelar se uma conversa daquele endereço já existiu — é comum a todo compartilhamento por link, não só a este canal. Do ponto de vista de canal, o que importa é:

• É a única porta que atende quem não tem conta na organização.
• Tem conjunto próprio de capacidades — não herda o do painel. Uma pessoa sem conta interagindo com o agente não deve alcançar as mesmas ferramentas de quem é membro.
• Mensagem que entra por ali fica marcada, de modo que o histórico distinga membro autenticado de visitante com link.

O ponto comum dos canais programáticos

Os três caminhos sem sessão (API, webhook do agente, share) compartilham o mesmo desenho:

1. Autenticação própria, sem cookie.
2. Conjunto de capacidades definido pelo canal, não pelo agente sozinho.
3. Convergência para a mesma conversa e o mesmo motor — o canal muda a porta, não o que acontece depois.

A segunda propriedade é a que mais se esquece: ligar uma capacidade no agente não a habilita em todo canal. A capacidade efetiva é a conjunção entre o que está ligado no agente e o que aquele canal permite.