--- title: "Kết nối qua SIP (không cần số điện thoại)" description: "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: | | **URI SIP theo cuộc gọi** | **Điểm cuối SIP** | |---|---|---| | Có dạng | `sip:c-@sip.thunderphone.com` | `sip:agent--@sip.thunderphone.com` | | Được tạo bằng | `POST /v1/calls/register-sip`, một lần cho mỗi cuộc gọi | `POST /v1/sip-endpoints`, một lần | | Xác thực | Token dùng một lần trong địa chỉ | Tên người dùng + mật khẩu SIP digest (và tùy chọn danh sách cho phép IP nguồn) | | Phù hợp cho | Ứng dụng đã gọi API trước khi chuyển cuộc gọi; biến theo từng cuộc gọi | PBX và nhà mạng chỉ cần "trỏ trunk" đến ThunderPhone | | Có hiệu lực trong | 5 phút, một cuộc gọi | Cho đến khi bạn xóa | 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 ```bash 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"} }' ``` ```json { "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](/vi/guides/call-variables). - `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: ```xml sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp ``` 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 ```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": "Main PBX"}' ``` ```json { "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" } ``` `password` chỉ được trả về một lần, khi điểm cuối được tạo. Lưu ngay thông tin này vào cấu hình PBX hoặc nhà cung cấp của bạn. Nếu làm mất, hãy xoay vòng mật khẩu bằng `POST /v1/sip-endpoints/{id}/rotate-password`. ### 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ài đặt | Giá trị | |---|---| | URI SIP | `sip_uri` của điểm cuối | | Tên người dùng / mật khẩu | `username` / `password` (xác thực digest; ThunderPhone yêu cầu xác thực cho mỗi cuộc gọi) | | Giao thức truyền tải | TCP trên cổng 5060 hoặc TLS trên cổng 5061 (khuyến nghị), hoặc UDP trên cổng 5060 | | Codec | G.711 (PCMU/PCMA) hoặc G.722 | Ưu tiên TCP hoặc TLS. UDP hoạt động từ địa chỉ công khai và hầu hết NAT, nhưng phía sau NAT "đối xứng" (loại dùng một cổng mới cho mỗi đích đến), lệnh ngắt cuộc gọi và chuyển cuộc gọi của tác nhân AI có thể không đến được hệ thống của bạn. Danh sách cho phép IP nguồn (bên dưới) cũng cần TCP hoặc TLS. Qua TLS, báo hiệu SIP vẫn được mã hóa sau `sip.thunderphone.com`, xuyên suốt đến các máy chủ xử lý cuộc gọ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: ```bash 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. Danh sách cho phép chỉ được kiểm tra với cuộc gọi qua TCP hoặc TLS. Địa chỉ nguồn UDP có thể bị giả mạo, vì vậy điểm cuối có danh sách cho phép sẽ từ chối mọi cuộc gọi đến qua UDP. Gửi cuộc gọi đến điểm cuối bằng `;transport=tcp` (cổng 5060) hoặc qua TLS (cổng 5061). ## 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 ``, 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](https://www.twilio.com/docs/voice/api/refer-to-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á](/vi/guides/pricing). ## 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](/api-reference/sip-addresses).