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

# Registrare chiamate Twilio

> **Avanzato**
>
> Questa guida illustra un modello di integrazione avanzato per gli sviluppatori che necessitano del pieno controllo della propria
> infrastruttura Twilio. Per una configurazione più semplice, valuta l'[integrazione Twilio nativa](/docs/it/eleven-agents/phone-numbers/twilio-integration/native-integration), che
> gestisce automaticamente la configurazione.

## Quando usare ciascun approccio

Prima di iniziare, comprendi i compromessi tra l'integrazione nativa e l'approccio di registrazione delle chiamate:

| Funzionalità                 | Integrazione nativa | Registrazione chiamate |
| ---------------------------- | ------------------- | ---------------------- |
| Facilità di configurazione   | Più semplice        | Più complessa          |
| Trasferimenti di chiamata    | Supportati          | Non supportati         |
| Logica Twilio personalizzata | Limitata            | Controllo completo     |
| Gestione dei numeri          | Tramite ElevenLabs  | Tramite Twilio         |

## Panoramica

L'endpoint di registrazione delle chiamate ti consente di usare la tua infrastruttura Twilio sfruttando al contempo gli agenti ElevenLabs per la conversazione. Invece di importare il tuo numero Twilio in ElevenLabs, mantieni il pieno controllo della configurazione Twilio e usi l'API ElevenLabs per registrare le chiamate e ricevere [TwiML](https://www.twilio.com/docs/voice/twiml) per connetterle ai tuoi agenti.

Questo approccio è ideale quando:

* Devi mantenere l'infrastruttura e i workflow Twilio esistenti
* Vuoi il controllo programmatico sul routing e la gestione delle chiamate
* Hai flussi di chiamata complessi che richiedono una logica Twilio personalizzata prima della connessione a un agente
* Devi integrare gli agenti ElevenLabs in un sistema di telefonia esistente

## Come funziona

1. Il tuo server riceve una chiamata in entrata o avvia una chiamata in uscita tramite Twilio
2. Il tuo server chiama l'endpoint ElevenLabs di registrazione delle chiamate con i dettagli dell'agente e della chiamata
3. ElevenLabs restituisce TwiML che connette la chiamata al tuo agente tramite WebSocket
4. Restituisci questo TwiML a Twilio per stabilire la connessione

> **Note**
>
> Quando usi l'endpoint di registrazione delle chiamate, la funzionalità di trasferimento di chiamata non è disponibile perché ElevenLabs
> non ha accesso diretto alle credenziali del tuo account Twilio.

## Prerequisiti

* Un [account ElevenLabs](https://elevenlabs.io)
* Un agente conversazionale ElevenLabs configurato ([creane uno qui](/docs/it/eleven-agents/quickstart))
* Un [account Twilio](https://www.twilio.com/try-twilio) con un numero di telefono attivo
* Il tuo agente configurato con il formato audio μ-law 8000 Hz (consulta la [configurazione dell'agente](#agent-configuration))

## Configurazione dell'agente

Prima di usare l'endpoint di registrazione delle chiamate, configura il tuo agente in modo che utilizzi il formato audio corretto supportato da Twilio.

#### Configura l'output TTS

1. Vai alle impostazioni del tuo agente
2. Vai alla sezione Voice
3. Seleziona "μ-law 8000 Hz" dal menu a discesa

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

#### Imposta il formato di input

1. Vai alle impostazioni del tuo agente
2. Vai alla sezione Advanced
3. Seleziona "μ-law 8000 Hz" come formato di input

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

## Riferimento API

L'endpoint di registrazione delle chiamate accetta i seguenti parametri:

| Parametro                             | Tipo   | Obbligatorio | Descrizione                                              |
| ------------------------------------- | ------ | ------------ | -------------------------------------------------------- |
| `agent_id`                            | string | Sì           | L'ID dell'agente che gestirà la chiamata                 |
| `from_number`                         | string | Sì           | Il numero di telefono del chiamante                      |
| `to_number`                           | string | Sì           | Il numero di telefono di destinazione                    |
| `direction`                           | string | No           | Direzione chiamata: `inbound` (predefinita) o `outbound` |
| `conversation_initiation_client_data` | object | No           | Variabili dinamiche e override della configurazione      |

L'endpoint restituisce TwiML che devi passare direttamente a Twilio.

## Implementazione

```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");
});
```

## Chiamate in uscita

Per le chiamate in uscita, avvia la chiamata tramite Twilio e indirizza l'URL del webhook al tuo server, che poi registra la chiamata con 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);
});
```

## Personalizzazione delle conversazioni

Usa il parametro `conversation_initiation_client_data` per passare variabili dinamiche ed eseguire l'override della configurazione dell'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**
>
> Per ulteriori informazioni sulle variabili dinamiche e sugli override, consulta la documentazione su
> [variabili dinamiche](/docs/it/eleven-agents/customization/personalization/dynamic-variables) e
> [override](/docs/it/eleven-agents/customization/personalization/overrides).

## Configurazione Twilio

Configura il tuo numero di telefono Twilio affinché punti al tuo server:

#### Crea un URL pubblico

Per lo sviluppo locale, usa [ngrok](https://ngrok.com) per esporre il tuo server:

```bash
ngrok http 8000
```

#### Configura il tuo numero Twilio

1. Vai alla [Twilio Console](https://console.twilio.com)
2. Vai a Phone Numbers > Manage > Active numbers
3. Seleziona il tuo numero di telefono
4. In "Voice Configuration", imposta l'URL del webhook sull'endpoint del tuo server (ad esempio, `https://your-ngrok-url.ngrok.app/twilio/inbound`)
5. Imposta il metodo HTTP su POST

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

## Limitazioni

Quando usi l'endpoint di registrazione delle chiamate invece dell'integrazione nativa:

* **Nessun trasferimento di chiamata**: la funzionalità di trasferimento non è disponibile perché ElevenLabs non ha accesso alle tue credenziali Twilio
* **Configurazione manuale**: devi configurare i formati audio e gestire autonomamente il routing TwiML
* **Nessuna importazione nella dashboard**: i numeri di telefono registrati in questo modo non vengono visualizzati nella dashboard dei numeri di telefono ElevenLabs