Página pública e Widget

O SquadOS oferece dois canais de Web Chat sem login:

• Página pública — um link em https://app.squados.io/a/<endereço> que você compartilha;
• Widget — uma bolha instalada no seu site por um trecho de código.

Os dois são caixas de entrada da organização. Você cria, edita, pausa e exclui cada um em Caixas de entrada. Eles não são o Hub, que atende membros autenticados da organização e não precisa de caixa.

	Página pública	Widget
Acesso normal	Qualquer pessoa com o link	Visitante de um domínio autorizado
Formato	Chat em página inteira	Bolha que abre o chat sobre o site
Endereço	Escolhido por você e editável	Gerado na criação e fixo
Aparência configurável	Não	Ícone, cor e lado da bolha
Quota diária própria	Não	Opcional, para turnos atendidos por IA

Criar a caixa

Você precisa das permissões para editar caixas e agentes.

1. Abra Caixas de entrada e selecione Conectar caixa de entrada.
2. Em Outros canais, escolha Página pública ou Widget.
3. Em Quem atende esta caixa?, escolha um agente ou Atendimento humano e dê um nome à caixa.
4. Configure o canal conforme as seções abaixo e conclua o wizard.

A caixa só é criada ao concluir o fluxo. Se o destino for humano, novas mensagens entram na fila da equipe e a página avisa ao visitante que uma pessoa responderá. Se for um agente, ele precisa estar ativo para o canal ficar disponível. Horários de atendimento podem alternar o destino depois da criação; veja Caixas de entrada.

Página pública

Configuração

• Endereço da página — use de 3 a 64 caracteres: letras minúsculas, números e hífens. O formulário normaliza o nome sugerido e verifica se o endereço já existe antes de salvar.
• Mensagem de boas-vindas (opcional) — aparece no chat antes da primeira mensagem do visitante.
• Permitir envio de arquivos — libera arquivos e imagens quando há um agente na caixa. Em atendimento humano sem agente, o controle fica indisponível. O botão de áudio depende também da configuração multimodal do agente.

O link final é https://app.squados.io/a/<endereço>. Depois de criar a caixa, use Ações → Abrir página para testar ou Ações → Copiar link para compartilhar.

Trocar o endereço quebra o link anterior. Ao editar uma caixa que já tem conversas, o SquadOS mostra esse aviso; quem abrir a URL antiga verá a página indisponível.

Antes de divulgar

1. Abra o link em um navegador sem sessão e envie uma mensagem real.
2. Confirme se a resposta e a mensagem de boas-vindas deixam claro o escopo do atendimento.
3. Teste o caminho humano se a agenda puder transferir conversas para a equipe.
4. Revise guardrails e ferramentas que enviam e-mail, alteram dados ou executam transações. Ter o link significa poder iniciar uma conversa.
5. Acompanhe os primeiros atendimentos em Conversas.

Widget

Domínios permitidos

Informe pelo menos um domínio antes de concluir:

• exemplo.com autoriza somente esse host;
• *.exemplo.com autoriza subdomínios, como www.exemplo.com e loja.exemplo.com, mas não o domínio raiz;
• Liberar qualquer domínio dispensa a lista e deve ser usado somente em um teste controlado.

Não inclua protocolo, caminho ou porta. Para desenvolvimento local, adicione localhost ou 127.0.0.1 explicitamente; o ambiente de produção não os libera automaticamente.

O loader consulta a configuração antes de desenhar a bolha e não a monta quando o domínio não está autorizado. Essa lista reduz instalação indevida, mas não substitui autenticação nem guardrails: o Web Chat continua sendo um canal anônimo. Não exponha dados ou ações sensíveis apenas com base no domínio de origem.

Aparência, mensagem e consumo

