部署电话Twilio

注册 Twilio 通话

使用自己的 Twilio 基础设施将通话连接到 ElevenLabs 智能体。

高级

本指南介绍一种高级集成模式，适用于需要完全控制 Twilio 基础设施的开发者。如需更简单的设置，建议使用会自动处理配置的 原生 Twilio 集成。

何时使用各方案

开始前，请了解原生集成和注册通话方案之间的权衡：

功能原生集成注册通话
设置难度更简单更复杂
通话转接支持不支持
自定义 Twilio 逻辑有限完全控制
电话号码管理通过 ElevenLabs通过 Twilio

概述

注册通话端点允许你在使用 ElevenLabs 智能体进行对话的同时，继续使用自己的 Twilio 基础设施。你无需将 Twilio 号码导入 ElevenLabs，而是可以完全控制 Twilio 设置，并使用 ElevenLabs API 注册通话、接收用于将通话连接到智能体的 TwiML。

以下情况适合使用此方案：

  • 需要保留现有的 Twilio 基础设施和 workflow
  • 希望以编程方式控制通话路由和处理
  • 在连接智能体前，需要通过自定义 Twilio 逻辑处理复杂通话流程
  • 需要将 ElevenLabs 智能体集成到现有电话系统

工作原理

  1. 服务器通过 Twilio 接收来电或发起去电
  2. 服务器调用 ElevenLabs 注册通话端点，并提供智能体和通话详情
  3. ElevenLabs 返回通过 WebSocket 将通话连接到智能体的 TwiML
  4. 将此 TwiML 返回给 Twilio 以建立连接

使用注册通话端点时，无法使用通话转接功能，因为 ElevenLabs 无法直接访问 Twilio 账户凭据。

前提条件

智能体配置

使用注册通话端点前，请将智能体配置为使用 Twilio 支持的正确音频格式。

1

配置 TTS 输出

  1. 前往智能体设置
  2. 打开 Voice 部分
  3. 从下拉菜单中选择“μ-law 8000 Hz”
2

设置输入格式

  1. 前往智能体设置
  2. 打开 Advanced 部分
  3. 为输入格式选择“μ-law 8000 Hz”

API 参考

注册通话端点接受以下参数：

参数类型必填说明
agent_idstring是处理通话的智能体 ID
from_numberstring是来电号码
to_numberstring是目标电话号码
directionstring否通话方向：inbound（默认）或 outbound
conversation_initiation_client_dataobject否动态变量和配置覆盖

该端点会返回应直接传递给 Twilio 的 TwiML。

实现

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)

去电

对于去电，请通过 Twilio 发起通话，并将 webhook URL 指向服务器；服务器随后向 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")

个性化对话

使用 conversation_initiation_client_data 参数传递动态变量并覆盖智能体配置：

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

有关动态变量和覆盖的更多信息，请参阅动态变量和覆盖文档。

Twilio 配置

将 Twilio 电话号码配置为指向服务器：

1

创建公共 URL

本地开发时，可使用 ngrok 公开服务器：

ngrok http 8000
2

配置 Twilio 号码

  1. 前往 Twilio Console
  2. 前往 Phone Numbers > Manage > Active numbers
  3. 选择电话号码
  4. 在“Voice Configuration”下，将 webhook URL 设为服务器端点（例如 https://your-ngrok-url.ngrok.app/twilio/inbound）
  5. 将 HTTP 方法设为 POST

限制

使用注册通话端点而非原生集成时：

  • 不支持通话转接：由于 ElevenLabs 无法访问 Twilio 凭据，因此无法使用转接功能
  • 需手动配置：必须自行配置音频格式并处理 TwiML 路由
  • 不会导入控制台：以此方式注册的电话号码不会显示在 ElevenLabs 电话号码控制台中