Depois de carregado, o widget expõe o objeto global window.RagionWidget para controlar o chat programaticamente e reagir a eventos da conversa.
| Método | Descrição |
|---|---|
| RagionWidget.init(config) | Inicializa o widget. Destrói a instância anterior, se houver |
| RagionWidget.open() | Abre o painel do chat |
| RagionWidget.close() | Fecha o painel do chat |
| RagionWidget.toggle() | Alterna entre aberto e fechado |
| RagionWidget.preload() | Pré-monta o painel antes do primeiro clique (elimina o delay inicial) |
| RagionWidget.updateConfig(partial) | Atualiza qualquer parte da configuração em runtime, sem recriar o widget |
| RagionWidget.destroy() | Remove o widget da página por completo |
| RagionWidget.isOpen() | Retorna boolean indicando se o painel está aberto |
| RagionWidget.version | Versão do bundle (string) |
<button onclick="RagionWidget.open()">Fale com o assistente</button>updateConfig aceita qualquer subconjunto da configuração — útil para trocar tema, textos ou cores sem recriar o widget:
// Trocar para o tema escuro quando o site mudar de tema
RagionWidget.updateConfig({ theme: "dark" });
// Trocar título e cor de destaque
RagionWidget.updateConfig({
texts: { title: "Suporte Premium" },
appearance: { accentColor: "#7c3aed" },
});Passe os callbacks em RagionWidget.init({ callbacks: { ... } }) para acompanhar o ciclo de vida do chat:
| Callback | Quando dispara |
|---|---|
| ready() | Widget montado e pronto para uso |
| open() | Painel foi aberto |
| close() | Painel foi fechado |
| messageSent({ message, retry }) | Usuário enviou uma mensagem (retry indica reenvio após erro) |
| firstChunk({ message, firstChunkMs }) | Primeiro trecho da resposta chegou (latência em ms) |
| chunk({ chunk }) | Cada trecho recebido durante o streaming |
| complete({ message, response, totalMs, firstChunkMs }) | Resposta completa, com texto final e métricas de tempo |
| error({ message, error }) | Falha ao responder (timeout, rede, API key inválida etc.) |
<script>
RagionWidget.init({
apiKey: "rg_xxx",
callbacks: {
ready: () => console.log("widget pronto"),
open: () => console.log("chat aberto"),
close: () => console.log("chat fechado"),
messageSent: ({ message, retry }) => {
console.log(retry ? "reenvio:" : "mensagem:", message);
},
firstChunk: ({ firstChunkMs }) => {
console.log("primeira resposta em", firstChunkMs, "ms");
},
complete: ({ response, totalMs }) => {
console.log("resposta completa em", totalMs, "ms:", response);
},
error: ({ error }) => console.error("erro no chat:", error),
},
});
</script>RagionWidget.init({
apiKey: "rg_xxx",
callbacks: {
open: () => analytics.track("widget_opened"),
messageSent: ({ message }) => analytics.track("widget_message", { length: message.length }),
complete: ({ totalMs, firstChunkMs }) =>
analytics.track("widget_response", { totalMs, firstChunkMs }),
error: ({ error }) => analytics.track("widget_error", { error }),
},
});Performance percebida
Chame RagionWidget.preload() em páginas onde o uso do chat é provável — o painel abre instantaneamente.
SPAs
Chame RagionWidget.destroy() ao desmontar a aplicação ou ao navegar para rotas onde o chat não deve aparecer.
Depuração
Ative behavior.debug: true para logar todos os eventos do widget no console durante o desenvolvimento.
Aguarde o carregamento
Com defer, chame init dentro de window.addEventListener("load", ...) para garantir que o script já foi carregado.