> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suasofia.online/llms.txt
> Use this file to discover all available pages before exploring further.
# Widget Web
> Incorpore seu assistente de IA em seu website com recursos de voz e chat
Adicione seu assistente de IA a qualquer website com um widget personalizável que suporta chamadas de voz, chat de texto ou ambos.
## Visão Geral
O Widget Web permite que visitantes do site interajam com seu assistente de IA diretamente através de:
* **Conversas por voz:** Chamadas de voz em tempo real no navegador
* **Chat de texto:** Interface de mensagens para interações baseadas em texto
* **Modo híbrido:** Alternância perfeita entre voz e chat
## Acessando a Configuração do Widget
1. Navegue para a página de edição do seu assistente
2. Clique no botão **"Widget web"** (cor amarela/warning)
3. O painel de configuração do widget abre com visualização ao vivo
O Widget Web é um recurso premium. Certifique-se de que seu plano inclui acesso ao widget web antes da configuração.
## Modos do Widget
Escolha como os visitantes interagem com seu assistente:
### Voz & Chat (Recomendado)
Os usuários podem alternar perfeitamente entre voz e texto durante as conversas.
**Melhor para:**
* Máxima flexibilidade para usuários
* Acessibilidade (voz para mobile, chat para ambientes silenciosos)
* Interações complexas que requerem ambos os modos
### Apenas Chat
Interface de mensagens baseada apenas em texto.
**Melhor para:**
* Suporte ao cliente e FAQs
* Ambientes onde voz não é apropriada
* Captura de leads e formulários de qualificação
### Apenas Voz
Conversas de voz em tempo real apenas.
**Melhor para:**
* Experiência similar a telefone no website
* Casos de uso que priorizam voz
* Interações mãos-livres
## Opções de Configuração
### Aba Geral
**Modo do Widget:** Voz, Chat ou Voz & Chat
**Tamanho do Widget:** Escolha entre layout padrão ou **extra grande**
* **Padrão**: Widget flutuante compacto adequado para a maioria dos casos de uso
* **Extra Grande**: Painel de meio da tela no desktop, tela cheia no mobile — ideal para conversas detalhadas
**Posição:** Escolha entre 8 posições (inferior-direita, inferior-esquerda, inferior-centro, meio-direita, meio-esquerda, superior-direita, superior-esquerda, superior-centro)
**Cor Primária:** Cor da marca para botões e acentos
**Tamanho do Botão de Alternância:** Pequeno ou Normal
**Estilo do Botão de Alternância:** Animado (glass morphism) ou Simples (design plano)
**Abrir Automaticamente no Carregamento da Página:** Quando habilitado, o widget expande automaticamente quando a página carrega — nenhum clique é necessário do visitante.
### Aba Botão
**Avatar Personalizado:** Faça upload da sua própria imagem de avatar para substituir o ícone padrão do widget. Aparece no botão de alternância e no cabeçalho do chat. Tamanho máximo: 512KB, proporção 1:1 (quadrado).
**Texto Principal do Botão** (padrão: "Precisa de ajuda?") — texto principal no botão do widget
**Texto Secundário do Botão** (padrão: "Converse conosco") — texto secundário, oculto quando usando tamanho pequeno do botão
**Rótulos das Abas (apenas modo Voz & Chat):**
* Rótulo da Aba Voz (padrão: "Voz") — renomeie para corresponder à linguagem da sua marca (ex: "Ligue", "Fale")
* Rótulo da Aba Chat (padrão: "Chat") — renomeie para corresponder à linguagem da sua marca (ex: "Mensagem", "Texto")
### Aba Cabeçalho & Modal
**Título do Cabeçalho** (padrão: "Assistente IA")
**Subtítulo do Cabeçalho** (padrão: "Pronto para te ajudar ✨")
**Título do Modal** (padrão: "Pronto para conversar?")
**Texto do Botão Iniciar** (padrão: "Iniciar Chat de Voz")
**Descrição do Modal** (padrão: "Clique abaixo para iniciar sua conversa")
### Aba Configurações de Chat
Esta aba só é visível quando o modo do widget inclui chat (Apenas Chat ou Voz & Chat).
**Placeholder do Chat** (padrão: "Digite sua mensagem...")
**Rótulo do Botão Enviar** (padrão: "Enviar mensagem") — rótulo de acessibilidade para o botão enviar
**Mostrar Chamadas de Função:** Quando desabilitado (padrão), chamadas de ferramentas LLM (ex: consultas de calendário, consultas de base de conhecimento) são ocultadas do chat, mantendo a conversa limpa para usuários finais. Habilite para mostrar detalhes de uso de ferramentas.
### Links Clicáveis no Chat
O widget de chat suporta **formatação markdown**, então seu assistente de IA pode enviar links clicáveis, texto em negrito, listas, e mais.
Para incluir URLs clicáveis em mensagens de chat, use o formato de link markdown no prompt ou mensagem inicial do seu assistente:
```
Confira nossas [últimas ofertas](https://example.com/offers) ou visite nosso [centro de ajuda](https://example.com/help).
```
Adicione uma instrução ao prompt do seu assistente como: *"Ao compartilhar links ou URLs, sempre formate-os como links markdown clicáveis: [texto do link](url)"* — isso garante que a IA consistentemente produza links clicáveis ao invés de URLs em texto simples.
### Aba Configurações de Voz
Esta aba só é visível quando o modo do widget inclui voz (Apenas Voz ou Voz & Chat).
**Texto de Conectando** (padrão: "Conectando...")
**Texto de Desconectar** (padrão: "Desconectar")
**Texto de Erro** (padrão: "Conexão falhada. Por favor, tente novamente.")
### Formulário Pré-Chat
Colete informações antes de iniciar conversas:
**Configuração do Formulário:**
* Título do Pré-formulário (padrão: "Antes de começarmos...")
* Descrição do Pré-formulário (padrão: "Por favor, forneça algumas informações para nos ajudar a te atender melhor")
* Texto do Botão Enviar (padrão: "Continuar")
**Campos do Formulário:**
Adicione campos personalizados para coletar dados:
* **Nome da Variável:** Nome interno da variável (mapeia para variáveis do assistente). Apenas letras, números, hífens e sublinhados permitidos.
* **Rótulo do Campo:** Rótulo de exibição mostrado aos usuários
* **Tipo de Campo:** Texto, Email, Telefone, ou Textarea
* **Obrigatório:** Torna o campo obrigatório
* **Placeholder:** Texto placeholder mostrado no campo
* **Texto de Ajuda:** Descrição opcional abaixo do campo
**Mapeamento de Variáveis:**
Nomes dos campos do formulário mapeiam automaticamente para as variáveis do seu assistente, tornando os dados coletados disponíveis durante as conversas.
**Exemplo de Campos do Formulário:**
```
Nome: Nome Completo (obrigatório, texto)
Email: Endereço de Email (obrigatório, email)
Empresa: Nome da Empresa (opcional, texto)
Mensagem: Como podemos ajudar? (opcional, textarea)
```
### Configurações de Resposta da IA
**IA Habilitada:** Quando ativado (padrão), o assistente de IA responde automaticamente às mensagens recebidas. Desative isso se quiser usar o widget apenas para conversas manuais — mensagens são coletadas mas a IA não responde.
### Webhook de Conversa
**URL do Webhook:** Digite uma URL para receber uma notificação webhook sempre que uma nova conversa iniciar via widget. Use isso para acionar fluxos de automação, registrar eventos no seu CRM, ou notificar sua equipe em tempo real.
### Exibição do Widget
**Habilitar Widget:** Alternância principal que controla se o widget carrega em seu website. Quando desabilitado, o widget não aparecerá mesmo que o script de incorporação esteja instalado no seu site. Use isso para ocultar temporariamente o widget sem remover código do seu website.
## Visualização ao Vivo do Widget
No topo do painel de configuração, uma visualização ao vivo mostra exatamente como seu widget irá parecer e se comportar em um website. A visualização atualiza em tempo real conforme você altera qualquer configuração.
**Copiar URL da Visualização** — copia a URL da visualização para sua área de transferência para que você possa abri-la em uma aba separada do navegador ou compartilhá-la com sua equipe para revisão.
**Redefinir Dados** — limpa todo histórico de conversa armazenado, envios de formulários e preferências na visualização. Use isso para simular a experiência de um visitante inicial após testes.
A visualização é totalmente interativa — você pode clicar no botão do widget, preencher o formulário pré-chat, e iniciar uma conversa real para testar sua configuração antes de implantar.
### Código de Incorporação
A seção de código de incorporação fornece uma tag de script pronta para copiar. Clique em **Copiar** para copiá-la para sua área de transferência, então cole-a em seu website antes da tag de fechamento ``:
```html theme={null}