Open in
從 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。- 以相同方式加入更多背景資料,例如
&X-Account-Id=12345。在 TwiML 內,請將&寫成&,因為未逸出的&並非有效 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>撥打智能體。