Kết nối qua SIP (không cần số điện thoại)

Gửi cuộc gọi đến tác nhân AI ThunderPhone trực tiếp từ PBX, nhà mạng hoặc ứng dụng SIP của bạn, bằng URI SIP dùng một lần cho mỗi cuộc gọi hoặc địa chỉ SIP cố định.

Nếu hệ thống riêng của bạn đã xử lý số điện thoại (PBX, nền tảng trung tâm liên hệ hoặc tài khoản nhà mạng nơi bạn luân phiên số), bạn có thể gửi cuộc gọi đến một tác nhân AI ThunderPhone qua SIP thông thường. Bạn không cần nhập hoặc mua số trên ThunderPhone. Hệ thống của bạn gọi một địa chỉ SIP và tác nhân AI sẽ trả lời.

Có hai loại địa chỉ SIP:

Cả hai loại đều định tuyến đến một tác nhân AI trong tổ chức của bạn và đều xuất hiện trong lịch sử cuộc gọi như mọi cuộc gọi đến khác.

URI SIP theo cuộc gọi#

1. Đăng ký cuộc gọi#

curl -X POST https://api.thunderphone.com/v1/calls/register-sip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "to_number": "+14155550142",
    "variables": {"customer_name": "Ada"}
  }'

{
  "call_id": 862197007562,
  "sip_uri": "sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com",
  "expires_at": "2026-09-25T21:49:52Z",
  "agent_id": 12,
  "to_number": "+14155550142"
}

• to_number (tùy chọn) là số mà người gọi đã quay ở phía bạn. Số này được lưu là đích của cuộc gọi trong lịch sử cuộc gọi, và tác nhân AI sẽ nhìn thấy số đó là số của chính mình.
• variables (tùy chọn) điền vào {{placeholders}} trong prompt của tác nhân AI, giống như với cuộc gọi đi.
• call_id là id mà cuộc gọi sẽ có trong lịch sử cuộc gọi (GET /v1/calls/{call_id}) sau khi kết nối.

2. Gọi URI#

Gửi cuộc gọi đến sip_uri trong vòng 5 phút. URI chỉ hoạt động cho một cuộc gọi: sau khi một cuộc gọi đã dùng URI, URI đó sẽ không còn hiệu lực, kể cả khi cuộc gọi kết thúc nhanh.

Ví dụ, với Twilio, hãy trả về TwiML này cho cuộc gọi bạn muốn chuyển sang:

<Response>
  <Dial>
    <Sip>sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp</Sip>
  </Dial>
</Response>

Từ PBX, hãy gọi URI dưới dạng đích SIP. Không cần tên người dùng hoặc mật khẩu; token là thông tin xác thực, vì vậy hãy coi URI như mật khẩu cho đến khi URI được sử dụng.

Điểm cuối SIP (địa chỉ cố định)#

1. Tạo điểm cuối#

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": "Main PBX"}'

{
  "id": 7,
  "name": "Main PBX",
  "agent_id": 12,
  "sip_uri": "sip:agent-12-jhxmginwjx@sip.thunderphone.com",
  "username": "tp409667538f83",
  "password": "8mJ0…",
  "allowed_source_cidrs": [],
  "status": "active",
  "created_at": "2026-09-25T21:46:18Z"
}

2. Trỏ hệ thống của bạn đến điểm cuối#

Cấu hình một trunk SIP hoặc đích đến với:

Các cài đặt giao thức truyền tải và codec này cũng áp dụng cho URI theo từng cuộc gọi. Hai chi tiết mạng quan trọng cho cả hai loại địa chỉ:

• Tuân theo Record-Route. Sau INVITE đầu tiên, phần báo hiệu còn lại của cuộc gọi (ACK, ngắt cuộc gọi, chuyển cuộc gọi) sẽ đến máy chủ ThunderPhone cụ thể đã phản hồi, được nêu trong tiêu đề Record-Route (sip-1.thunderphone.com hoặc sip-2.thunderphone.com, hoặc địa chỉ IP của máy chủ). Nếu bạn hạn chế SIP đi ra, hãy cho phép các máy chủ này cùng với sip.thunderphone.com: 172.170.39.202 (sip), 13.86.104.121 (sip-1) và 20.80.98.90 (sip-2).
• Âm thanh đi theo đường khác. sip.thunderphone.com chỉ mang báo hiệu. Cho phép phương tiện (RTP) đến các địa chỉ và cổng trong phản hồi SDP.

Mọi cuộc gọi đến địa chỉ này đều đến tác nhân AI của điểm cuối, bất kể người gọi của bạn đã quay số nào ở phía bạn. Bạn không cần nhập số, nên việc xoay vòng số ở phía bạn không cần thay đổi gì trên ThunderPhone.

Truyền số đã quay (không bắt buộc)#

Để ghi lại số nào của bạn mà người gọi đã quay, hãy gửi số đó trong INVITE qua tiêu đề X-Original-To (ví dụ: X-Original-To: +14155550142) hoặc trong tiêu đề chuẩn Diversion. ThunderPhone lưu số đó làm đích đến của cuộc gọi.

