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

# Exotel 集成

## 概览

本指南介绍如何将 Exotel 电话号码直接连接到 ElevenAgents。通过此集成，你可以继续使用现有的 Exotel 号码和基础设施，同时利用 ElevenLabs 先进的语音 AI 功能处理呼入和呼出电话。

## 集成方式

Exotel 集成使用两个 Exotel 功能：

1. **Voicebot applet（呼入 + 呼出媒体）**：Exotel 上的 ExoML applet，可建立与 ElevenLabs 的 WebSocket 连接，并双向传输通话音频。
2. **Connect API（呼出拨号）**：对于呼出电话，ElevenLabs 会使用 API Key 和 API Token 调用 Exotel 的 `Calls/connect.json` 端点。Exotel 会拨打目标号码，接通后通过同一个 Voicebot applet 将音频路由至 ElevenLabs。

对于**呼入**电话，Exotel 会将来电路由到你分配给该号码的 Voicebot applet，再由其建立与 ElevenLabs 的 WebSocket 连接。

对于**呼出**电话，ElevenLabs 会通过 Connect API 发起通话，Exotel 随后通过 Voicebot applet 回接通话。

## 前提条件

设置 Exotel 集成前，请确保具备：

1. 一个已启用且至少配置了 1 个电话号码的 [Exotel 账户](https://exotel.com/)。
2. 对 Exotel 控制台 [my.exotel.com](https://my.exotel.com)（新加坡）或 [my.exotel.in](https://my.exotel.in)（孟买）的管理员访问权限。
3. 一个 ElevenLabs 账户，以及要关联该电话号码的 [智能体](/docs/zh/eleven-agents/quickstart)。

> **Note**
>
> Exotel 目前支持**新加坡**（`api.exotel.com`）和**孟买**
> （`api.in.exotel.com`）集群。请选择 Exotel 账户所在的集群。使用错误区域将导致身份验证失败。

## 在 Exotel 账户中启用 Voicebot

首先，请联系 **Exotel 支持团队**，请他们：

1. 为账户**启用 Voicebot applet**。该功能默认受限，在账户完成配置前不会显示在 App Bazaar 中。
2. **配置所需的通道数（并发通话数）**。这决定 Exotel 允许账户同时运行的 Voicebot 通话上限。请根据预期流量高峰确定数量。

> **Warning**
>
> 此步骤通常需要 1 到 2 个工作日。请在开始其余设置前提前进行。

## ElevenLabs WebSocket 端点

需要将 Exotel Voicebot applet 配置为向以下 WebSocket URL 传输音频。

| 环境        | WebSocket URL                                                        |
| --------- | -------------------------------------------------------------------- |
| 默认（美国/国际） | `wss://api.elevenlabs.io/v1/convai/conversation/exotel`              |
| 欧盟数据驻留    | `wss://api.eu.residency.elevenlabs.io/v1/convai/conversation/exotel` |
| 印度数据驻留    | `wss://api.in.residency.elevenlabs.io/v1/convai/conversation/exotel` |

> **Info**
>
> 如果 ElevenLabs 账户位于独立的数据驻留环境（欧盟或印度），必须使用对应的数据驻留 URL。了解更多[数据 驻留](/docs/zh/overview/administration/data-residency)信息。

## 在 Exotel 中设置

#### 获取 Exotel 凭据

在 Exotel 控制台中，打开左侧的 **Monitor** 菜单，然后点击 **Developer**。这会打开 API 凭据页面，可在其中查看 Account SID、API Key 和 API Token。

![Exotel 侧边栏：Developer](/docs/_fern-img/ebe936f8cd0d1773a88bb4922a7642cf8c2f844f39eb4ee9ee04eab50ecfa6c4.webp)

需要以下 4 个值：

* **Account SID**：Exotel 账户 SID。
* **API Key**：Exotel API 凭据中的用户名部分。
* **API Token**：Exotel API 凭据中的密码部分。请妥善保密。
* **区域（API 子域名）**：Exotel 账户所在的集群，即 `api.exotel.com`（新加坡）或 `api.in.exotel.com`（孟买）。查看 Developer 页面中任意 API URL 的主机名即可确认。

ElevenLabs 在调用 Exotel Connect API 进行呼出拨号时，会使用 API Key + API Token 进行 HTTP Basic Auth。

#### 在 App Bazaar 中创建 Voicebot applet

1. 在 Exotel 控制台中，打开左侧的 **Manage** 菜单，然后点击 **App Bazaar**。

   ![Exotel 侧边栏：App Bazaar](/docs/_fern-img/1e50c6687044e4fea1e6e636bc2db8a4a481c87eb44cdfc8019cff20bd1fe363.webp)

2. 点击 **Create / Add New Flow**，为应用指定描述性名称（例如 `ElevenLabs`），然后点击 **OK**。

   ![Exotel：Add New Flow 对话框](/docs/_fern-img/928f17d1351f93e7a9bd60d92498dde8b24d350686cf273be146e9d315927704.webp)

3. 在右侧 applet 面板中，将 **Voicebot** applet 拖到 **Call Start** 画布上。

   ![突出显示 Voicebot 的 Exotel applet
   面板](/docs/_fern-img/d19a0e66925d5931cd8f9eae7a1264b8a0e259d07736564cab4e1e894401c508.webp)

4. 打开 Voicebot applet 配置，将数据驻留环境对应的 ElevenLabs WebSocket URL 粘贴到 **URL** 字段（“Which bot you want to connect the enduser?” 字段）：

   ```
   wss://api.elevenlabs.io/v1/convai/conversation/exotel
   ```

   > **Info**
   >
   > 如果 ElevenLabs 账户使用欧盟或印度数据驻留，请使用上表中对应的数据驻留 URL（例如 `wss://api.in.residency.elevenlabs.io/v1/convai/conversation/exotel`），而非默认的 `api.elevenlabs.io`。

   除非有特定的录音或合规要求，其余 Voicebot 选项（“Record this?”、“Recording Channels”、“Recording Format”、“Encrypt DTMF”）可保留默认值。

   ![已配置 ElevenLabs WebSocket
   URL 的 Voicebot applet](/docs/_fern-img/bb375863bb02b0908786403c080280f4561f21d887fb490050d54ff4ec211794.webp)

5. **（可选）添加 Connect applet 以转接人工客服。** 如果不需要智能体将通话转接给人工客服，请跳过此步骤。若要使用智能体的 **Transfer to number** 工具，必须在流程中紧接 Voicebot applet 添加一个 **Connect** applet。

   在右侧 **Voice Applets** 面板中，将 **Connect** applet 拖入 Voicebot 的 **Next → Continue to the next applet** 槽位。

   ![突出显示 Connect 的 Voice Applets
   面板](/docs/_fern-img/1c325fc4ae992db551209b667519ffd75161b6a97ebf71ed6b751bbf26339faf.webp)

   在 Connect applet 配置中，选择 **Configure parameters dynamically by providing a URL**，并将数据驻留环境对应的 ElevenLabs connect-applet 端点粘贴到 **Primary URL**：

   ```
   https://api.elevenlabs.io/v1/convai/exotel/connect-applet
   ```

   ![已配置 ElevenLabs 动态
   URL 的 Connect applet](/docs/_fern-img/7ed4516ec33ea62830d9279a266ada20311741d0489fe2661dc528b8dbcbe126.webp)

   对应的数据驻留 URL 如下：

   | 环境        | Connect applet URL                                                       |
   | --------- | ------------------------------------------------------------------------ |
   | 默认（美国/国际） | `https://api.elevenlabs.io/v1/convai/exotel/connect-applet`              |
   | 欧盟数据驻留    | `https://api.eu.residency.elevenlabs.io/v1/convai/exotel/connect-applet` |
   | 印度数据驻留    | `https://api.in.residency.elevenlabs.io/v1/convai/exotel/connect-applet` |

   > **Info**
   >
   > 当智能体调用 **Transfer to number** 工具时，ElevenLabs 会将控制权交还给 Exotel，
   > Exotel 会请求此 URL 以获取要拨打的目标号码。请将 **Fallback URL** 留空，并保留其他默认设置。

6. 保存并发布 applet。

7. 记下 **Applet ID**（有时称为 **App ID**）。可在 ExoML 编辑器的 URL 中（例如 `.../exoml/start_voice/12345`）或 App 列表中找到。导入号码到 ElevenLabs 时需要使用它。

> **Note**
>
> Voicebot applet 同时处理呼入和呼出通话。每个账户只需一个 applet，导入到 ElevenLabs 的所有电话号码都可共用。

#### 将流程分配给电话号码（仅呼入）

保存并发布上一步的 ExoML 流程。然后将一个 Exotel 电话号码路由至该流程，使呼入电话进入 Voicebot applet。

1. 在 Exotel 控制台中，打开左侧的 **Manage** 菜单，然后点击 **ExoPhones**（位于 **App Bazaar** 下方）。

   ![Exotel 侧边栏：ExoPhones](/docs/_fern-img/30351173b2c2cfaa2ccd8d9e29e6aaba319ac3b5f2ee51d91a4f7913d3e218a4.webp)

2. 如果尚未拥有电话号码，请点击 **Buy a number**，先购买所需国家/地区的号码。

3. 找到要与 ElevenLabs 智能体配合使用的号码。在其 **Installed App** 列中，打开下拉菜单并选择上一步创建的流程（例如 **ElevenLabs**）。

   ![ExoPhones：为电话号码分配 Installed App](/docs/_fern-img/5ed6b42794bb00f330dd52d50a5831622e3156955d59adb1ca64b746d1ec7d2b.webp)

4. 保存配置。该号码的来电现在会直接路由至 Voicebot applet，并传输到 ElevenLabs。

> **Note**
>
> 如果该号码仅用于呼出电话，可以跳过此步骤。呼出电话由 ElevenLabs 通过 Connect API 拨打，不依赖 **Installed App** 分配。

## 在 ElevenLabs 中设置

#### 导入 Exotel 电话号码

在 ElevenAgents 控制台中，前往 [**Phone Numbers**](https://elevenlabs.io/app/agents/phone-numbers) 标签页。点击 **+ Import number**，然后从下拉菜单中选择 **From Exotel**。

![ElevenAgents：Import number 下拉菜单中已选择 From Exotel](/docs/_fern-img/2a62cf9f6b63914c5688da5f58515168fa1ff39b8602f70fea7a1ff257bb6918.webp)

填写以下字段：

* **Label**：描述性名称（例如 `Support Line`）。
* **Phone number**：E.164 格式的 Exotel 号码（例如 `+918048961234`）。
* **Exotel Account SID**：使用上方步骤 1 中的值。
* **Exotel API Key**：使用上方步骤 1 中的值。
* **Exotel API Token**：使用上方步骤 1 中的值（将存储为工作区密钥）。
* **Region**：选择与 Exotel 集群匹配的 `Singapore (api.exotel.com)` 或 `Mumbai (api.in.exotel.com)`。
* **Voicebot Applet ID**：使用上方步骤 2 中的 App ID。

点击 **Import** 保存号码。ElevenLabs 会向 Exotel 验证凭据，并将 API token 存储为工作区密钥。

#### 分配智能体

导入号码后，从 **Phone Numbers** 列表中打开该号码，并在 **Assigned agent** 下拉菜单中选择处理呼入电话的智能体。

> **Note**
>
> 呼入电话要求在 Exotel 端将 Voicebot applet 分配给该号码（参见上一节）。仅呼出的设置无需呼入分配。

#### 测试呼入电话

使用任意电话拨打 Exotel 号码。Exotel 会将通话路由到 Voicebot applet，后者会建立与 ElevenLabs 的 WebSocket 连接。智能体将接听并开始对话。

> **Tip**
>
> 在 [Calls History 控制台](https://elevenlabs.io/app/agents/history)中监控通话，确认所有功能均正常运行。

## 发起呼出电话

导入的 Exotel 号码也可以发起呼出电话。接收方接听后，智能体会拨打其电话号码并开始对话。

#### 发起呼出电话

在 [**Phone Numbers**](https://elevenlabs.io/app/agents/phone-numbers) 标签页中，找到 Exotel 号码并点击 **Outbound call** 按钮。

#### 配置通话

在 Outbound Call 弹窗中：

1. 选择处理对话的智能体。
2. 输入接收方的 E.164 格式电话号码。
3. 点击 **Send Test Call** 发起通话。

ElevenLabs 会使用已存储的凭据调用 Exotel Connect API。Exotel 会拨打接收方号码，并在通话接通后通过 Voicebot applet 回传音频。

> **Note**
>
> 发起呼出电话时，智能体是对话发起方，因此请确保已为智能体配置合适的首条消息。

如需通过编程方式而非控制台触发呼出电话，请使用 [通过 Exotel 发起呼出电话](/docs/zh/api-reference/exotel/outbound-call)端点。API 参考文档包含请求架构和可直接使用的 SDK 代码片段。

## 智能体配置要求

Voicebot applet 以 **8 kHz PCM** 传输音频。ElevenLabs 平台会自动处理音频格式转换，**无需**更改智能体的 TTS 或输入音频设置。

## 电话号码格式

电话号码以 E.164 格式存储（例如 `+918048961234`）。导入印度 Exotel 号码时，如果本地通常写作 `08048961234` 或 `8048961234`，请填写 `+918048961234`。ElevenLabs 会拒绝以不同格式重复导入相同号码。

## 通话转接

可以在智能体上配置 **Transfer to number** 工具，将通话从智能体转回 Exotel。该工具触发后，ElevenLabs 会结束 Voicebot 通话段，Exotel 会从串联的 **Connect** applet 动态 URL 获取目标号码，然后拨打该号码。

要实现此功能，需要**同时**具备：

1. 在 ExoML 流程中紧接 Voicebot applet 配置可选的 **Connect applet**（参见[在 Exotel 中设置](#setup-on-exotel)的步骤 5）。
2. 在智能体上配置 **Transfer to number** 工具。参阅[智能体转接指南](/docs/zh/eleven-agents/customization/tools/system-tools/transfer-to-number)。

如果流程中没有 Connect applet，智能体的转接尝试将失败，因为 Voicebot 结束后 Exotel 没有可路由通话的目标。

## 故障排除

#### 发起呼出电话时出现 \`exotel_connect_failed\` 错误

ElevenLabs 从 Exotel Connect API 收到了非 200 响应。最常见的原因包括：

* **Region** 错误。请确保导入时选择的区域与账户所在 Exotel 集群相符（`Singapore` 或 `Mumbai`）。
* **API Key** 或 **API Token** 无效。请在 Exotel **API Settings** 页面重新检查凭据，并使用正确值重新导入号码。
* **Account SID** 与 API Key / Token 对不匹配。
* 目标号码不是 E.164 格式。

#### 呼入电话未到达智能体

* 确认 Voicebot applet 的 **URL** 字段与数据驻留环境对应的 ElevenLabs WebSocket 端点完全一致（包括 `wss://`）。
* 确认 Exotel **电话号码**已路由到包含 Voicebot applet 的 ExoML 应用（Exotel 控制台、ExoPhones、该号码、Installed App）。
* 在 ElevenLabs 中，确认该电话号码已在 **Phone Numbers** 标签页中分配智能体。

#### 导入时出现 \`Applet ID\` 不匹配错误

**Voicebot Applet ID** 字段需要 ExoML 编辑器 URL 中的数字 App ID（例如，对于 `.../exoml/start_voice/12345`，ID 是 `12345`）。不要粘贴完整 URL，仅使用 ID。

#### 以不同格式重复导入电话号码

ElevenLabs 会在存储前将 Exotel 号码标准化为 E.164，并对 `(provider, phone_number)` 强制唯一性。如果之前以非 E.164 格式导入过相同号码，请先删除旧条目，再以 E.164 格式重新导入。

## 实用链接

* [Exotel 呼出电话 API 参考文档](/docs/zh/api-reference/exotel/outbound-call)
* [Exotel API 文档](https://developer.exotel.com/api/)
* [Exotel Voicebot applet 参考文档](https://support.exotel.com/support/solutions/articles/3000099826)
* [ElevenAgents 电话号码控制台](https://elevenlabs.io/app/agents/phone-numbers)