> 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

## Visão geral

A personalização permite adaptar o comportamento do seu agente a cada usuário, possibilitando conversas mais naturais e relevantes para o contexto. A ElevenLabs oferece várias abordagens para personalização:

1. **Variáveis dinâmicas** - Insira valores em tempo de execução em prompts e mensagens
2. **Substituições** - Substitua completamente prompts do sistema ou mensagens
3. **Webhooks de início de conversa** - Busque esses dados no seu servidor quando uma conversa começar

## Métodos de personalização

#### [Variáveis dinâmicas](/docs/pt/eleven-agents/customization/personalization/dynamic-variables)

Defina valores em tempo de execução usando a sintaxe `{{ var_name }}` para personalizar as mensagens,
os prompts do sistema e as ferramentas do seu agente.

#### [Substituições](/docs/pt/eleven-agents/customization/personalization/overrides)

Substitua completamente os prompts do sistema, as primeiras mensagens, o idioma ou as configurações de voz de cada
conversa.

#### [Webhooks de início de conversa](/docs/pt/eleven-agents/customization/personalization#conversation-initiation-webhooks)

Busque variáveis dinâmicas e substituições no seu servidor para conversas recebidas.

## Estrutura de dados de início de conversa do cliente

O objeto `conversation_initiation_client_data` define o que pode ser personalizado ao iniciar uma conversa. Os clientes podem enviá-lo diretamente. Um webhook de início de conversa retorna o mesmo objeto.

```json
{
  "type": "conversation_initiation_client_data",
  "conversation_config_override": {
    "agent": {
      "prompt": {
        "prompt": "overriding system prompt",
        "llm": "gpt-5.6-luna"
      },
      "first_message": "overriding first message",
      "language": "en"
    },
    "tts": {
      "voice_id": "voice-id-here"
    },
    "conversation": {
      "text_only": false
    },
    "asr": {
      "keywords": ["Acme Corp", "Contoso"]
    }
  },
  "custom_llm_extra_body": {
    "temperature": 0.7,
    "max_tokens": 100
  },
  "dynamic_variables": {
    "string_var": "text value",
    "number_var": 1.2,
    "integer_var": 123,
    "boolean_var": true
  },
  "user_id": "your_custom_user_id",
  "branch_id": "agtbrch_xxxx",
  "environment": "production"
}
```

> **Warning**
>
> As variáveis dinâmicas do sistema (com o prefixo `system__`) não podem ser enviadas nem substituídas na
> carga de início do cliente. Somente variáveis dinâmicas personalizadas podem ser definidas pelo campo
> `dynamic_variables`.

## Webhooks de início de conversa

Para telefonia e mensagens recebidas, o ElevenAgents pode buscar esses dados de início no seu servidor em vez de no cliente. Quando o webhook está ativado, o ElevenAgents envia uma solicitação `POST` e aplica o JSON retornado por você.

Configure a URL do webhook e os segredos de cabeçalho nas [configurações de Agents](https://elevenlabs.io/app/agents/settings). Na aba **Segurança** do agente, ative **Buscar dados de início do cliente em um webhook** e todos os campos de substituição que sua resposta possa incluir.

O webhook é executado para uma nova conversa recebida no Twilio Voice, Exotel, tronco SIP, WhatsApp ou Twilio SMS quando os dados de início do cliente ainda não estão presentes.

Chamadas de saída do Twilio Voice, Exotel, SIP e WhatsApp só o acionam se a solicitação de saída não incluiu `conversation_initiation_client_data`. Mensagens de saída do WhatsApp nunca o acionam — envie variáveis dinâmicas na solicitação de saída.

Ele não é executado para conversas do widget ou SDK, outras integrações de mensagens nem conversas retomadas do WhatsApp e SMS.

> **Warning**
>
> Conversas de prévia iniciadas na página de configurações do agente não acionam webhooks de início de
> conversa. Use os espaços reservados de **Variáveis dinâmicas** no editor do agente ao testar na Prévia.
> Esses espaços reservados não são usados em conversas recebidas em produção.

O ElevenAgents envia o contexto do chamador no corpo da solicitação:

```json
{
  "caller_id": "+15551234567",
  "called_number": "+15557654321",
  "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
  "call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "conversation_id": "conv_8901k5zvyjhmfg983brhmhkd98n6"
}
```

`caller_id` e `called_number` são números de telefone no Twilio, Exotel, SIP e SMS. No WhatsApp recebido, eles são o ID de usuário do WhatsApp e o ID do número de telefone do seu WhatsApp. Em chamadas de saída, `caller_id` é o seu número e `called_number` é a pessoa para quem a chamada é feita. `call_sid` é o SID da chamada do provedor na telefonia e uma string vazia no WhatsApp e SMS. Chamadas SIP também podem incluir `call_id` e `sip_headers`.

Sua resposta deve usar a estrutura `conversation_initiation_client_data` acima. Inclua todas as variáveis dinâmicas personalizadas definidas pelo agente. As substituições são opcionais e precisam ser ativadas em **Segurança**. O corpo da resposta HTTP deve ter 256 KB ou menos (262.144 bytes).

Um webhook com falha ou que exceda o tempo limite pode impedir o início da conversa. Para a configuração do Twilio, consulte [personalização do Twilio](/docs/pt/eleven-agents/customization/personalization/twilio-personalization). Este webhook é separado dos [webhooks pós-chamada](/docs/pt/eleven-agents/workflows/post-call-webhooks).

## Como escolher a abordagem certa

<thead>
  <tr>
    <th>
      Método
    </th>

    <th>
      Ideal para
    </th>

    <th>
      Implementação
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      **Variáveis dinâmicas**
    </td>

    <td>
      * Inserir dados específicos do usuário em conteúdo com modelo - Manter um comportamento consistente do agente
        com detalhes personalizados - Personalizar parâmetros de ferramentas
    </td>

    <td>
      Defina variáveis com 

      `{{ variable_name }}`

       e envie valores em tempo de execução
    </td>
  </tr>

  <tr>
    <td>
      **Substituições**
    </td>

    <td>
      * Alterar completamente o comportamento do agente por usuário - Alternar idiomas ou vozes - Aplicativos
        legados (considere migrar para Variáveis dinâmicas)
    </td>

    <td>
      Ative permissões específicas de substituição nas configurações de segurança e envie o conteúdo completo de
      substituição
    </td>
  </tr>

  <tr>
    <td>
      **Webhooks de início de conversa**
    </td>

    <td>
      * Personalizar conversas recebidas do Twilio, SIP, WhatsApp ou SMS pelo seu servidor -
        Consultar o contexto do chamador antes do início da conversa
    </td>

    <td>
      Ative o webhook nas configurações de Segurança e retorne `conversation_initiation_client_data`
    </td>
  </tr>
</tbody>

## Saiba mais

* [Documentação de variáveis dinâmicas](/docs/pt/eleven-agents/customization/personalization/dynamic-variables)
* [Documentação de substituições](/docs/pt/eleven-agents/customization/personalization/overrides)
* [Personalização do Twilio](/docs/pt/eleven-agents/customization/personalization/twilio-personalization)