Chuyển tới nội dung chính

REST API cục bộ

AI Softphone có một REST API để tích hợp CTI: một chương trình trên cùng máy tính có thể thực hiện và điều khiển cuộc gọi, đọc danh bạ, lịch sử cuộc gọi và tài khoản SIP, và theo dõi các cuộc gọi đang diễn ra. Không cần SDK, không có trung gian trên đám mây và không có cổng lắng nghe nào mở ra mạng. Yêu cầu và câu trả lời đều là JSON, nên curl hay bất kỳ HTTP client nào cũng đủ dùng.

API ở trạng thái tắt sau khi cài đặt; không có gì lắng nghe cho tới khi bạn bật nó. Khi đó nó chỉ lắng nghe trên giao diện loopback — một giao diện web nhỏ chỉ trả lời chính máy tính này — và không thể truy cập từ mạng văn phòng, VPN hay máy khác.

Hãy dùng API khi chương trình của bạn cần dữ liệu từ điện thoại hoặc phải điều khiển cuộc gọi. Hãy dùng webhook khi nó phải phản ứng với cuộc gọi ngay khi chúng diễn ra, mà không cần thăm dò liên tục. Phần lớn các tích hợp dùng cả hai; chúng độc lập với nhau.

Bật API​

Mở Cài đặt → Tích hợp và đến mục Điều khiển cục bộ.

  1. Bật Cho phép các chương trình khác trên máy này điều khiển điện thoại. Máy chủ khởi động ngay lập tức.
  2. Giữ Cổng mặc định, 8377, trừ khi một chương trình khác đã dùng cổng này.
  3. Nếu muốn, đặt một Token. Sau khi lưu, ô này hiển thị Đã lưu — gõ để thay thế.
  4. Ở mục Truy cập, chọn các nhóm cần mở: Danh bạ, Lịch sử cuộc gọi, Cuộc gọi và việc điều khiển chúng, Tài khoản, Cài đặt, Bộ đếm (các chỉ số). Nhóm đã tắt không bị lọc mà hoàn toàn không được phục vụ.
  5. Kiểm tra: curl http://127.0.0.1:8377/accounts. Nếu câu trả lời là JSON, API đang hoạt động.

Không có dịch vụ riêng nào được cài đặt và không cần khởi động lại. Phần chương trình làm việc này có thể tắt trong Mô-đun (Tích hợp).

Trang của chính API​

Mở trang của chính API mở http://127.0.0.1:8377 trong trình duyệt. Địa chỉ này trả lời bằng danh sách mọi thứ nó phục vụ, bằng tiếng Anh; các địa chỉ dùng để đọc dữ liệu là những liên kết bạn có thể nhấp vào.

Quyền truy cập và token​

Một chương trình được làm gì phụ thuộc vào việc nó có thay đổi dữ liệu đã lưu hay không, chứ không phụ thuộc vào việc nó có đọc hay không:

  • Không có token, bất kỳ chương trình nào trên máy tính cũng có thể đọc mọi thứ trong các nhóm đã bật và điều khiển cuộc gọi: gọi, trả lời, cúp máy, giữ máy, tiếp tục, chuyển cuộc gọi và gửi DTMF.
  • Có token trong tiêu đề Authorization, nó còn có thể dùng các endpoint thay đổi dữ liệu đã lưu. Không có token, các endpoint đó không được liệt kê trên trang của chính API và trả lời 401. Nếu hoàn toàn không đặt token, không gì có thể thay đổi dữ liệu đã lưu.

Token được giữ trong kho khoá của máy tính, không nằm trong tệp cài đặt, và không bao giờ được /settings trả về.

thận trọng

Không có token, bất kỳ chương trình nào đang chạy trên máy tính này đều có thể điều khiển điện thoại, kể cả trả lời cuộc gọi. Trên máy trạm cá nhân, điều đó thường chấp nhận được. Trên máy dùng chung hoặc máy được quản lý tập trung, hãy đặt token và bảo vệ nó như mọi mật khẩu khác. Token chỉ bảo vệ các yêu cầu làm thay đổi dữ liệu đã lưu, không bảo vệ cuộc gọi: để chặn chương trình khác điều khiển cuộc gọi, hãy tắt Cuộc gọi và việc điều khiển chúng trong mục Truy cập.

Các endpoint​

Địa chỉ gốc là http://127.0.0.1:8377. Các endpoint dưới đây không cần token.

