ThunderPhone v3 現已上線。自助開通,價格低至每分鐘 2¢。查看公告

Contact centers

從 Twilio 連接

透過 SIP 使用 CallSid 將 Twilio 通話轉接至 ThunderPhone 智能體,並透過 referUrl 將通話轉回,轉接地址中包含交接資訊。

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

開始前

  • 一個 ThunderPhone 智能體及組織的 API 金鑰。
  • Twilio Programmable Voice,以及可提供 TwiML 和 referUrl 處理器的環境:你自己的伺服器,或 TwiML Bin 與 Twilio Function。Flex 為選用項目。

1. 建立 SIP 端點

Twilio 的 <Sip> 需要使用者名稱及密碼,因此請使用標準端點:

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 位址。

2. 連同背景資料傳送通話

為要交由智能體處理的通話回傳以下 TwiML:

<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而失敗。answerOnBridge="true" 會令來電者保持連線,直至新目的地接聽,以便在轉接失敗時轉用備援流程。

Studio 的 將通話連接至 小工具並未記載自訂標頭或 referUrl,因此請從 Studio 將通話轉交至此 TwiML,例如使用 TwiML 重新導向 小工具。

3. 接回通話

智能體透過 REFER 進行轉接,而轉接地址會帶有交接 ID 和意圖。加入此轉接號碼(參閱 加入轉接號碼 及轉接地址內的標頭):

{
  "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 標頭:

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 的環境變數中。其他欄位請參閱 查找已交接的通話。

測試

致電一個會回傳以上 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> 撥打智能體。