Đích đến được chọn theo thứ tự sau: to_number được cung cấp khi đăng ký URI theo từng cuộc gọi, sau đó là số trong X-Original-To, rồi đến số trong Diversion. Nếu không mục nào cung cấp số, đích đến sẽ hiển thị là sip:agent-12-jhxmginwjx (địa chỉ của điểm cuối) đối với một điểm cuối, hoặc sip:call đối với URI theo từng cuộc gọi.

Với Twilio, bạn có thể thêm tiêu đề vào URI SIP: sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tcp?X-Original-To=%2B14155550142.

Hạn chế IP nguồn (không bắt buộc)#

Đặt allowed_source_cidrs để chỉ chấp nhận cuộc gọi từ các địa chỉ báo hiệu của riêng bạn, ngoài tên người dùng và mật khẩu:

curl -X PATCH https://api.thunderphone.com/v1/sip-endpoints/7 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_source_cidrs": ["203.0.113.0/28"]}'

Cuộc gọi từ bất kỳ địa chỉ nào khác sẽ bị từ chối trước khi đến tác nhân AI. Dùng các địa chỉ mà hệ thống của bạn gửi báo hiệu SIP từ đó (đối với nhà cung cấp như Twilio, hãy dùng các dải IP báo hiệu được công bố), không phải địa chỉ phương tiện của bạn.

Những gì người gọi và hệ thống của bạn thấy#

• ID người gọi: phần người dùng của header From được lưu làm người gọi. Số điện thoại (chữ số, có thể kèm +, khoảng trắng, dấu gạch ngang, dấu chấm hoặc dấu ngoặc) được chuẩn hóa thành E.164; mọi giá trị khác, chẳng hạn như tên người dùng SIP, được giữ nguyên như đã gửi. Chỉ giữ tối đa 32 ký tự và người gọi bị thiếu được lưu là anonymous.
• Cuộc gọi bị từ chối: URI theo từng cuộc gọi không xác định hoặc đã hết hạn nhận SIP 404 Not Found. URI theo từng cuộc gọi đã được sử dụng, điểm cuối bị vô hiệu hóa hoặc nguồn nằm ngoài danh sách cho phép (bao gồm mọi cuộc gọi UDP đến điểm cuối có danh sách cho phép) sẽ bị ngắt trước khi tác nhân AI bắt đầu: hệ thống của bạn có thể thấy cuộc gọi thất bại hoặc kết nối rồi kết thúc ngay. Những lần từ chối này không tạo mục lịch sử cuộc gọi. Nếu tổ chức của bạn hết tín dụng hoặc đã đạt giới hạn chi tiêu, cuộc gọi sẽ bị từ chối và hiển thị trong lịch sử cuộc gọi là cuộc gọi thất bại không có phí. Để thử lại một lần gọi theo từng cuộc gọi, hãy đăng ký URI mới.
• Chuyển cuộc gọi: chức năng chuyển cuộc gọi lạnh của tác nhân AI hoạt động (ThunderPhone gửi SIP REFER, mà hệ thống của bạn phải chấp nhận). Chuyển cuộc gọi có tham vấn không khả dụng cho cuộc gọi đến địa chỉ SIP vì không có số ThunderPhone để hiển thị làm ID người gọi cho chặng thứ hai. Với Twilio, TwiML ở trên kết nối tác nhân AI nhưng không xử lý chuyển cuộc gọi: thêm referUrl="https://YOUR_SERVER/sip-transfer" vào <Dial>, rồi để webhook đó đọc ReferTransferTarget và trả về TwiML quay số đến đích chuyển cuộc gọi (xem hướng dẫn SIP REFER của Twilio).
• Tin nhắn văn bản: địa chỉ SIP và số đã quay không thể gửi tin nhắn. Tác nhân AI chỉ có thể nhắn tin trong cuộc gọi đến địa chỉ SIP nếu được thiết lập một số riêng có khả năng SMS để nhắn tin; nếu không, công cụ SMS của tác nhân AI sẽ không khả dụng.
• Đăng ký: ThunderPhone không chấp nhận SIP REGISTER. Hãy gửi cuộc gọi đến địa chỉ; không đăng ký với địa chỉ đó.

Định giá#

Cuộc gọi đến địa chỉ SIP được tính phí theo mức phí mỗi phút thông thường của tác nhân AI. Không có phí số điện thoại vì không có số ThunderPhone nào thực hiện cuộc gọi. Nhà mạng của bạn vẫn tính phí phần cuộc gọi của họ như thông thường. Xem Định giá.

Kiểm tra#

1. Tạo URI theo từng cuộc gọi hoặc điểm cuối như ở trên.
2. Quay số từ hệ thống của bạn hoặc từ bất kỳ phần mềm điện thoại SIP nào (đối với điểm cuối, nhập tên người dùng và mật khẩu).
3. Sau khi gác máy, mở cuộc gọi trong Cuộc gọi trên bảng điều khiển hoặc truy xuất bằng GET /v1/calls/{call_id}. Mục này hiển thị người gọi, đích đến (xem thứ tự trong phần "Truyền số đã quay") và bản chép lời.

Chi tiết API: Tài liệu tham chiếu API địa chỉ SIP.