---
title: "Kết nối từ Twilio"
description: "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](/vi/guides/api-keys) 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:

```bash
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](/vi/guides/sip-addresses).

## 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:

```xml
<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](https://www.twilio.com/docs/api/errors/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](/vi/guides/contact-centers/overview)
và [Header trong địa chỉ chuyển tiếp](/vi/guides/call-transfers)):

```json
{
  "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`:

```js
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](/api-reference/calls#look-up-a-handed-off-call)
để 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.
