Configurar

Personalização

Aprenda a personalizar o comportamento do seu agente usando variáveis dinâmicas e substituições.

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

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

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

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.

{
  "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"
}

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. 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.

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:

{
  "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. Este webhook é separado dos webhooks pós-chamada.

Como escolher a abordagem certa

MétodoIdeal paraImplementação
Variáveis dinâmicas
  • 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
Defina variáveis com {{ variable_name }} e envie valores em tempo de execução
Substituições
  • Alterar completamente o comportamento do agente por usuário - Alternar idiomas ou vozes - Aplicativos legados (considere migrar para Variáveis dinâmicas)

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

Webhooks de início de conversa
  • Personalizar conversas recebidas do Twilio, SIP, WhatsApp ou SMS pelo seu servidor - Consultar o contexto do chamador antes do início da conversa

Ative o webhook nas configurações de Segurança e retorne conversation_initiation_client_data

Saiba mais