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 未记录其自有的通话 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 查找摘要。由于 Studio 的 HTTP Request 小组件无法发送 Authorization
标头,因此查找操作在 Function 中执行:
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>拨打智能体。