• Ícone da bolinha — escolha entre seis ícones.
• Cor de destaque — use uma cor sugerida ou personalizada; ela colore a bolha e os destaques do chat.
• Posição da bolinha — canto inferior direito, por padrão, ou canto inferior esquerdo.
• Mensagem de boas-vindas — aparece quando o visitante abre o chat.
• Quota diária de créditos — limite opcional que recusa novos turnos de IA depois de atingido e volta a contar no dia seguinte. A medição atual soma o consumo de todos os widgets ligados ao mesmo agente, não apenas desta caixa. Caixas com atendimento exclusivamente humano não executam IA e não usam essa quota.
• Permitir envio de arquivos — segue a mesma regra da Página pública: exige um agente; áudio depende também da configuração multimodal dele.

Além da quota, os dois canais anônimos têm limites automáticos por visitante e por conversa. Eles reduzem abuso, mas não tornam seguro conceder ferramentas irrestritas a um agente público.

Instalar

Depois de criar a caixa, selecione Ações → Copiar código de instalação. O código tem este formato:

<!-- SquadOS Widget — Minha caixa -->
<script async src="https://app.squados.io/widget.js" data-agent="minha-caixa-4a5d8010"></script>

Cole-o antes de </body> em todas as páginas autorizadas. data-agent contém o endereço da caixa, gerado a partir do nome mais um sufixo aleatório. Ele não pode ser editado, pois é a referência dos snippets já instalados.

Para testar a tela do chat isoladamente, abra https://app.squados.io/embed/<endereço>. Esse endereço técnico não testa se o domínio do seu site está na lista: valide também o snippet na página onde ele será publicado.

Identificar o visitante (opcional)

Sem integração adicional, a conversa é anônima. Se o seu site já conhece o visitante, envie dados estruturados depois do snippet:

window.SquadOS.identify({
  name: "Maria Silva",
  email: "maria@empresa.com",
  external_id: "usr_8231",
  metadata: { plano: "pro", empresa: "Acme" },
});

Campo	Efeito
name	Atualiza o nome exibido em Conversas; sozinho, não cria um contato identificado.
external_id	Identidade estável preferencial para criar ou vincular o contato na organização.
email	Identidade alternativa quando external_id não é enviado.
metadata	Pares de texto, número ou booleano gravados no contato; não são inseridos automaticamente no prompt do agente.

Você pode chamar identify() antes ou depois de abrir a bolha e repetir a chamada quando o login mudar. Se precisar chamá-lo antes de o arquivo assíncrono carregar, crie a fila primeiro:

<script>
  window.SquadOS = window.SquadOS || {
    q: [],
    identify: function () { this.q.push(arguments); }
  };
  window.SquadOS.identify({ name: "Maria Silva", external_id: "usr_8231" });
</script>
<script async src="https://app.squados.io/widget.js" data-agent="minha-caixa-4a5d8010"></script>

Esses valores vêm do navegador e não são prova de identidade. Não use identify() para autorizar acesso, revelar informação confidencial ou executar ações sensíveis.

Continuidade, edição e pausa

O navegador guarda uma referência e um token secreto por caixa para retomar a conversa e carregar até 200 mensagens do histórico após recarregar. Limpar os dados do navegador ou escolher Nova conversa na Página pública inicia outro atendimento. Não compartilhe nem tente reutilizar IDs ou tokens internos.

Em Caixas de entrada → Editar você pode mudar o nome, a mensagem, anexos, aparência, domínios, quota, horários e opções avançadas. Na Página pública também pode trocar o endereço; no Widget, o endereço permanece fixo.

• Desligue Página no ar ou Widget no ar para interromper o acesso sem apagar o histórico.
• Use Excluir caixa apenas para remoção definitiva. O menu genérico pode mencionar “desconectar”, mas Página pública e Widget são pausados pelos controles no ar.

Se a página ou a bolha não responder, confira nesta ordem: caixa no ar, agente ativo ou destino humano válido, domínio autorizado no Widget, saldo/créditos, quota diária e erros do navegador. No Widget, teste o snippet no domínio real; abrir somente /embed/ não valida a instalação.