Registrare chiamate Twilio

Quando usare ciascun approccio

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

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

Prerequisiti

• Un account ElevenLabs
• Un agente conversazionale ElevenLabs configurato (creane uno qui)
• Un account Twilio con un numero di telefono attivo
• Il tuo agente configurato con il formato audio μ-law 8000 Hz (consulta la configurazione dell’agente)

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.

1

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

2

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

Riferimento API

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

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

Implementazione

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)

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:

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

Personalizzazione delle conversazioni

Usa il parametro conversation_initiation_client_data per passare variabili dinamiche ed eseguire l’override della configurazione dell’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"
    }
  }
}

Configurazione Twilio

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

1

Crea un URL pubblico

Per lo sviluppo locale, usa ngrok per esporre il tuo server:

ngrok http 8000

2

Configura il tuo numero Twilio

1. Vai alla Twilio Console
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

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