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

# Registrar llamadas de Twilio

> **Avanzado**
>
> Esta guía explica un patrón de integración avanzado para desarrolladores que necesitan tener control total sobre su
> infraestructura de Twilio. Para una configuración más sencilla, considera usar la [integración nativa de Twilio](/docs/es/eleven-agents/phone-numbers/twilio-integration/native-integration), que
> gestiona la configuración automáticamente.

## Cuándo usar cada enfoque

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

| Función                        | Integración nativa     | Registrar llamada  |
| ------------------------------ | ---------------------- | ------------------ |
| Facilidad de configuración     | Más sencilla           | Más compleja       |
| Transferencias de llamadas     | Compatible             | No compatible      |
| Lógica personalizada de Twilio | Limitada               | Control total      |
| Gestión de números de teléfono | A través de ElevenLabs | A través de Twilio |

## 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](https://www.twilio.com/docs/voice/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

> **Note**
>
> Al utilizar la ruta de API para registrar llamadas, la funcionalidad de transferencia de llamadas no está disponible, ya que ElevenLabs
> no tiene acceso directo a las credenciales de tu cuenta de Twilio.

## Requisitos previos

* Una [cuenta de ElevenLabs](https://elevenlabs.io)
* Un agente conversacional de ElevenLabs configurado ([crea uno aquí](/docs/es/eleven-agents/quickstart))
* Una [cuenta de Twilio](https://www.twilio.com/try-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](#agent-configuration))

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

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

![](/docs/_fern-img/b37196c36051755fb0b10a99b393501ec11573f963c83b6b092e1b5926c6617f.webp)

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

![](/docs/_fern-img/ec87531c38e26f2293b90126f1b91ee9acb4cc677c6f3e83a6e1b6029743d3f7.webp)

## Referencia de la API

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

| Parámetro                             | Tipo   | Obligatorio | Descripción                                                      |
| ------------------------------------- | ------ | ----------- | ---------------------------------------------------------------- |
| `agent_id`                            | string | Sí          | El ID del agente que gestionará la llamada                       |
| `from_number`                         | string | Sí          | El número de teléfono de quien llama                             |
| `to_number`                           | string | Sí          | El número de teléfono de destino                                 |
| `direction`                           | string | No          | Dirección de la llamada: `inbound` (predeterminada) o `outbound` |
| `conversation_initiation_client_data` | object | No          | Variables dinámicas y anulaciones de configuración               |

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

## Implementación

```python
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)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import express from "express";

const app = express();
app.use(express.urlencoded({ extended: true }));

const elevenlabs = new ElevenLabsClient();
const AGENT_ID = process.env.ELEVENLABS_AGENT_ID;

// Handle incoming Twilio calls
app.post("/twilio/inbound", async (req, res) => {
  const { From: fromNumber, To: toNumber } = req.body;

  // Register the call with ElevenLabs
  const twiml = await elevenlabs.conversationalAi.twilio.registerCall({
    agentId: AGENT_ID,
    fromNumber,
    toNumber,
    direction: "inbound",
    conversationInitiationClientData: {
      dynamicVariables: {
        caller_number: fromNumber,
      },
    },
  });

  // Return the TwiML directly to Twilio
  res.type("application/xml").send(twiml);
});

app.listen(8000, () => {
  console.log("Server running on 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:

```python
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")
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import Twilio from "twilio";

// Initialize clients
const twilioClient = new Twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);
const elevenlabs = new ElevenLabsClient();
const AGENT_ID = process.env.ELEVENLABS_AGENT_ID;

// Initiate an outbound call
async function initiateOutboundCall(toNumber: string) {
  const call = await twilioClient.calls.create({
    from: process.env.TWILIO_PHONE_NUMBER,
    to: toNumber,
    url: "https://your-server.com/twilio/outbound",
  });
  return call.sid;
}

// Handle the Twilio webhook for outbound calls
app.post("/twilio/outbound", async (req, res) => {
  const { From: fromNumber, To: toNumber } = req.body;

  const twiml = await elevenlabs.conversationalAi.twilio.registerCall({
    agentId: AGENT_ID,
    fromNumber,
    toNumber,
    direction: "outbound",
  });

  res.type("application/xml").send(twiml);
});
```

## Personaliza las conversaciones

Utiliza el parámetro `conversation_initiation_client_data` para pasar variables dinámicas y anular la configuración del agente:

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

> **Info**
>
> Para más información sobre las variables dinámicas y las anulaciones, consulta la documentación sobre
> [variables dinámicas](/docs/es/eleven-agents/customization/personalization/dynamic-variables) y
> [anulaciones](/docs/es/eleven-agents/customization/personalization/overrides).

## Configuración de Twilio

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

#### Crea una URL pública

Para el desarrollo local, utiliza [ngrok](https://ngrok.com) para exponer tu servidor:

```bash
ngrok http 8000
```

#### Configura tu número de Twilio

1. Ve a la [consola de Twilio](https://console.twilio.com)
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

![](/docs/_fern-img/510d09d492b0c6ac9966f8fe39a9da685df79e8108f6fbc55fe502f48f650084.webp)

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