Widget web

Nomes técnicos como window.SingChat fazem parte do widget e da API. Mantenha-os exatamente como estão no seu código.

O widget web é um único script, widget.js, servido a partir de askais.com. Ele adiciona um botão de chat às suas páginas e desenha a janela do chat dentro de um Shadow DOM, para que os estilos do seu site e os do widget não se misturem.

Adicione ao seu site

Cole isto antes de </body> em todas as páginas onde o chat deve aparecer. Seu App ID fica em Configurações → Caixas de entrada.

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  async></script>

O data-base-url é obrigatório no seu próprio site: sem ele, o widget procura o servidor no seu domínio em vez de askais.com.

⚠️ Carregue o widget.js a partir de askais.com

Não baixe o widget.js nem o inclua no seu próprio código. Carregado a partir de askais.com, ele sempre roda a versão atual; uma cópia fica congelada e perde todas as correções e novos recursos.

Atributos do script

Tudo é configurado com atributos data- na tag script:

• data-app-id — Obrigatório. O App ID da sua caixa de entrada.
• data-base-url — Obrigatório no seu site. Sempre https://askais.com.
• data-locale — Opcional. Força o idioma do widget, por exemplo ja ou zh-Hant. Sem ele, o widget segue o idioma do dispositivo do visitante e, depois, o lang da sua página.
• data-external-id — O ID que você usa para um usuário logado.
• data-email — O e-mail do usuário, mostrado à sua equipe.
• data-name — O nome do usuário, mostrado à sua equipe.
• data-avatar-url — Link para a foto de perfil do usuário.
• data-hmac — Assinatura de identidade; veja abaixo.
• data-attrs — Detalhes extras em JSON, por exemplo {"plan":"Pro"}, mostrados à sua equipe no perfil do visitante. JSON inválido é ignorado.

data-embed, data-platform, data-app-version e data-device-model são definidos pela página de chat no app. Veja Chat no app (WebView).

Visitantes logados

Para um usuário logado, adicione os dados dele à tag script. Sua equipe vê com quem está falando, e o chat acompanha o usuário em outros dispositivos:

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  data-external-id="user_123"
  data-email="ada@example.com"
  data-name="Ada Lovelace"
  data-attrs='{"plan":"Pro"}'
  data-hmac="SIGNATURE_FROM_YOUR_SERVER"
  async></script>

Sem data-external-id, o widget dá a cada navegador um ID anônimo próprio, guardado no armazenamento local do navegador, para que o histórico do chat sobreviva a recarregamentos de página nesse navegador. Se a caixa de entrada tiver um formulário pré-chat, os visitantes anônimos o preenchem antes de o chat começar.

Identidade verificada (HMAC)

• hmac é o HMAC-SHA256 do externalId, usando como chave a chave secreta da caixa de entrada, escrito em hexadecimal minúsculo.
• Calcule-o no seu servidor. A chave secreta nunca vai para uma página ou um app.
• A chave secreta aparece uma vez quando você cria a caixa de entrada e de novo quando você a rotaciona em Configurações → Caixas de entrada. Rotacioná-la invalida todas as assinaturas antigas.
• Sempre envie data-external-id junto com data-hmac. A assinatura é verificada em relação ao ID externo, então uma assinatura feita só sobre o e-mail é rejeitada.
• Com uma assinatura errada, o widget não consegue se conectar. Sem data-hmac, os dados são aceitos como a página os informa, então qualquer pessoa que consiga alterar a página poderia se passar por outra pessoa.

Exemplo para Node.js:

import { createHmac } from "node:crypto";

// Runs on your server. INBOX_SECRET_KEY never leaves it.
const hmac = createHmac("sha256", INBOX_SECRET_KEY)
  .update(user.id) // the exact value you pass as data-external-id
  .digest("hex");

Como iniciar o widget pelo JavaScript

Para iniciar o widget você mesmo, por exemplo quando sua página já sabe quem é o usuário, carregue o script sem data-app-id e chame window.SingChat.start() depois que ele carregar:

<script src="https://askais.com/widget.js"></script>
<script>
  window.SingChat.start({
    appId: "YOUR_APP_ID",
    baseUrl: "https://askais.com",
    // optional, for a signed-in user:
    externalId: "user_123",
    email: "ada@example.com",
    name: "Ada Lovelace",
    hmac: "SIGNATURE_FROM_YOUR_SERVER",
  });
</script>

start() é o único método que o script oferece. Não há métodos para abrir, fechar ou escutar eventos do widget; os visitantes o abrem pelo botão de chat.

Aparência e comportamento

• Configurações → Caixas de entrada e, em seguida, expanda uma caixa de entrada: cor principal e cor do texto, posição (canto inferior direito ou inferior esquerdo), tamanho da bolha, fundo claro ou escuro, título e subtítulo da janela, com uma pré-visualização ao vivo.
• Formulário pré-chat (no mesmo lugar): peça aos visitantes anônimos e-mail, nome, telefone ou empresa antes de o chat começar.
• Origens permitidas (no mesmo lugar): os sites que podem carregar o widget desta caixa de entrada. Uma lista vazia permite qualquer site.
• Marca do widget (no mesmo lugar): a linha “Powered by” na parte de baixo do chat. Se você pode ocultá-la ou mostrar seu próprio nome ali depende do seu plano.
• A mensagem de boas-vindas da IA é definida em Agente de IA, as bolhas clicáveis de FAQ em Configurações → Perguntas frequentes e os artigos em Help Center.

Segurança

• O App ID é público e pode ficar no seu HTML com segurança.
• A chave secreta da caixa de entrada fica apenas no seu servidor.
• Use a identidade verificada (HMAC) sempre que a página souber quem é o usuário.
• Limite as origens permitidas aos seus próprios domínios para que o widget não possa ser carregado em outros sites.