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 函式會將呼叫者以交接資訊作為任務屬性加入 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>撥打語音智慧體。