---
title: "從 Twilio 連接"
description: "透過 SIP 使用 CallSid 將 Twilio 通話轉接至 ThunderPhone 智能體，並透過 referUrl 將通話轉回，轉接地址中包含交接資訊。"
---

你的 TwiML 會以通話的 `CallSid` 作為標頭，撥號至智能體的 SIP 位址。
當來電者需要真人協助時，智能體會傳送 SIP `REFER`，Twilio 會將包含轉接資訊的轉接位址傳遞至你的 `referUrl` 處理器，而處理器回傳的 TwiML 會決定來電者的去向，例如 Flex 佇列。

## 開始前

- 一個 ThunderPhone 智能體及組織的 [API 金鑰](/yue/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 位址](/yue/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 並沒有記載其自有的 call-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 和意圖。加入此轉接號碼（參閱
[加入轉接號碼](/yue/guides/contact-centers/overview)
及[轉接地址內的標頭](/yue/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 查找摘要。查找操作會在 Function 中執行，因為
Studio 的 HTTP Request 小工具無法傳送 `Authorization`
標頭：

```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>` 撥打智能體。
