ThunderPhone v3 đã chính thức ra mắt.Tự đăng ký và sử dụng, chỉ từ 2¢/phút.Xem thông báo ra mắt

Contact centers

Kết nối từ Twilio

Gửi cuộc gọi Twilio đến một tác nhân AI ThunderPhone qua SIP bằng CallSid, rồi nhận lại qua referUrl của bạn với thông tin bàn giao trong địa chỉ chuyển cuộc gọi.

TwiML của bạn gọi đến địa chỉ SIP của tác nhân AI với CallSid của cuộc gọi trong một header. Khi người gọi cần gặp người, tác nhân AI gửi một SIP REFER, Twilio chuyển địa chỉ chuyển cuộc gọi kèm thông tin bàn giao đến trình xử lý referUrl của bạn, và TwiML mà trình xử lý trả về sẽ quyết định người gọi được chuyển đến đâu, chẳng hạn như hàng đợi Flex.

Trước khi bắt đầu

  • Một tác nhân AI ThunderPhone và khóa API của tổ chức.
  • Twilio Programmable Voice, cùng nơi để phục vụ TwiML và trình xử lý referUrl: máy chủ riêng của bạn, hoặc TwiML Bin và Twilio Function. Flex là tùy chọn.

1. Tạo endpoint SIP

<Sip> của Twilio nhận tên người dùng và mật khẩu, vì vậy hãy dùng endpoint tiêu chuẩn:

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"}'

Lưu ngay password từ phản hồi; giá trị này chỉ được hiển thị một lần. Để cũng chỉ chấp nhận cuộc gọi từ Twilio, hãy xem Giới hạn IP nguồn.

2. Gửi cuộc gọi kèm ngữ cảnh

Trả về TwiML này cho cuộc gọi bạn muốn chuyển cho tác nhân AI:

<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 rất quan trọng: Twilio sử dụng UDP nếu không được chỉ định khác.
  • X-Call-ID mang CallSid. Twilio không tài liệu hóa header call-id riêng, vì vậy hãy thêm header này: ThunderPhone lưu nó làm external_call_id của cuộc gọi. {{CallSid}} hoạt động trong TwiML Bin; từ máy chủ riêng của bạn, hãy ghi CallSid của yêu cầu đến.
  • Thêm ngữ cảnh khác theo cùng cách, chẳng hạn &amp;X-Account-Id=12345. Trong TwiML, viết & thành &amp;, vì & đơn lẻ là XML không hợp lệ. Mỗi giá trị đến prompt dưới dạng biến, ở đây là {{sip_x_account_id}}. Twilio cho phép header x- và User-to-User, được mã hóa phần trăm, với toàn bộ URI dưới 255 ký tự và header dưới 1.024 ký tự.
  • referUrl cho phép Twilio chấp nhận REFER của tác nhân AI; nếu không có, việc chuyển cuộc gọi sẽ thất bại với lỗi 13802. answerOnBridge="true" giữ người gọi được kết nối cho đến khi đích mới trả lời, để việc chuyển cuộc gọi thất bại có thể dùng phương án dự phòng.

Widget Kết nối cuộc gọi đến của Studio không tài liệu hóa header tùy chỉnh hoặc referUrl, vì vậy từ Studio hãy chuyển cuộc gọi đến TwiML này, chẳng hạn bằng widget Chuyển hướng TwiML.

3. Nhận lại cuộc gọi

Tác nhân AI chuyển cuộc gọi bằng REFER, trong đó địa chỉ chuyển tiếp chứa id và ý định bàn giao. Thêm số chuyển tiếp này (xem Thêm số chuyển tiếp và Header trong địa chỉ chuyển tiếp):

{
  "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 gửi toàn bộ địa chỉ đến referUrl của bạn dưới dạng ReferTransferTarget, ví dụ <sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>. Trình xử lý của bạn đọc các header từ đó và trả về TwiML cho điểm đến tiếp theo của người gọi. Phần người dùng của địa chỉ (support) do bạn chọn, vì vậy bạn có thể thêm một số chuyển tiếp cho mỗi đích đến và định tuyến theo số đó.

Twilio Function này đưa người gọi vào hàng đợi Flex với thông tin bàn giao làm thuộc tính tác vụ và tra cứu bản tóm tắt theo id bàn giao. Việc tra cứu chạy trong Function vì widget HTTP Request của Studio không thể gửi header 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);
};

Giữ API key trong biến môi trường của Function. Xem Tra cứu cuộc gọi đã bàn giao để biết các trường khác.

Kiểm tra

Gọi đến một số Twilio trả về TwiML ở trên, yêu cầu tác nhân AI chuyển cho một người, rồi kiểm tra rằng trình xử lý referUrl của bạn nhận được ReferTransferTarget với cả hai header và người gọi vào được hàng đợi. Sau đó mở cuộc gọi bằng GET /v1/calls/{call_id}: external_call_id phải là CallSid.

Giới hạn

  • Twilio giới hạn Refer-To ở 256 ký tự. ThunderPhone giữ địa chỉ ở mức 254 ký tự và bỏ qua header không vừa, vì vậy hãy giữ tên và giá trị header ngắn.
  • Twilio không có tài liệu về việc đọc header trên BYE, vì vậy một lượt trả về không thể mang thông tin bàn giao quay lại Twilio. Hãy sử dụng REFER như trên.
  • Twilio không chấp nhận REFER trên cuộc gọi được kết nối qua <Conference> hoặc <Queue>, vì vậy hãy gọi tác nhân AI bằng <Dial><Sip> như trên.