Callback Widget

O Callback Widget é um pequeno formulário incorporável que permite aos visitantes do seu site deixarem o seu número de telefone e receberem uma chamada de volta do seu agente de voz IA — normalmente em segundos. Em vez de pedir aos visitantes para ligarem, é a conversa que vai ter com eles.

Este é o quinto tipo de widget, juntamente com os widgets Floating, Pill, Inline e Popup — mas funciona de forma muito diferente. Os outros widgets iniciam uma conversa de voz no browser. O Callback Widget coloca em fila uma chamada telefónica real efetuada pelo seu agente através do seu número outbound.

---

Quando Usar

Cenário	Porque o Callback Widget Encaixa
Landing pages de lead-gen	O visitante compromete-se com um número de telefone, o agente qualifica-o no minuto seguinte
Páginas de produto de alta intenção	"Fale com um especialista" sem fazer o visitante ligar
Sites mobile-first	Um toque na pill, sem prompt de permissão, sem auscultadores necessários
Cobertura fora de horário	O visitante deixa um número fora de horas, o agente liga quando a fila abrir
Fricção reduzida vs. formulários	Os visitantes submetem um único campo e recebem uma resposta instantânea

---

Elegibilidade

O Callback Widget requer três coisas na sua conta para poder ser ativado:

Requisito	Porquê
Plano pago (Starter ou superior)	Os minutos outbound consumidos durante o callback são faturados ao minuto
Número outbound verificado atribuído ao agente	O agente precisa de um número real para marcar
Email verificado no seu workspace	Confirma a propriedade antes de desbloquear chamadas outbound

Se algum destes estiver em falta, a secção do Callback widget no separador Widgets do agente mostra um alerta a dizer-lhe exatamente o que corrigir. O widget permanece desativado até os três estarem em vigor.

Plano Free

O Callback Widget não está disponível no plano Free porque efetua chamadas telefónicas outbound. Todos os outros tipos de widget (Floating, Pill, Inline) continuam gratuitos.

---

Configuração

1. Ativar callback no agente

1. Abra o seu agente e vá ao separador Widgets.
2. Desça até à secção Callback widget.
3. Ative "Enable callback widget".
4. Configure:
   • Retry attempts — quantas vezes o agente tenta novamente se o visitante não atender (1–5, padrão 3).
   • Retry interval — minutos entre tentativas (1–30, padrão 5).
   • Widget language — o idioma em que o formulário, mensagens de estado e seletor de país falam com o seu visitante (14 idiomas disponíveis — ver abaixo).
   • Theme — esquema de cores para a pill flutuante e o diálogo (usa a mesma paleta de temas dos outros widgets).
5. Guarde.

Uma pré-visualização ao vivo do widget aparece junto às definições para que possa ver as suas alterações imediatamente — não precisa de fazer deploy para testar a aparência.

2. Copiar o snippet de embed

Na mesma secção, copie o snippet HTML:

<hanc-ai-callback agent-id="YOUR_AGENT_ID"></hanc-ai-callback>
<script src="https://unpkg.com/hanc-webrtc-widgets@latest" async type="text/javascript"></script>

Cole-o uma vez no seu site, normalmente mesmo antes de </body>. O widget aparece como uma pill flutuante no canto da página.

dica

A tag @latest significa que o seu site automaticamente recebe as novas versões do widget quando são lançadas. Fixe numa versão específica (ex.: hanc-webrtc-widgets@1.4.0) se quiser controlo total sobre as atualizações.

---

O Que o Visitante Vê

O widget guia os visitantes através de quatro estados:

Estado	O Que o Visitante Vê
Form	Pill flutuante no canto. Clica para abrir. Seletor de país à esquerda, input de telefone à direita, botão de submissão.
Queued	"Está na fila — cerca de N segundos até lhe ligarmos." Atualiza ao vivo.
Dialing	"Estamos a ligar-lhe agora." Permanece até a chamada conectar ou falhar.
Completed / Failed	Uma curta confirmação ou um erro amigável com a sugestão "recarregue a página para fazer outro callback".

O formulário valida automaticamente o número de telefone face ao formato nacional do país escolhido e recusa submeter a menos que o número seja plausível.

Cobertura de Países

O seletor de países cobre a Europa (UE + DACH + Reino Unido), América do Norte (EUA + Canadá), e um conjunto curado de países adicionais amplamente suportados. Cada país mostra a sua bandeira, nome e um placeholder de exemplo no formato nativo para que o visitante saiba o que escrever.

Se um país que os seus visitantes usam não estiver listado, contacte support@hanc.ai — a cobertura é expandida regularmente.

---

Atributos HTML

O widget aceita estes atributos na tag <hanc-ai-callback>:

Atributo	Obrigatório	Descrição
agent-id	Sim	O identificador único do seu agente
locale	Não	Sobrepõe o idioma da UI do widget para esta página (ex.: locale="de"). Útil se o seu site for multilíngue e o locale da página não corresponder ao padrão do agente.
theme	Não	Sobrepõe o tema de cor para esta página
position	Não	Onde a pill flutuante se ancora (bottom-right, bottom-left, top-right, top-left)

Tudo o que deixar de fora recai no que tiver configurado no agente no dashboard.

