Registrar chamadas do Twilio

Quando usar cada abordagem

Antes de começar, entenda as diferenças entre a integração nativa e a abordagem de registrar chamada:

Visão geral

O endpoint de registrar chamada permite usar sua própria infraestrutura do Twilio enquanto aproveita os agentes da ElevenLabs para a conversa. Em vez de importar seu número do Twilio para a ElevenLabs, você mantém controle total da configuração do Twilio e usa a API da ElevenLabs para registrar chamadas e receber TwiML para conectá-las aos seus agentes.

Esta abordagem é ideal quando você:

• Precisa manter sua infraestrutura e workflows existentes do Twilio
• Quer controle programático sobre o roteamento e tratamento de chamadas
• Tem fluxos de chamada complexos que exigem lógica personalizada do Twilio antes de conectar a um agente
• Precisa integrar agentes da ElevenLabs a um sistema de telefonia existente

Como funciona

1. Seu servidor recebe uma chamada recebida ou inicia uma chamada de saída pelo Twilio
2. Seu servidor chama o endpoint de registrar chamada da ElevenLabs com os detalhes do agente e da chamada
3. A ElevenLabs retorna TwiML que conecta a chamada ao seu agente via WebSocket
4. Você retorna esse TwiML ao Twilio para estabelecer a conexão

Pré-requisitos

• Uma conta da ElevenLabs
• Um agente conversacional da ElevenLabs configurado (crie um aqui)
• Uma conta do Twilio com um número de telefone ativo
• Seu agente configurado com formato de áudio μ-law 8000 Hz (consulte a configuração do agente)

Configuração do agente

Antes de usar o endpoint de registrar chamada, configure seu agente para usar o formato de áudio correto compatível com o Twilio.

1

Configurar saída de TTS

1. Navegue até as configurações do seu agente
2. Acesse a seção Voice
3. Selecione “μ-law 8000 Hz” no menu suspenso

2

Definir formato de entrada

1. Navegue até as configurações do seu agente
2. Acesse a seção Advanced
3. Selecione “μ-law 8000 Hz” para o formato de entrada

Referência da API

O endpoint de registrar chamada aceita os seguintes parâmetros:

O endpoint retorna TwiML, que você deve passar diretamente ao Twilio.

Implementação

import os
from fastapi import FastAPI, Request
from fastapi.responses import Response
from elevenlabs import ElevenLabs
app = FastAPI()
elevenlabs = ElevenLabs()
AGENT_ID = os.getenv("ELEVENLABS_AGENT_ID")
@app.post("/twilio/inbound")
async def handle_inbound_call(request: Request):
    form_data = await request.form()
    from_number = form_data.get("From")
    to_number = form_data.get("To")
    # Register the call with ElevenLabs
    twiml = elevenlabs.conversational_ai.twilio.register_call(
        agent_id=AGENT_ID,
        from_number=from_number,
        to_number=to_number,
        direction="inbound",
        conversation_initiation_client_data={
            "dynamic_variables": {
                "caller_number": from_number,
            }
        }
    )
    # Return the TwiML directly to Twilio
    return Response(content=twiml, media_type="application/xml")
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Chamadas de saída

Para chamadas de saída, inicie a chamada pelo Twilio e direcione a URL do webhook para seu servidor, que então registra a chamada na ElevenLabs:

from twilio.rest import Client
import os
from fastapi import Request
from fastapi.responses import Response
from elevenlabs import ElevenLabs
# Initialize clients
twilio_client = Client(
    os.getenv("TWILIO_ACCOUNT_SID"),
    os.getenv("TWILIO_AUTH_TOKEN")
)
elevenlabs = ElevenLabs()
AGENT_ID = os.getenv("ELEVENLABS_AGENT_ID")
def initiate_outbound_call(to_number: str):
    call = twilio_client.calls.create(
        from_=os.getenv("TWILIO_PHONE_NUMBER"),
        to=to_number,
        url="https://your-server.com/twilio/outbound"
    )
    return call.sid
@app.post("/twilio/outbound")
async def handle_outbound_webhook(request: Request):
    form_data = await request.form()
    from_number = form_data.get("From")
    to_number = form_data.get("To")
    twiml = elevenlabs.conversational_ai.twilio.register_call(
        agent_id=AGENT_ID,
        from_number=from_number,
        to_number=to_number,
        direction="outbound",
    )
    return Response(content=twiml, media_type="application/xml")

Personalização de conversas

Use o parâmetro conversation_initiation_client_data para passar variáveis dinâmicas e substituir a configuração do agente:

{
  "agent_id": "your-agent-id",
  "from_number": "+1234567890",
  "to_number": "+0987654321",
  "direction": "inbound",
  "conversation_initiation_client_data": {
    "dynamic_variables": {
      "customer_name": "John Doe",
      "account_type": "premium",
      "order_id": "ORD-12345"
    }
  }
}

Configuração do Twilio

Configure seu número de telefone do Twilio para apontar para seu servidor:

1

Criar uma URL pública

Para desenvolvimento local, use o ngrok para expor seu servidor:

ngrok http 8000

2

Configurar seu número do Twilio

1. Acesse o Console do Twilio
2. Navegue até Phone Numbers > Manage > Active numbers
3. Selecione seu número de telefone
4. Em “Voice Configuration”, defina a URL do webhook para o endpoint do seu servidor (por exemplo, https://your-ngrok-url.ngrok.app/twilio/inbound)
5. Defina o método HTTP como POST

Limitações

Ao usar o endpoint de registrar chamada em vez da integração nativa:

• Sem transferências de chamada: a funcionalidade de transferência não está disponível porque a ElevenLabs não tem acesso às suas credenciais do Twilio
• Configuração manual: você precisa configurar os formatos de áudio e gerenciar o roteamento de TwiML por conta própria
• Sem importação pelo painel: números de telefone registrados dessa forma não aparecem no painel de números de telefone da ElevenLabs