ImplantarTelefoniaTwilio

Personalização do Twilio

Configure a personalização de chamadas recebidas do Twilio usando webhooks.

Visão geral

Ao receber chamadas de entrada do Twilio, você pode buscar dinamicamente dados de início da conversa por meio de um webhook. Isso permite personalizar o comportamento do seu agente com base nas informações de quem liga e em outros dados contextuais.

Para saber quando o webhook é acionado e o formato da solicitação, consulte webhooks de início da conversa.

Como funciona

  1. Quando uma chamada do Twilio é recebida, o ElevenAgents faz uma chamada de webhook para o endpoint especificado, passando informações da chamada (caller_id, agent_id, called_number, call_sid, conversation_id) como argumentos
  2. Seu webhook retorna os dados de cliente para início da conversa, incluindo variáveis dinâmicas e substituições (um exemplo é mostrado abaixo)
  3. Esses dados são usados para iniciar a conversa

O sistema usa o período de conexão/discagem do Twilio para buscar dados do webhook em paralelo, criando uma experiência fluida em que:

  • Os usuários ouvem o som esperado de conexão telefônica
  • Em paralelo, o ElevenAgents busca os dados necessários do webhook
  • A conversa é iniciada com os dados obtidos quando a conexão de áudio é estabelecida

Configuração

1

Configure os detalhes do webhook

Na página de configurações do ElevenAgents, configure a URL do webhook e adicione os secrets necessários para autenticação.

Ativar webhook

Clique no webhook para modificar quais secrets são enviados nos cabeçalhos.

Adicionar secrets aos cabeçalhos

2

Ative a busca de dados de início da conversa

Na aba “Segurança” da página do agente, ative a busca de dados de início da conversa para chamadas de entrada do Twilio e defina os campos que podem ser substituídos.

Ativar webhook

3

Implemente o endpoint de webhook para receber dados do Twilio

O webhook receberá uma solicitação POST com os seguintes parâmetros:

ParâmetroTipoDescrição
caller_idstringO número de telefone de quem está ligando
agent_idstringO ID do agente que recebe a chamada
called_numberstringO número do Twilio que foi chamado
call_sidstringIdentificador único da chamada do Twilio
conversation_idstringIdentificador da conversa do ElevenLabs
4

Retorne os dados de cliente para início da conversa

Seu webhook deve retornar uma resposta JSON contendo os dados de início para o agente.

O campo dynamic_variables deve conter todas as variáveis dinâmicas definidas para o agente. As substituições, por outro lado, são totalmente opcionais. Para mais informações sobre variáveis dinâmicas e substituições, consulte a documentação sobre variáveis dinâmicas e substituições.

Um exemplo de resposta poderia ser:

{
  "type": "conversation_initiation_client_data",
  "conversation_config_override": {
    "agent": {
      "prompt": {
        "prompt": "The customer's bank account balance is $100. They are based in San Francisco.",
        "llm": "gpt-5.6-luna"
      },
      "first_message": "Hi, how can I help you today?",
      "language": "en"
    },
    "tts": {
      "voice_id": "new-voice-id"
    },
    "conversation": {
      "text_only": false
    }
  },
  "dynamic_variables": {
    "customer_name": "John Doe",
    "account_status": "premium",
    "last_interaction": "2026-01-15"
  },
  "branch_id": "agtbrch_xxxx",
  "environment": "production"
}

O ElevenAgents usará as variáveis dinâmicas para preencher os dados de início da conversa, e ela começará sem problemas.

Garanta que seu webhook responda dentro de um período de tempo razoável para evitar atrasos no atendimento da chamada.

Segurança

  • Use apenas endpoints HTTPS
  • Implemente a autenticação usando cabeçalhos de solicitação
  • Armazene valores sensíveis como secrets usando o gerenciador de secrets do ElevenLabs
  • Valide os parâmetros da solicitação recebida