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 未记录其自有的通话 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 查找摘要。由于 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> 拨打智能体。