Ir para a navegação
ImplantarWeb

Personalização do widget

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

Os widgets permitem integrar instantaneamente o ElevenAgents a qualquer site. Você pode personalizar seu widget pela interface ou por meio dos nossos SDKs do ElevenAgents type-safe, para ter controle total sobre o estilo e o comportamento. As substituições pelo SDK têm prioridade sobre a personalização pela interface. Nosso widget é multimodal e pode 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 painel, 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 mais informações sobre como usar o modo de chat (somente texto) por meio dos 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 quando iniciadas por texto.

Incorporar o widget

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

Adicione este trecho de código à seção <body> do seu site. Coloque-o no arquivo principal index.html para que esteja disponível 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 painel do agente. O widget aceita vários atributos HTML para mais personalização:

<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 devem ser fornecidas no widget.

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

Substituições

As substituições permitem personalizar completamente o comportamento do seu 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 no nosso guia de substituições.

Personalização visual

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

Abra seu agente no painel e navegue até 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 as formas do widget para combinar com a identidade da sua marca.

Aparência do widget

Conteúdo avançado

O conteúdo avançado permite que o agente responda com componentes interativos junto das mensagens. Configure-o no painel, em Canais → Widget → Conteúdo avançado.

Configurações de conteúdo avançado do widget

O conteúdo avançado é exibido em conversas por texto e, nas conversas por voz, quando Transcrição em tempo real da conversa está ativada em Interface. Ele está disponível apenas no widget incorporado.

As respostas rápidas são botões que os usuários podem tocar em vez de digitar. Quando um usuário toca em um deles, seu rótulo é enviado como a próxima mensagem do usuário.

Respostas rápidas

Sugeridas pelo agente

O agente sugere até três respostas durante a conversa, por exemplo, para confirmar uma escolha ou oferecer próximos passos.

Respostas da primeira mensagem

Adicione até três respostas em Respostas da primeira mensagem para exibi-las com a primeira mensagem do agente, permitindo que os usuários iniciem a conversa com um toque. Arraste-as para alterar a ordem.

Essas respostas são fixas: aparecem em todas as primeiras mensagens, e o agente não as escolhe. Elas são traduzidas junto com suas outras predefinições de idioma.

Como o agente usa conteúdo avançado

Exceto pelas respostas da primeira mensagem, o agente decide a cada turno se deve exibir respostas rápidas ou um carrossel. Uma resposta que não precisa de um componente permanece como texto simples. Para definir quando e como eles aparecem, descreva isso no prompt de sistema do agente.

As respostas rápidas e o carrossel vêm ativados por padrão para novos agentes. Para agentes criados antes de o conteúdo avançado estar disponível, ative-os nas configurações do widget.

Implementação avançada

Para personalizações mais avançadas, use os SDKs do ElevenAgents SDKs type-safe com um aplicativo Next.js, React ou Python.

Ferramentas de cliente

As ferramentas de cliente permitem ampliar a funcionalidade do widget adicionando escutadores de eventos. Isso permite que o widget realize 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 referência.

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

Veja abaixo 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 type-safe para implementações em React, Next.js e Python.