---
title: "从 Twilio 连接"
description: "通过 SIP 使用 CallSid 将 Twilio 通话发送至 ThunderPhone 智能体，并通过您的 referUrl 将其接回，交接信息位于转接地址中。"
---

您的 TwiML 会在标头中携带通话的 `CallSid`，拨打智能体的 SIP 地址。
当来电者需要转接人工时，智能体会发送 SIP `REFER`，Twilio 会将包含转接信息的转接地址传递给您的 `referUrl` 处理程序，而您的处理程序返回的 TwiML 将决定来电者的去向，例如 Flex 队列。

## 开始前

- 一个 ThunderPhone 智能体和一个组织[API 密钥](/zh/guides/api-keys)。
- Twilio Programmable Voice，以及可用于提供 TwiML 和 `referUrl`
  处理程序的位置：您自己的服务器，或 TwiML Bin 和 Twilio Function。Flex 为可选项。

## 1. 创建 SIP 端点

Twilio 的 `<Sip>` 需要用户名和密码，因此请使用标准端点：

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 12, "name": "Twilio"}'
```

请立即保存响应中的 `password`；它只会显示一次。如需同时仅接受来自 Twilio 的通话，请参阅
[限制来源 IP](/zh/guides/sip-addresses)。

## 2. 携带上下文发送通话

对于您要交给智能体处理的通话，请返回以下 TwiML：

```xml
<Response>
  <Dial answerOnBridge="true" referUrl="https://YOUR_SERVER/thunderphone-refer">
    <Sip username="tp409667538f83" password="YOUR_ENDPOINT_PASSWORD">sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tls?X-Call-ID={{CallSid}}</Sip>
  </Dial>
</Response>
```

- `;transport=tls` 很重要：除非另行指定，否则 Twilio 使用 UDP。
- `X-Call-ID` 用于携带 `CallSid`。Twilio 未记录其自有的通话 ID 标头，
  因此请添加此标头：ThunderPhone 会将其存储为该通话的
  `external_call_id`。`{{CallSid}}` 可在 TwiML Bin 中使用；如果您使用自己的服务器，
  请写入传入请求的 `CallSid`。
- 以相同方式添加更多上下文，例如 `&amp;X-Account-Id=12345`。在
  TwiML 中，请将 `&` 写为 `&amp;`，因为单独的 `&` 是无效 XML。每个值都会作为变量传递到
  提示词中，此处为 `{{sip_x_account_id}}`。Twilio 允许使用 `x-` 标头
  和经过百分比编码的 `User-to-User`，整个 URI 不超过 255 个字符，
  标头不超过 1,024 个字符。
- `referUrl` 允许 Twilio 接受智能体的 `REFER`；没有它，转接将因
  [错误 13802](https://www.twilio.com/docs/api/errors/13802) 而失败。
  `answerOnBridge="true"` 会让来电者保持连接，直到新目标接听，
  因此失败的转接可以回退处理。

Studio 的 **连接通话至** 小部件未记录自定义标头或
`referUrl`，因此请从 Studio 将通话交给此 TwiML，例如使用
**TwiML 重定向** 小部件。

## 3. 接回通话

智能体通过 `REFER` 发起转接，其转接地址中包含交接
ID 和意图。添加此转接号码（请参阅
[添加转接号码](/zh/guides/contact-centers/overview)
和[转接地址中的标头](/zh/guides/call-transfers)）：

```json
{
  "name": "Twilio support",
  "number": "sip:support@acme.sip.twilio.com",
  "headers": {"X-Handoff-Id": "{{handoff_id}}", "X-Handoff-Intent": "{{handoff_intent}}"},
  "headers_in_uri": true
}
```

Twilio 会将整个地址作为 `ReferTransferTarget` 发送到您的 `referUrl`，例如
`<sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>`。
您的处理程序从中读取标头，并返回用于确定来电者下一步转往何处的 TwiML。地址的用户部分（`support`）可由您自行选择，因此您可以为每个目的地添加一个转接号码，并据此进行路由。

此 Twilio Function 会将来电者加入 Flex 队列，并将交接信息作为任务
属性，同时按交接 ID 查找摘要。由于 Studio 的 HTTP Request 小组件无法发送 `Authorization`
标头，因此查找操作在 Function 中执行：

```js
exports.handler = async (context, event, callback) => {
  const target = (event.ReferTransferTarget || "").replace(/^<|>$/g, "");
  const params = new URLSearchParams(target.split("?")[1] || "");
  const handoffId = params.get("X-Handoff-Id") || "";
  const attributes = { handoff_id: handoffId, intent: params.get("X-Handoff-Intent") || "" };

  if (handoffId) {
    const response = await fetch(
      "https://api.thunderphone.com/v1/calls/handoff?handoff_id=" + encodeURIComponent(handoffId),
      { headers: { Authorization: "Bearer " + context.THUNDERPHONE_API_KEY } }
    );
    if (response.ok) {
      const call = await response.json();
      attributes.summary = (call.handoff && call.handoff.summary) || "";
    }
  }

  const twiml = new Twilio.twiml.VoiceResponse();
  twiml.enqueue({ workflowSid: context.FLEX_WORKFLOW_SID }).task({}, JSON.stringify(attributes));
  callback(null, twiml);
};
```

将 API 密钥保存在 Function 的环境变量中。有关其他字段，请参阅
[查找已交接的通话](/api-reference/calls#look-up-a-handed-off-call)。

## 测试

致电一个返回上述 TwiML 的 Twilio 号码，请求智能体为您转接人工人员，
并确认您的 `referUrl` 处理程序收到同时包含两个标头的 `ReferTransferTarget`，
且来电者已进入队列。然后使用
`GET /v1/calls/{call_id}` 打开该通话：`external_call_id` 应为 `CallSid`。

## 限制

- Twilio 将 `Refer-To` 限制为 256 个字符。ThunderPhone 将地址控制在
  254 个字符以内，并会省略无法容纳的标头，因此请保持标头名称和值简短。
- Twilio 未记录如何读取 `BYE` 上的标头，因此回转无法将交接信息带回 Twilio。请使用上述 `REFER`。
- Twilio 不接受通过 `<Conference>` 或
  `<Queue>` 连接的通话上的 `REFER`，因此请按上述方式使用 `<Dial><Sip>` 拨打智能体。