Phương thứcĐường dẫnTác dụng
GET/metricsCác bộ đếm, ở định dạng Prometheus.
GET/uiDanh sách bản ghi, dưới dạng trang HTML.
GET/ui/recordings/{id}Một bản ghi kèm bản chép lời, dưới dạng trang HTML.
GET/ui/recordings/{id}/audioÂm thanh cho trang ở trên.
GET/contactsDanh bạ.
GET/contacts/{id}Một liên hệ.
GET/historyNhật ký cuộc gọi, mới nhất ở trên. Nhận ?limit=, ?missed=true và ?declined=true.
GET/callsCác cuộc gọi đang diễn ra.
POST/callsThực hiện cuộc gọi: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerTrả lời cuộc gọi.
POST/calls/{id}/hangupCúp máy.
POST/calls/{id}/holdGiữ máy.
POST/calls/{id}/resumeTiếp tục cuộc gọi đang giữ.
POST/calls/{id}/dtmfGửi âm: {"digits": "..."}.
POST/calls/{id}/transferChuyển cuộc gọi: {"target": "..."}.
GET/accountsCác tài khoản SIP và trạng thái đăng ký của chúng. Không bao giờ có mật khẩu.
GET/settingsToàn bộ cấu hình, không kèm các thông tin bí mật.
GET/taxonomyHạng mục, nhãn và dấu hiệu cảnh báo, kèm mã của chúng.

Các endpoint cần token​

Chúng thay đổi dữ liệu đã lưu, nên mỗi yêu cầu phải mang token trong tiêu đề Authorization. Trang của chính API chỉ hiển thị chúng cho yêu cầu có mang token.

Phương thứcĐường dẫnTác dụng
POST/contactsThêm một liên hệ: {"name": "...", "number": "...", "account_id": "..."}; account_id là tuỳ chọn.
PUT/contacts/{id}Thay thế một liên hệ.
DELETE/contacts/{id}Xoá một liên hệ.
DELETE/history/{id}Quên một cuộc gọi trong nhật ký cuộc gọi.
DELETE/historyQuên toàn bộ nhật ký cuộc gọi. Không thể hoàn tác.
PUT/accounts/{id}Thay thế cài đặt của một tài khoản. Mật khẩu không nằm trong đó.
PUT/settingsThay thế cài đặt.

Mọi mã định danh đều là UUID do điện thoại cấp: id của cuộc gọi lấy từ /calls hoặc từ câu trả lời của POST /calls, id của tài khoản lấy từ /accounts.

Tên trường viết theo snake_case và phần đuôi cho biết kiểu: _id là tham chiếu tới một UUID, _ts là thời điểm tính bằng mili giây Unix (UTC), _s là độ dài tính bằng giây. Điều này cũng đúng với webhook; chỉ /settings giữ tên riêng của nó. Trong REST API, các giá trị này là số JSON, và thời điểm chưa biết là null.

Ví dụ: thực hiện cuộc gọi​

POST /calls thực hiện một cuộc gọi đi. Phần thân là JSON với number cần gọi và, tuỳ chọn, account_id của tài khoản dùng để gọi:

curl --location 'http://127.0.0.1:8377/calls' \
--header 'Content-Type: application/json' \
--data '{
"number": "1020",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90"
}'

Câu trả lời là mã định danh của cuộc gọi mới:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • number là bắt buộc. Thiếu nó, câu trả lời là 400 {"error":"a call needs a number"} và không có gì được quay số.
  • Số được hoàn thiện trên tài khoản đã chọn theo cách bàn quay số hoàn thiện nó: 1020 được gửi thành sip:1020@pbx.example.com. POST /calls/{id}/transfer hoàn thiện target của nó theo cùng cách; đích đã có scheme hoặc @ được gửi nguyên trạng.
  • account_id là tuỳ chọn; lấy nó từ GET /accounts. Thiếu nó, cuộc gọi đi ra trên tài khoản đang được chọn trong cửa sổ chính.
  • Dùng id trong /calls/{id}/…: hangup, hold, resume, dtmf và transfer. Các webhook của cuộc gọi này mang cùng id.

Từ một trang web: nhấp để gọi​

Một trang gọi tới 127.0.0.1 sẽ đến được máy tính mà trình duyệt đang chạy — cũng chính là máy mà điện thoại đang chạy — nên nút nhấp để gọi trong CRM không cần máy chủ riêng:

async function dial(number) {
const r = await fetch("http://127.0.0.1:8377/calls", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ number }),
});
if (!r.ok) console.warn("softphone:", (await r.json()).error);
}

