> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.
# Personalização do widget
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](/docs/pt/eleven-api/resources/libraries) 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.
> **Note**
>
> 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](/docs/pt/eleven-agents/operate/hosted-mcp).
## 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**.
> **Note**
>
> A multimodalidade é totalmente compatível com nossos SDKs de cliente. Saiba mais
> [aqui](/docs/pt/eleven-api/resources/libraries).
**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](/docs/pt/eleven-agents/guides/chat-mode).
> **Note**
>
> 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
> **Note**
>
> 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 `` do seu site. Coloque-o no arquivo principal `index.html` para disponibilizá-lo em todo o site:
**`Código de incorporação do widget`**
```html title="Código de incorporação do widget"
```
> **Info**
>
> 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:
#### Configuração principal
```html
```
#### Personalização visual
```html
```
#### Personalização de texto
```html
```
#### Renderização de Markdown
O widget renderiza Markdown nas respostas do agente. Por padrão, os links são exibidos como texto simples para evitar phishing.
```html
```
## 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.
```html
```
Todas as variáveis dinâmicas exigidas pelo agente precisam ser passadas no widget.
> **Info**
>
> Saiba mais em nosso [guia de variáveis dinâmicas](/docs/pt/eleven-agents/customization/personalization/dynamic-variables).
### Substituições
As substituições permitem personalizar totalmente o comportamento do agente em tempo de execução:
```html
```
As substituições podem ser ativadas para campos específicos e são totalmente opcionais.
> **Info**
>
> Saiba mais em nosso [guia de substituições](/docs/pt/eleven-agents/customization/personalization/overrides).
## Personalização visual
Personalize a aparência do widget, o conteúdo do texto, a seleção de idioma e muito mais.
#### Atualizar pelo dashboard
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.
#### Atualizar pela CLI
#### Baixar a configuração do agente
```bash
elevenlabs agents pull --agent ""
```
#### Editar \`agent_configs/\.json\`
Defina os campos em `platform_settings.widget`. Por exemplo, para alterar as cores do orbe e o modo de feedback:
```json
{
"platform_settings": {
"widget": {
"variant": "full",
"placement": "bottom-right",
"avatar": {
"type": "orb",
"color_1": "#6DB035",
"color_2": "#F5CABB"
},
"feedback_mode": "during",
"bg_color": "#ffffff",
"text_color": "#000000",
"btn_color": "#000000",
"btn_text_color": "#ffffff"
}
}
}
```
#### Enviar suas alterações
```bash
elevenlabs agents push --agent ""
```
#### Atualizar pela API
```python
from elevenlabs import ElevenLabs
elevenlabs = ElevenLabs()
elevenlabs.conversational_ai.agents.update(
agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
platform_settings={
"widget": {
"variant": "full",
"placement": "bottom-right",
"avatar": {
"type": "orb",
"color_1": "#6DB035",
"color_2": "#F5CABB",
},
"feedback_mode": "during",
},
},
)
```
```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const elevenlabs = new ElevenLabsClient();
await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
platformSettings: {
widget: {
variant: "full",
placement: "bottom-right",
avatar: {
type: "orb",
color1: "#6DB035",
color2: "#F5CABB",
},
feedbackMode: "during",
},
},
});
```
#### Aparência
Personalize as cores e formas do widget para combinar com a identidade da sua marca.
#### Feedback
Colete insights dos usuários para melhorar o desempenho do agente. Isso pode ser usado para ajustar a base de conhecimento e o prompt de sistema do seu agente.
**Modos de coleta**
* **Nenhum**: desativa totalmente a coleta de feedback.
* **Durante a conversa**: permite feedback em tempo real durante as conversas. Metadados adicionais, como a resposta do agente que motivou o feedback, serão coletados para ajudar a identificar lacunas.
* **Após a conversa**: exibe uma única solicitação de feedback após a conversa.
> **Note**
>
> Envie feedback de forma programática pela [API](/docs/pt/eleven-agents/api-reference/conversations/create) ao usar implementações personalizadas de SDK.
#### Avatar
Configure o orbe de voz ou forneça seu próprio avatar.
**Opções disponíveis**
* **Orbe**: escolha duas cores de gradiente (por exemplo, #6DB035 e #F5CABB).
* **Link/imagem**: use uma imagem de avatar personalizada.
#### Texto exibido
Personalize todos os elementos de texto exibidos no widget, por exemplo, para modificar os rótulos dos botões.
#### Termos
Exiba termos e condições personalizados antes da conversa.
**Opções disponíveis**
* **Conteúdo dos termos**: use Markdown para formatar o texto da sua política.
* **Chave de armazenamento local**: uma chave (por exemplo, "terms_accepted") para evitar solicitar confirmação a usuários recorrentes.
**Uso**
Os termos são exibidos aos usuários em uma janela modal antes do início da chamada:
Os termos podem ser escritos em Markdown, permitindo que você:
* Adicione links para políticas externas
* Formate o texto com títulos e listas
* Inclua ênfase e estilização
Para mais ajuda com Markdown, consulte o [guia de ajuda do CommonMark](https://commonmark.org/help/).
> **Info**
>
> Depois de aceito, o status é armazenado localmente e o usuário não receberá outra solicitação em visitas
> posteriores.
#### Idioma
Ative o suporte a vários idiomas no widget.
> **Note**
>
> Para ativar a seleção de idioma, primeiro você precisa [adicionar outros idiomas](/docs/pt/eleven-agents/customization/voice/customization/language) ao seu agente.
#### Silenciamento
Permita que os usuários silenciem o áudio no widget.
Para adicionar o botão de silenciar, ative esta opção no cartão `interface` das configurações de
`widget` do agente.
#### Página compartilhável
Personalize sua página pública de destino do widget (link compartilhável).
**Opções disponíveis**
* **Descrição**: forneça um parágrafo curto explicando o objetivo da chamada.
---
## Implementação avançada
> **Note**
>
> Para uma personalização mais avançada, use os [SDKs do ElevenAgents SDKs](/docs/pt/eleven-api/resources/libraries) 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](https://github.com/elevenlabs/elevenlabs-dx/blob/main/fern/assets/scripts/widget.js) para consulta.
#### Criar uma ferramenta de cliente
Para criar sua primeira ferramenta de cliente, siga o [guia de ferramentas de cliente](/docs/pt/eleven-agents/customization/tools/client-tools).
#### Exemplo: criar a ferramenta \`redirectToExternalURL\`
#### 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`**
```javascript title="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");
},
};
});
}
});
```
> **Info**
>
> Explore nossos [SDKs](/docs/pt/eleven-api/resources/libraries) com tipagem segura para implementações em React, Next.js e Python.