Website Widgets
Incorpore o seu agente de voz IA em qualquer website para que os visitantes possam iniciar uma conversa de voz diretamente a partir do browser. O separador Widgets fornece códigos de embed, opções de personalização e definições de segurança de domínio.
O Callback Widget funciona de forma muito diferente dos widgets nesta página — em vez de iniciar uma chamada de voz no browser, recolhe o número de telefone do visitante e faz o seu agente ligar de volta. Veja a página dedicada Callback Widget.
Tipos de Widget
Hanc.AI oferece quatro tipos de widget no browser, mais um Callback Widget separado para callbacks telefónicos:
| Widget | Tag Name | Descrição | Melhor Para |
|---|---|---|---|
| Floating Widget | hanc-ai-floating-call | Botão orbe que flutua sobre a sua página | Call-to-action sempre visível |
| Pill Widget | hanc-ai-pill-call | Botão compacto em forma de pill colocado inline no seu conteúdo | Pegada mínima dentro de um layout existente |
| Pill Floating Widget | hanc-ai-pill-float-call | Mesma forma compacta de pill, mas flutua com a página como o Floating widget | Quando quer estética de pill que segue o visitante enquanto faz scroll |
| Inline Widget | hanc-ai-inline-call | Botão de chamada em tamanho real incorporado no conteúdo da página | Secções dedicadas "Fale Connosco" |
| Callback Widget | hanc-ai-callback | Formulário de número de telefone; agente liga de volta ao visitante | Páginas de lead-gen, landing pages de alta intenção — ver Callback Widget |
Atributos Comuns
Todos os tipos de widget suportam estes atributos centrais:
| Atributo | Obrigatório | Descrição | Padrão |
|---|---|---|---|
agent-id | Sim | O identificador único do seu agente | — |
voice-service-url | Não | Sobrepor o URL do voice service | Auto-detetado |
api-base-url | Não | Sobrepor o URL base da API | Auto-detetado |
Atributos de Display
| Atributo | Descrição | Valores | Padrão |
|---|---|---|---|
position | Posição do widget na página | bottom-right, bottom-left, top-right, top-left, static | bottom-right |
size | Tamanho do widget em pixels | Número | 120 |
theme | Nome do tema de cor | Ver Temas de Cor | default |
Atributos de Texto do Botão
| Atributo | Descrição | Padrão |
|---|---|---|
button-start-text | Texto mostrado no botão em idle | "Call" |
button-connecting-text | Texto mostrado enquanto conecta | "Connecting..." |
button-end-text | Texto mostrado durante uma chamada ativa | — |
Atributos de Terms
| Atributo | Descrição | Padrão |
|---|---|---|
terms-enabled | Ativar diálogo de consentimento antes da chamada | false |
terms-content | Texto de consentimento formatado em Markdown | "" |
terms-url | Link para a sua página de Termos e Condições | "https://hanc.ai/terms" |
privacy-url | Link para a sua página de Política de Privacidade | "https://hanc.ai/privacy" |
Atributos de terms definidos no elemento HTML são sobrepostos pelas definições do widget do agente obtidas via API, a menos que skip-fetch esteja definido como true.
Atributos de Som
| Atributo | Descrição | Padrão |
|---|---|---|
sound-enabled | Ativar sons de início/fim de chamada | true |
sound-volume | Volume dos efeitos sonoros | 0.25 |
sound-preset | Identificador do preset de som | "1" |
Temas de Cor
Personalize a aparência do widget com 11 temas de cor integrados:
| Tema | Valor |
|---|---|
| Default | default |
| Purple | purple |
| Blue | blue |
| Cyan | cyan |
| Emerald | emerald |
| Amber | amber |
| Tangerine | tangerine |
| Rose | rose |
| Ember | ember |
| Black | black |
| White | white |
Cada tema tem variantes dark e light. Defina o tema através do atributo theme no código de embed, ou configure-o nas definições de widget do agente.
Exemplos de Embed
Floating Widget
<hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Floating Widget com Tema e Posição
<hanc-ai-floating-call
agent-id="YOUR_AGENT_ID"
theme="emerald"
position="bottom-left"
size="140"
></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Pill Widget
<hanc-ai-pill-call agent-id="YOUR_AGENT_ID"></hanc-ai-pill-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Inline Widget
<hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
O URL do script acima carrega sempre o widget mais recente — o seu site recebe melhorias automaticamente. Se precisar de fixar numa versão conhecida e estável, fixe explicitamente com https://unpkg.com/hanc-webrtc-widgets@1.4.0 (substitua pela versão que quiser). A tag @latest é o padrão quando nenhuma versão é especificada.
Eventos do Widget
Os widgets emitem eventos que pode escutar em JavaScript:
| Evento | Descrição |
|---|---|
status-changed | Disparado quando o estado da chamada muda |
connecting | A chamada está a ser estabelecida |
connected | A chamada está ativa |
idle | Sem chamada ativa |
error | Ocorreu um erro |
audio-track | Faixa de áudio remota recebida (para visualização) |
local-audio-track | Faixa de áudio do microfone local (para visualização) |
microphone-enabled | O microfone foi ativado |
microphone-disabled | O microfone foi desativado |
call-start | Disparado quando uma chamada começa com sucesso |
call-end | Disparado quando a chamada termina |
Exemplo: Escutar Eventos
const widget = document.querySelector('hanc-ai-floating-call');
widget.addEventListener('call-start', () => {
console.log('Call started');
});
widget.addEventListener('call-end', () => {
console.log('Call ended');
});
Requisitos Técnicos
Os widgets exigem que o browser do visitante suporte:
- WebGL 2.0 — para rendering
- Web Audio API — para processamento de áudio
- WebRTC — para comunicação de voz em tempo real
Todos os browsers modernos (Chrome, Firefox, Safari, Edge) suportam estas tecnologias.
Restrições de Domínio
Controle quais websites podem embeber o seu widget de agente.
Domínios Sempre Permitidos
Os seguintes domínios são sempre permitidos independentemente da configuração:
hanc.ai(e subdomínios)hanc.me(e subdomínios)localhost
Permitir Todos os Domínios
Por padrão, o seu widget pode ser embebido em qualquer website. Alterne "Allow all domains" nas definições de widget para restringir isto.
Restringir a Domínios Específicos
Quando restringido, adicione cada domínio que deve ser permitido:
- Introduza nomes de domínio sem
https://(ex.:example.com) - Subdomínios precisam de entradas separadas (ex.:
www.example.com,shop.example.com) - Portas podem ser especificadas (ex.:
localhost:3000) - Máximo de 50 domínios podem ser whitelisted
Para agentes em produção, restrinja os widgets aos seus próprios domínios para prevenir embeds não autorizados.
Termos e Condições
Ative um diálogo de consentimento antes que os interlocutores possam iniciar uma conversa.
Configuração
| Definição | Descrição |
|---|---|
| Enable Terms | Ativar/desativar diálogo de termos |
| Terms Content | Texto de consentimento formatado em Markdown mostrado aos utilizadores (máx 5.000 caracteres) |
| Terms URL | Link para a sua página completa de Termos e Condições |
| Privacy URL | Link para a sua página de Política de Privacidade |
Quando ativado:
- Os utilizadores veem um diálogo de consentimento antes de iniciar uma chamada
- Têm de clicar "Agree" para prosseguir
- O consentimento é armazenado localmente no browser
- O botão Reset Consent limpa o consentimento armazenado para testes
Formatação do Conteúdo
O conteúdo de terms suporta formatação Markdown:
- Use
####para títulos - Use
**bold**para ênfase - Use quebras de linha para legibilidade
Relacionado
- Callback Widget — Phone callbacks para visitantes que preferem não falar no browser
- Voice Agents Overview
- Settings — Definições do agente incluindo configuração de widget
- Integrations — API keys e configuração de número de telefone