ImplantarWeb

Personalização do widget

Saiba como personalizar a aparência do widget para combinar com sua marca e personalizar o comportamento do agente a partir de HTML.

Os widgets permitem a integração instantânea do ElevenAgents a qualquer site. Você pode personalizar seu widget pela interface ou pelos nossos SDKs do ElevenAgents com tipagem segura para ter controle total sobre o estilo e o comportamento. As substituições do SDK têm prioridade sobre a personalização pela interface. Nosso widget é multimodal e consegue processar texto e áudio.

Você também pode recuperar a configuração do widget e o link compartilhável de um agente pelo Claude ou outro cliente MCP usando o servidor MCP hospedado.

Configuração de modalidade

O widget oferece modos de entrada flexíveis para atender ao seu caso de uso. Configure essas opções no dashboard em Canais → Widget → Interface.

A multimodalidade é totalmente compatível com nossos SDKs de cliente. Saiba mais aqui.

Opções de interface do widget

Modos disponíveis:

  • Somente voz (padrão): os usuários interagem apenas por fala.
  • Voz + texto: os usuários podem alternar entre entrada por voz e texto durante as conversas.
  • Modo de chat: as conversas começam no modo de chat (somente texto), sem recursos de voz, quando iniciadas com uma mensagem de texto.

Para saber mais sobre como usar o modo de chat (somente texto) pelos nossos SDKs, consulte nosso guia do modo de chat.

Por padrão, o widget usa o modo somente voz. Ative a opção de entrada de texto para permitir interações multimodais ou ative o suporte ao modo somente texto para conversas exclusivamente por texto iniciadas por texto.

Incorporar o widget

No momento, os widgets exigem agentes públicos com a autenticação desativada. Verifique se ela está desativada na aba Avançado das configurações do agente.

Adicione este trecho de código à seção <body> do seu site. Coloque-o no arquivo principal index.html para disponibilizá-lo em todo o site:

Código de incorporação do widget
<elevenlabs-convai agent-id="<replace-with-agent_7101k5zvyjhmfg983brhmhkd98n6>"></elevenlabs-convai>
<script
  src="https://unpkg.com/@elevenlabs/convai-widget-embed"
  async
  type="text/javascript"
></script>

Para maior segurança, defina os domínios permitidos na Lista de permissões do seu agente (localizada na aba Segurança). Isso restringe o acesso apenas aos hosts especificados.

Atributos do widget

Este código básico de incorporação exibirá o widget com a configuração padrão definida no dashboard do agente. O widget oferece vários atributos HTML para personalização adicional:

<elevenlabs-convai
  agent-id="agent_id"              // Required: Your agent ID
  signed-url="signed_url"          // Alternative to agent-id
  server-location="us"             // Optional: "us" or default
  variant="expanded"               // Optional: Widget display mode
  dismissible="true"               // Optional: Allow the user to minimize the widget
></elevenlabs-convai>
<elevenlabs-convai
  avatar-image-url="https://..." // Optional: Custom avatar image
  avatar-orb-color-1="#6DB035" // Optional: Orb gradient color 1
  avatar-orb-color-2="#F5CABB" // Optional: Orb gradient color 2
></elevenlabs-convai>
<elevenlabs-convai
  action-text="Need assistance?" // Optional: CTA button text
  start-call-text="Begin conversation" // Optional: Start call button
  end-call-text="End call" // Optional: End call button
  expand-text="Open chat" // Optional: Expand widget text
  listening-text="Listening..." // Optional: Listening state
  speaking-text="Assistant speaking" // Optional: Speaking state
></elevenlabs-convai>

O widget renderiza Markdown nas respostas do agente. Por padrão, os links são exibidos como texto simples para evitar phishing.

<elevenlabs-convai
  markdown-link-allowed-hosts="example.com"  // Domains where links are clickable (use "*" for all)
  markdown-link-include-www="true"           // Also allow www variants (default: true)
  markdown-link-allow-http="true"            // Allow http:// links (default: true)
  syntax-highlight-theme="dark"              // Code block theme: "dark", "light", or "auto"
></elevenlabs-convai>

Configuração em tempo de execução

Mais dois atributos HTML podem ser usados para personalizar o comportamento do agente em tempo de execução. Esses dois recursos podem ser usados juntos, separadamente ou não serem usados.

Variáveis dinâmicas

As variáveis dinâmicas permitem inserir valores em tempo de execução nas mensagens, nos prompts de sistema e nas ferramentas do seu agente.

<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  dynamic-variables='{"user_name": "John", "account_type": "premium"}'
></elevenlabs-convai>

Todas as variáveis dinâmicas exigidas pelo agente precisam ser passadas no widget.

Saiba mais em nosso guia de variáveis dinâmicas.

Substituições

As substituições permitem personalizar totalmente o comportamento do agente em tempo de execução:

<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  override-language="es"
  override-prompt="Custom system prompt for this user"
  override-first-message="Hi! How can I help you today?"
  override-voice-id="axXgspJ2msm3clMCkdW3"
></elevenlabs-convai>

As substituições podem ser ativadas para campos específicos e são totalmente opcionais.

Saiba mais em nosso guia de substituições.

Personalização visual

Personalize a aparência do widget, o conteúdo do texto, a seleção de idioma e muito mais.

Abra seu agente no dashboard e acesse a aba Widget para personalizar a aparência, o avatar, o texto, os termos, o suporte a idiomas e muito mais.

Personalização do widget

Personalize as cores e formas do widget para combinar com a identidade da sua marca.

Aparência do widget

Implementação avançada

Para uma personalização mais avançada, use os SDKs do ElevenAgents SDKs com uma aplicação Next.js, React ou Python.

Ferramentas de cliente

As ferramentas de cliente permitem ampliar a funcionalidade do widget adicionando ouvintes de eventos. Isso permite que o widget execute ações como:

  • Redirecionar o usuário para uma página específica
  • Enviar um e-mail para sua equipe de suporte
  • Redirecionar o usuário para uma URL externa

Para ver exemplos dessas ferramentas em ação, inicie uma chamada com o agente no canto inferior direito desta página. O código-fonte está disponível no GitHub para consulta.

Criar uma ferramenta de cliente

Para criar sua primeira ferramenta de cliente, siga o guia de ferramentas de cliente.

Configuração da ferramenta de cliente

Exemplo de implementação

A seguir está um exemplo de como processar a ferramenta redirectToExternalURL acionada pelo widget no seu código JavaScript:

index.js
document.addEventListener("DOMContentLoaded", () => {
  const widget = document.querySelector("elevenlabs-convai");
  if (widget) {
    // Listen for the widget's "call" event to trigger client-side tools
    widget.addEventListener("elevenlabs-convai:call", (event) => {
      event.detail.config.clientTools = {
        // Note: To use this example, the client tool called "redirectToExternalURL" (case-sensitive) must have been created with the configuration defined above.
        redirectToExternalURL: ({ url }) => {
          window.open(url, "_blank", "noopener,noreferrer");
        },
      };
    });
  }
});

Explore nossos SDKs com tipagem segura para implementações em React, Next.js e Python.