Exemplo: Página em alemão num site multilíngue

<hanc-ai-callback agent-id="YOUR_AGENT_ID" locale="de"></hanc-ai-callback>
<script src="https://unpkg.com/hanc-webrtc-widgets@latest" async></script>

O texto da pill, etiquetas do diálogo, seletor de país e mensagens de estado passam todos para alemão. O próprio agente continua a falar no idioma para que estiver configurado — locale só afeta o que o visitante lê na página.

---

Idioma do Widget

A UI do widget vem com 14 idiomas integrados:

Código	Idioma
en	English
de	Deutsch
fr	Français
es	Español
it	Italiano
pt	Português
pl	Polski
cs	Čeština
hu	Magyar
tr	Türkçe
kk	Қазақша
zh	中文
ru	Русский
uk	Українська

O agente escolhe o seu idioma a partir de três lugares, por ordem de prioridade:

1. O atributo locale="…" no embed (prioridade mais alta)
2. O Widget language definido no separador Widgets do agente
3. Inglês (padrão)

Idioma do widget ≠ idioma de fala do agente

O idioma do widget só afeta o texto no ecrã que o visitante lê — etiquetas, seletor de país, mensagens de estado. A conversa de voz real acontece no idioma em que o seu agente está configurado para falar.

---

Comportamento de Retry

Se o visitante não atender à primeira tentativa, o agente espera o intervalo configurado e tenta novamente — até ao número configurado de tentativas.

• Tentativas: 1–5 (padrão 3)
• Intervalo: 1–30 minutos (padrão 5)

O widget mostra ao visitante o estado de cada tentativa. Depois de todas as tentativas falharem, o widget muda para o estado "não conseguimos contactá-lo" com uma mensagem cordial.

Escolha os números certos

Três tentativas com intervalos de cinco minutos funciona bem para a maioria das páginas de lead-gen — rápido o suficiente para o visitante ainda estar a navegar, suave o suficiente para não parecer insistente. Aumente se a sua audiência tende a ignorar números desconhecidos.

---

Um Callback por Carregamento de Página

Assim que um visitante submete o seu número, o widget bloqueia-se durante o resto dessa página:

• Fechar o diálogo recolhe a pill mas não repõe o formulário.
• Reabrir mostra o estado atual (queued / dialing / completed / failed), não um formulário novo.
• Para fazer um segundo callback, o visitante precisa de recarregar a página.

Isto previne submissões duplicadas acidentais enquanto uma chamada já está a caminho. Se o visitante cancelar explicitamente o seu callback em fila a partir do diálogo (o botão "Cancel" no ecrã queued), o bloqueio é libertado e ele pode re-submeter imediatamente.

O que acontece se recarregarem a meio de um callback?

Se um visitante recarregar a página enquanto o agente ainda está a tentar o seu número, o widget deteta que já existe um callback ativo para o mesmo número e reconecta-se silenciosamente — sem marcação duplicada, sem segunda entrada em fila. O visitante apenas vê o seu estado existente a continuar de onde estava.

---

Concorrência e Throughput

Um único agente pode ter até 10 callbacks em curso ao mesmo tempo. As submissões para além disso esperam na fila e são marcadas à medida que a capacidade liberta.

O loop agente-libertado-e-marcar drena a fila continuamente — a maioria dos visitantes é marcada em poucos segundos após submeter se não estiver perto do limite de concorrência.

Existe um limite de taxa por número (um número só pode ser colocado em fila um punhado de vezes por hora para o mesmo agente) para prevenir abuso. Os visitantes que atinjam o limite veem uma mensagem amigável "entraremos em contacto em breve" em vez do ecrã queued.

---

Pré-visualização ao Vivo no Dashboard

O separador Widgets mostra uma pré-visualização ao vivo do callback widget junto às definições. Qualquer alteração que faça — tema, idioma, números de retry — atualiza a pré-visualização instantaneamente. Não tem de fazer deploy do seu site para ver como o widget vai parecer.

A pré-visualização usa um manifest mock com a lista completa de países e elegibilidade demo, para que o widget renderize mesmo em planos onde os callbacks outbound ainda não estão disponíveis.

---

Tracking Embutido

O widget emite os mesmos eventos call-start e call-end que os outros widgets. Escute-os em JavaScript se quiser disparar os seus próprios analytics:

const widget = document.querySelector('hanc-ai-callback');

widget.addEventListener('call-start', () => {
  // O callback do visitante acabou de ser ligado — registar como conversão
});

widget.addEventListener('call-end', () => {
  // Callback terminado — registar duração, resultado, etc.
});

---

Disponibilidade por Plano

Plano	Callback Widget
Free	Não disponível (requer chamadas outbound)
Starter / Pro / Business / Enterprise	Disponível

Todos os planos pagos recebem o mesmo conjunto de funcionalidades do widget. O custo por chamada segue a sua taxa outbound normal — veja Billing.

---

Relacionado

• Website Widgets — Tipos de widget Floating, Pill, Inline e Popup para conversas no browser
• Settings — Definições de chamada ao nível do agente incluindo Max Call Duration que também limita callbacks
• Phone Numbers — Conecte o número outbound a partir do qual o seu callback widget vai marcar
• FAQ — Perguntas comuns e casos extremos