Registrar llamadas de Twilio

Cuándo usar cada enfoque

Antes de empezar, conoce las diferencias entre la integración nativa y el enfoque de registrar llamadas:

Resumen

La ruta de API para registrar llamadas te permite usar tu propia infraestructura de Twilio mientras aprovechas los agentes de ElevenLabs para la conversación. En lugar de importar tu número de Twilio a ElevenLabs, mantienes el control total de tu configuración de Twilio y utilizas la API de ElevenLabs para registrar llamadas y recibir TwiML para conectarlas a tus agentes.

Este enfoque es ideal si:

• Necesitas mantener tu infraestructura y workflows de Twilio actuales
• Quieres controlar mediante programación el enrutamiento y la gestión de llamadas
• Tienes flujos de llamadas complejos que requieren lógica personalizada de Twilio antes de conectar con un agente
• Necesitas integrar agentes de ElevenLabs en un sistema de telefonía existente

Cómo funciona

1. Tu servidor recibe una llamada entrante o inicia una llamada saliente mediante Twilio
2. Tu servidor llama a la ruta de API de registro de llamadas de ElevenLabs con los detalles del agente y de la llamada
3. ElevenLabs devuelve TwiML que conecta la llamada con tu agente mediante WebSocket
4. Devuelves este TwiML a Twilio para establecer la conexión

Requisitos previos

• Una cuenta de ElevenLabs
• Un agente conversacional de ElevenLabs configurado (crea uno aquí)
• Una cuenta de Twilio con un número de teléfono activo
• Tu agente configurado con el formato de audio μ-law de 8000 Hz (consulta la configuración del agente)

Configuración del agente

Antes de utilizar la ruta de API para registrar llamadas, configura tu agente para usar el formato de audio correcto compatible con Twilio.

1

Configura la salida de TTS

1. Ve a los ajustes de tu agente
2. Ve a la sección Voz
3. Selecciona “μ-law 8000 Hz” en el menú desplegable

2

Configura el formato de entrada

1. Ve a los ajustes de tu agente
2. Ve a la sección Avanzado
3. Selecciona “μ-law 8000 Hz” como formato de entrada

Referencia de la API

La ruta de API para registrar llamadas acepta los siguientes parámetros:

La ruta de API devuelve TwiML, que debes pasar directamente a Twilio.

Implementación

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)

Llamadas salientes

Para las llamadas salientes, inicia la llamada mediante Twilio y dirige la URL del webhook a tu servidor, que después la registra en 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 las conversaciones

Utiliza el parámetro conversation_initiation_client_data para pasar variables dinámicas y anular la configuración del 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"
    }
  }
}

Configuración de Twilio

Configura tu número de teléfono de Twilio para que apunte a tu servidor:

1

Crea una URL pública

Para el desarrollo local, utiliza ngrok para exponer tu servidor:

ngrok http 8000

2

Configura tu número de Twilio

1. Ve a la consola de Twilio
2. Ve a Phone Numbers > Manage > Active numbers
3. Selecciona tu número de teléfono
4. En “Voice Configuration”, establece la URL del webhook en la ruta de API de tu servidor (por ejemplo, https://your-ngrok-url.ngrok.app/twilio/inbound)
5. Establece el método HTTP en POST

Limitaciones

Al utilizar la ruta de API para registrar llamadas en lugar de la integración nativa:

• Sin transferencias de llamadas: La funcionalidad de transferencia no está disponible, ya que ElevenLabs no tiene acceso a tus credenciales de Twilio
• Configuración manual: Debes configurar los formatos de audio y gestionar tú mismo el enrutamiento de TwiML
• Sin importación al panel: Los números de teléfono registrados de esta forma no aparecen en el panel de números de teléfono de ElevenLabs