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 函式會將呼叫者以交接資訊作為任務屬性加入 Flex 佇列,並依交接 ID 查詢摘要。查詢會在函式中執行,因為 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 金鑰保留在函式的環境變數中。其他欄位請參閱 查詢已交接的通話。

測試

撥打會回傳上述 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> 撥打語音智慧體。