Há duas formas de configurar o widget: data-attributes na própria tag do script (rápido, sem JavaScript) ou a API programática RagionWidget.init() (controle total).
Ideal para personalizações simples. Adicione os atributos direto na tag do script:
<script
src="https://widget.kevinkvn.com.br/ragion-widget.js"
data-api-key="rg_xxx"
data-position="bottom-right"
data-theme="auto"
data-title="Assistente virtual"
data-welcome-message="Olá! Como posso ajudar?"
data-accent-color="#4f6357"
defer
></script>| Atributo | Descrição |
|---|---|
| data-api-key | Obrigatório. API key do Ragion (rg_...) |
| data-backend-url | Opcional. Sobrescreve a URL padrão do backend embutida no bundle |
| data-position | bottom-right (padrão), bottom-left, top-right, top-left |
| data-theme | auto (padrão, segue o tema do SO), light, dark |
| data-preset | minimal-dark, minimal-light, warm-neutral |
| data-title | Título exibido no header do chat |
| data-welcome-message | Mensagem de boas-vindas (suporta Markdown) |
| data-accent-color | Cor de destaque (ex.: #4f6357) |
Para configurar textos, layout, comportamento e callbacks, carregue o script sem data-api-key e chame RagionWidget.init():
<script src="https://widget.kevinkvn.com.br/ragion-widget.js" defer></script>
<script>
window.addEventListener("load", () => {
RagionWidget.init({
apiKey: "rg_xxx",
position: "bottom-right",
theme: "auto", // "auto" | "light" | "dark"
preset: "minimal-dark", // opcional; sem preset, o theme decide
zIndex: 999999,
layout: { /* ver tabela abaixo */ },
texts: { /* ver tabela abaixo */ },
appearance: { /* ver página Aparência e Temas */ },
behavior: { /* ver tabela abaixo */ },
callbacks: { /* ver página API e Eventos */ },
});
});
</script>apiKey. Os valores não informados usam os padrões das tabelas abaixo.layout — dimensões e responsividade| Opção | Padrão | Descrição |
|---|---|---|
| buttonSize | 54 | Tamanho do botão flutuante (px) |
| panelWidth | 380 | Largura do painel (px) |
| panelHeight | 600 | Altura do painel (px) |
| mobileBreakpoint | 520 | Largura de tela (px) abaixo da qual o modo mobile é ativado |
| fullscreenOnMobile | true | Painel ocupa a tela inteira no mobile |
texts — todos os textos do widgetCada texto exibido no widget pode ser trocado — útil para outros idiomas ou tom de voz da marca:
| Opção | Padrão | Descrição |
|---|---|---|
| title | "Assistente virtual" | Título do header |
| statusText | "Conectado" | Status exibido sob o título |
| statusStreamingText | "Respondendo" | Status durante o streaming |
| statusErrorText | "Falha ao responder" | Status em caso de erro |
| welcomeMessage | "" | Mensagem inicial do assistente (suporta Markdown) |
| emptyTitle | "Comece uma conversa" | Título do estado vazio |
| emptyDescription | "Envie uma mensagem..." | Descrição do estado vazio |
| emptyHints | [] | Lista de dicas exibidas no estado vazio |
| inputPlaceholder | "Digite sua mensagem" | Placeholder do campo |
| suggestions | [] | Sugestões clicáveis exibidas antes da primeira mensagem |
| launcherOpenLabel / launcherCloseLabel | "Abrir chat" / "Fechar chat" | Acessibilidade do botão flutuante |
| sendLabel / cancelLabel / retryLabel | "Enviar" / "Cancelar" / "Tentar novamente" | Rótulos das ações |
| copyLabel / copiedLabel | "Copiar" / "Copiado" | Botão de copiar resposta |
<script>
RagionWidget.init({
apiKey: "rg_xxx",
texts: {
title: "Suporte Acme",
welcomeMessage: "Olá! Sou o assistente da **Acme**. Como posso ajudar?",
emptyHints: ["Faça perguntas diretas", "A conversa continua na mesma sessão"],
suggestions: ["Quais são os planos?", "Como funciona o suporte?"],
},
});
</script>behavior — performance e persistência| Opção | Padrão | Descrição |
|---|---|---|
| lazyMount | true | Monta o painel só quando necessário (melhor performance) |
| preloadOnHover | true | Pré-monta o painel ao passar o mouse no botão |
| rememberState | true | Lembra se o chat estava aberto/fechado entre páginas |
| storageMode | "session" | Onde persistir estado: "session" ou "local" |
| persistSession | false | Persiste o sessionId da conversa entre visitas |
| timeout | 30000 | Timeout da requisição (ms) |
| retryAttempts | 1 | Tentativas automáticas em caso de falha |
| retryDelay | 600 | Intervalo entre tentativas (ms) |
| debug | false | Loga eventos do widget no console |
Por conveniência, algumas opções aninhadas também podem ser passadas direto na raiz da config:
| Atalho | Equivale a |
|---|---|
| buttonSize | layout.buttonSize |
| panelWidth / panelHeight | layout.panelWidth / layout.panelHeight |
| timeout | behavior.timeout |
| retryAttempts / retryDelay | behavior.retryAttempts / retryDelay |
| suggestions | texts.suggestions |