Câu trả lời chứa gì​

Các cuộc gọi đang diễn ra: GET /calls​

Mỗi cuộc gọi có id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts và callstate_ts.

  • state là dialing, ringing-out, ringing-in, active, hold (do điện thoại này giữ máy), onhold (do bên kia giữ máy), conference hoặc ended. Khi nhiều giá trị cùng áp dụng, conference được ưu tiên hơn hold, và hold hơn onhold.
  • muted cho biết micrô có đang bị tắt tiếng trong cuộc gọi không; việc tắt tiếng không thay đổi state.
  • seance_id là cuộc trò chuyện: các cuộc gọi được liên kết bởi chuyển tiếp, tham vấn hay hội thoại nhóm dùng chung giá trị này.
  • event_ts là thời điểm câu trả lời được tạo. Hãy so sánh nó với callstate_ts để biết cuộc gọi đã ở trạng thái hiện tại bao lâu, mà không cần dựa vào đồng hồ của bạn.

Tài khoản: GET /accounts​

Mỗi tài khoản có id (chính là account_id ở mọi nơi khác), các cài đặt của nó — transport (udp, tcp hoặc tls), port, registrar, outbound_proxy, expiry_s và các trường khác — việc nó có enabled hay không, và state của nó trên tổng đài: registered khi đường dây đang hoạt động. Mật khẩu không bao giờ được đưa vào.

Lịch sử cuộc gọi: GET /history​

Mới nhất ở trên, 100 mục trừ khi ?limit= quy định khác. ?missed=true chỉ trả về các cuộc gọi nhỡ, ?declined=true chỉ trả về các cuộc gọi mà điện thoại này đã từ chối.

TrườngÝ nghĩa
idMã định danh riêng của mục lịch sử. Nó không phải id cuộc gọi của /calls và của webhook; seance_id liên kết hai thứ này.
outcomePhân loại chính: answered, missed, declined hoặc failed.
answeredtrue hoặc false.
duration_s0 với cuộc gọi chưa bao giờ được kết nối.
number, uriBên kia, dưới dạng số máy và địa chỉ SIP.
nameLấy từ Danh bạ nếu số đã biết, nếu không thì để trống. Hãy đối chiếu theo number, không theo trường này.
dialedCác chữ số đã quay, với cuộc gọi đi; để trống với cuộc gọi đến.
account, account_idĐường dây của cuộc gọi.
reasonCuộc gọi kết thúc thế nào: local-hangup, remote-hangup, cancelled…
answered_byno nếu một người đã trả lời; nếu không thì là thứ đã trả lời cuộc gọi.

Danh bạ: GET /contacts​

Mỗi liên hệ có id, name, number và đường dây mà nó thuộc về, account_id và account; account để trống nghĩa là liên hệ không gắn với đường dây nào.

Bản ghi​

Bản ghi và bản chép lời không được cung cấp dưới dạng JSON. API phục vụ chúng dưới dạng trang HTML, /ui và /ui/recordings/{id}: hãy liên kết tới các trang này từ CRM thay vì chuyển âm thanh đi khắp nơi. Liên kết mở trên máy tính đang giữ bản ghi, và âm thanh không bao giờ rời khỏi máy đó.

Phân loại và cài đặt​

Mỗi mục của /taxonomy có một code không đổi, một title và một description bằng ngôn ngữ giao diện, một kind (category, tag hoặc red_flag) và, với dấu hiệu cảnh báo, một severity. Hãy đối chiếu theo code, không bao giờ theo title: tiêu đề đến bằng ngôn ngữ mà điện thoại đang đặt. Mục có retired: true được giữ lại để các cuộc gọi cũ vẫn tra được; nó không còn được gán cho cuộc gọi mới. Hãy tải bảng phân loại một lần khi khởi động để ánh xạ các từ của điện thoại sang các trường của riêng bạn.

/settings trả về cấu hình trừ các thông tin bí mật: thiết bị âm thanh và âm lượng, thứ tự ưu tiên codec, giao diện và ngôn ngữ, khởi động, phím tắt, mức chẩn đoán và trạng thái của cả hai tích hợp — hữu ích cho công cụ hỗ trợ cần kiểm tra một máy trạm mà không phải chia sẻ màn hình. api.disabled liệt kê các nhóm truy cập đang tắt và webhooks.silenced các sự kiện đang tắt; danh sách rỗng nghĩa là mọi thứ đều bật. Nó không bao giờ chứa mật khẩu SIP, token API hay giá trị tiêu đề webhook.

