---
title: "從 Twilio 連線"
description: "透過 SIP 使用 CallSid 將 Twilio 通話傳送至 ThunderPhone 智慧體，並透過 referUrl 搭配轉接位址中的交接資訊將通話轉回。"
---

你的 TwiML 會透過標頭中的通話 `CallSid` 撥打智慧體的 SIP 位址。
當來電者需要真人服務時，智慧體會傳送 SIP `REFER`，Twilio 會將內含交接資訊的
轉接位址傳遞給你的 `referUrl` 處理常式，而處理常式回傳的 TwiML 會決定來電者要前往何處，例如 Flex 佇列。

## 開始前

- ThunderPhone 智慧體與組織的 [API 金鑰](/zh-Hant/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-Hant/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 和意圖。新增此轉接號碼（請參閱
[新增轉接號碼](/zh-Hant/guides/contact-centers/overview)
和[轉接位址中的標頭](/zh-Hant/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 函式會將呼叫者以交接資訊作為任務屬性加入 Flex 佇列，並依交接 ID 查詢摘要。查詢會在函式中執行，因為 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 金鑰保留在函式的環境變數中。其他欄位請參閱
[查詢已交接的通話](/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>` 撥打語音智慧體。