Lỗi​

Mọi lỗi đều là JSON với một khoá error duy nhất, dành cho con người đọc chứ không phải để phân tích cú pháp.

Mã trạng tháiPhần thânÝ nghĩa
404{"error":"no such endpoint"}Đường dẫn không tồn tại, hoặc nhóm truy cập của nó đang tắt; cả hai cố ý cho cùng một câu trả lời.
405{"error":"that endpoint does not take this method"}Đường dẫn có tồn tại nhưng không nhận phương thức này: ví dụ POST /settings thay vì PUT.
401{"error":"writing needs a token, and none is configured"}Một endpoint thay đổi dữ liệu đã lưu, trên điện thoại mà trường Token còn trống. Hãy điền nó trong Điều khiển cục bộ.
401{"error":"this endpoint needs the authorization token"}Một endpoint thay đổi dữ liệu đã lưu, không có token đúng.
404{"error":"no contact with that id"}Đường dẫn đúng, mã định danh thì không.
400{"error":"no call with that id"}Cuộc gọi đã kết thúc, hoặc chưa từng tồn tại.
400{"error":"a call needs a number"}POST /calls không có số. Không có gì được quay số.
400{"error":"no digits to send"}POST /calls/{id}/dtmf không có chữ số.
400{"error":"a transfer needs a target"}POST /calls/{id}/transfer không có đích.
400{"error":"the account this call is on is no longer set up"}Tài khoản của cuộc gọi đã bị xoá trong lúc gọi, nên không thể hoàn thiện đích. Không có gì được gửi tới tổng đài.

Các yêu cầu bị từ chối được đếm trong api_requests_refused_total, nên một tích hợp thất bại âm thầm sẽ lộ ra trong các chỉ số, chứ không chỉ trong nhật ký của riêng bạn.

Chỉ số​

GET /metrics trả về mọi bộ đếm của điện thoại, mỗi bộ đếm kèm một đoạn mô tả. Hãy thu thập bằng Prometheus hoặc đọc thủ công.

Bộ đếmĐếm
calls_incoming_totalCác cuộc gọi đến đã nhận.
calls_outgoing_totalCác cuộc gọi đi đã thực hiện.
calls_answered_totalCác cuộc gọi đã được trả lời.
calls_missed_totalCác cuộc gọi đến không được trả lời.
calls_declined_totalCác cuộc gọi bị từ chối ở đây hoặc bởi bên kia.
calls_failed_totalCác cuộc gọi không thể thiết lập.
registrations_succeeded_totalCác lần đăng ký SIP thành công.
registrations_failed_totalCác lần đăng ký SIP bị từ chối hoặc hết thời gian chờ.
webhooks_delivered_totalCác webhook bên nhận đã chấp nhận.
webhooks_failed_totalCác webhook bị từ chối hoặc không chuyển phát được.
webhooks_dropped_totalCác webhook bị bỏ vì hàng đợi đầy.
api_requests_totalCác yêu cầu API đã xử lý.
api_requests_refused_totalCác yêu cầu bị từ chối: sai token, nhóm đang tắt hoặc đường dẫn không xác định.

Cập nhật một tích hợp cũ​

Các phiên bản trước dùng tên camelCase và mã định danh ngắn. accountId giờ là account_id, startedAt là callstart_ts, durationSeconds là duration_s, answeredBy là answered_by, và trường webhook at là event_ts. Cuộc gọi và tài khoản chỉ được định danh bằng UUID: runtimeId và các mã định danh như call-3 hay account-2 không còn được trả về hay chấp nhận.

Khi nó không hoạt động​

Triệu chứngCần kiểm tra gì
Kết nối bị từ chối trên 127.0.0.1:8377Điều khiển cục bộ đang tắt, điện thoại không chạy, hoặc cổng đã bị đổi.
404 {"error":"no such endpoint"} với một đường dẫn có trên trang nàyNhóm truy cập của nó đang tắt.
Đọc được, ghi bị từ chối với 401Các endpoint thay đổi dữ liệu đã lưu cần token trong tiêu đề Authorization, và trên điện thoại phải điền trường Token trước.
Tiêu đề hạng mục không phải tiếng AnhTiêu đề theo ngôn ngữ giao diện. Hãy đối chiếu theo code từ /taxonomy.
Thiếu accountId, startedAt hoặc atTích hợp được viết cho các tên cũ; xem ở trên.

Với sự cố về đăng ký hoặc chính cuộc gọi, hãy mở Chẩn đoán.