Cuộc gọi
Kết thúc cuộc gọi
Hiện chỉ hỗ trợ cuộc gọi đi bằng thoại và video một đối một trên WhatsApp. Dùng account_id và call_id để kết thúc. Nếu quên ID, hãy lấy cuộc gọi hiện tại trước.
https://api.unifyport.ai/v1/calls/{call_id}/hangupKênh được hỗ trợ
Trước khi gọi
Dùng X-Api-Key của workspace sở hữu tài nguyên trên máy chủ. Thay mọi giá trị mẫu trước khi chạy.
Trước khi tạo cuộc gọi, hoàn tất xác thực WhatsApp và kiểm tra runtime_status=running. Dùng conversation_id của hội thoại riêng thuộc tài khoản này.
Nguồn tham số
- account_id
- Lấy data.id từ phản hồi tạo hoặc truy vấn tài khoản. ID thuộc workspace của X-Api-Key. Lấy tài khoản
- call_id
- Dùng call_id trả về khi tạo hoặc truy vấn cuộc gọi hiện tại của tài khoản này. Nếu mất ID, truy vấn cuộc gọi hiện tại trước khi kết thúc. Lấy cuộc gọi hiện tại
Tham số yêu cầu
Tiêu đề
X-Api-KeyAPI key của không gian làm việc. Không gian làm việc được xác định từ tiêu đề này.
Content-TypeDùng application/json khi gửi nội dung yêu cầu JSON.
Tham số đường dẫn
call_idĐịnh danh dùng cho route calls.
maxLength: 128 · pattern: ^[A-Za-z0-9][A-Za-z0-9_-]*$
Nội dung yêu cầu
account_idID tài khoản trong không gian làm việc hiện tại.
pattern: ^acc_[A-Za-z0-9][A-Za-z0-9_-]*$
Hiểu kết quả
Đọc call_id và state trả về. ended và failed đều là trạng thái kết thúc của cuộc gọi; yêu cầu kết thúc lặp lại có thể trả trạng thái kết thúc đã có. HTTP 200 không nhất thiết là state=ended; không tự động thử lại chỉ vì state=failed.
Phản hồi 200 · 200
{
"request_id": "req_example",
"data": {
"call_id": "call_example",
"state": "ended",
"direction": "outbound",
"media_type": "voice"
}
}
Nội dung phản hồi
call_idMã cuộc gọi, cũng dùng để kết thúc.
maxLength: 128
stateTrạng thái cuộc gọi hiện tại.
enum: ended, failed
directionHướng cuộc gọi.
enum: inbound, outbound
media_typevoice là âm thanh; video là cuộc gọi có hỗ trợ video.
enum: voice, video
Phản hồi
200200 · 200
Yêu cầu thành công. Xem ví dụ nội dung phản hồi.
400Bad Request
Body, đường dẫn hoặc tham số yêu cầu không hợp lệ.
401Unauthorized
Header X-Api-Key thiếu hoặc không hợp lệ.
403Forbidden
Yêu cầu đã được nhận diện nhưng thao tác không được phép.
404Not Found
Không tìm thấy tài nguyên được yêu cầu. Kiểm tra error.code cùng với thao tác hiện tại.
409Conflict
Thao tác đang yêu cầu xung đột với tài khoản hoặc tài nguyên nhà cung cấp đã có.
500Internal Server Error
Dịch vụ gặp lỗi không mong muốn.
501Not Implemented
Provider đã chọn chưa triển khai thao tác này.
502Bad Gateway
Adapter hoặc upstream provider không thể hoàn tất thao tác.
503Service Unavailable
Dịch vụ backend cần thiết tạm thời không khả dụng.
Khi yêu cầu thất bại
Kiểm tra HTTP và error.code/numeric_code; giữ request_id. Kiểm tra tài khoản và call_id. Nếu tạo bị xung đột, truy vấn cuộc gọi hiện tại trước. Xác nhận trạng thái trước khi thử lại thao tác tạo hoặc kết thúc. Tham chiếu mã lỗi
Đọc trạng thái HTTP, error.code và error.numeric_code theo thao tác đang gọi. Mã số có kiểu chuỗi. Giữ request_id để chẩn đoán; đây không phải khóa chống lặp hay mã tác vụ.
- invalid_request · 10000 · 400
Kiểm tra JSON và các trường bắt buộc.
Xử lý và thử lại: Sửa tham số theo thao tác và điều kiện của kênh rồi mới gọi lại. Lặp lại yêu cầu sai y nguyên không khắc phục lỗi.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 400 · 10000
{ "request_id": "req_example", "error": { "code": "invalid_request", "numeric_code": "10000", "message": "Invalid request parameters" } }- invalid_target_workspace · 11003 · 400
Đích ghi đè workspace trống hoặc sai định dạng. Bỏ tiêu đề ghi đè và dùng API Key thuộc workspace đích.
Điều kiện: Áp dụng khi yêu cầu có tiêu đề X-Workspace-Id để ghi đè workspace.
Xử lý và thử lại: Sửa tham số theo thao tác và điều kiện của kênh rồi mới gọi lại. Lặp lại yêu cầu sai y nguyên không khắc phục lỗi.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 400 · 11003
{ "request_id": "req_example", "error": { "code": "invalid_target_workspace", "numeric_code": "11003", "message": "Invalid target workspace" } }- provider_invalid_request · 30001 · 400
Kiểm tra các trường và định dạng riêng của kênh.
Xử lý và thử lại: Sửa tham số theo thao tác và điều kiện của kênh rồi mới gọi lại. Lặp lại yêu cầu sai y nguyên không khắc phục lỗi.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 400 · 30001
{ "request_id": "req_example", "error": { "code": "provider_invalid_request", "numeric_code": "30001", "message": "Provider rejected the request" } }- invalid_api_key · 11001 · 401
Kiểm tra API Key có đúng và được bật hay không.
Xử lý và thử lại: Giữ request_id và mã lỗi có cấu trúc; kiểm tra thao tác hiện tại trước khi chọn hành động tiếp theo.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 401 · 11001
{ "request_id": "req_example", "error": { "code": "invalid_api_key", "numeric_code": "11001", "message": "Invalid API key" } }- missing_api_key · 11000 · 401
Thêm tiêu đề X-Api-Key.
Xử lý và thử lại: Giữ request_id và mã lỗi có cấu trúc; kiểm tra thao tác hiện tại trước khi chọn hành động tiếp theo.
Ví dụ · 401 · 11000
{ "request_id": "req_xxx", "error": { "code": "missing_api_key", "numeric_code": "11000", "message": "Missing X-Api-Key header" } }- workspace_override_forbidden · 11002 · 403
Yêu cầu cố ghi đè workspace mà API Key không được phép dùng. Bỏ tiêu đề ghi đè và dùng API Key thuộc workspace đích.
Điều kiện: Áp dụng khi yêu cầu có tiêu đề X-Workspace-Id để ghi đè workspace.
Xử lý và thử lại: Giữ request_id và mã lỗi có cấu trúc; kiểm tra thao tác hiện tại trước khi chọn hành động tiếp theo.
Ví dụ · 403 · 11002
{ "request_id": "req_example", "error": { "code": "workspace_override_forbidden", "numeric_code": "11002", "message": "Workspace override is not allowed" } }- account_not_found · 20020 · 404
Kiểm tra account_id và dùng X-Api-Key của không gian làm việc sở hữu tài khoản. Khóa hiện tại không truy cập được tài khoản không tìm thấy trong không gian này.
Xử lý và thử lại: Kiểm tra mã đích, chủ sở hữu tài nguyên và workspace hiện tại. Không coi đích đã xác nhận thiếu hoặc không truy cập được là lỗi dịch vụ tạm thời để tự thử lại.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 404 · 20020
{ "request_id": "req_example", "error": { "code": "account_not_found", "numeric_code": "20020", "message": "Account not found" } }- call_not_found · 38003 · 404
Không tìm thấy cuộc gọi trong tài khoản và không gian làm việc này.
Xử lý và thử lại: Kiểm tra mã đích, chủ sở hữu tài nguyên và workspace hiện tại. Không coi đích đã xác nhận thiếu hoặc không truy cập được là lỗi dịch vụ tạm thời để tự thử lại.
Ví dụ · 404 · 38003
{ "request_id": "req_example", "error": { "code": "call_not_found", "numeric_code": "38003", "message": "Call not found" } }- target_workspace_not_found · 11004 · 404
Không tìm thấy workspace được ghi đè hoặc workspace không khả dụng. Kiểm tra chủ sở hữu, bỏ tiêu đề ghi đè và dùng API Key của workspace đích; gọi lặp không cấp thêm quyền.
Điều kiện: Áp dụng khi yêu cầu có tiêu đề X-Workspace-Id để ghi đè workspace.
Xử lý và thử lại: Kiểm tra mã đích, chủ sở hữu tài nguyên và workspace hiện tại. Không coi đích đã xác nhận thiếu hoặc không truy cập được là lỗi dịch vụ tạm thời để tự thử lại.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 404 · 11004
{ "request_id": "req_example", "error": { "code": "target_workspace_not_found", "numeric_code": "11004", "message": "Target workspace not found" } }- account_binding_not_found · 30006 · 409
Tài khoản chưa gắn với kết nối kênh hoạt động; kiểm tra trạng thái.
Xử lý và thử lại: Kiểm tra trạng thái xác thực và runtime rồi chọn làm mới, khởi động hoặc kết nối lại theo mục tiêu và khả năng kênh. Lỗi kết nối không tự chứng minh đã đăng xuất. Xác nhận running trước thao tác nghiệp vụ cần kết nối.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 409 · 30006
{ "request_id": "req_example", "error": { "code": "account_binding_not_found", "numeric_code": "30006", "message": "Account is not bound to an available server" } }- call_already_active · 38000 · 409
Tài khoản đã có cuộc gọi đang hoạt động do hệ thống quản lý. Kiểm tra cuộc gọi đã biết và mục đích thao tác; lỗi này không yêu cầu gác cuộc gọi hay liên tục gọi lại cùng truy vấn lỗi.
Xử lý và thử lại: Giữ request_id và mã lỗi có cấu trúc; kiểm tra thao tác hiện tại trước khi chọn hành động tiếp theo.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 409 · 38000
{ "request_id": "req_example", "error": { "code": "call_already_active", "numeric_code": "38000", "message": "Account already has an active call" } }- egress_configuration_pending · 20032 · 409
Hiện chưa thể xác nhận hoặc tải cấu hình mạng mặc định của nền tảng. Điều này không có nghĩa là tài khoản đã đăng xuất.
Điều kiện: Thao tác này dùng dung lượng mạng do nền tảng phân bổ hoặc cấu hình mạng mặc định cố định của tài khoản.
Xử lý và thử lại: Lưu request_id và kiểm tra tài khoản hoặc kết quả tạo trước khi ghi lại. Chờ dung lượng hoặc cấu hình phục hồi, hoặc liên hệ hỗ trợ. Không tự động tạo tài khoản, đổi mạng hay khởi động lại liên tục.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 409 · 20032
{ "request_id": "req_example", "error": { "code": "egress_configuration_pending", "numeric_code": "20032", "message": "Account network configuration is pending verification" } }- provider_not_ready · 30009 · 409
Kết nối chưa sẵn sàng. Kiểm tra ủy quyền và runtime_status trước khi thử lại.
Xử lý và thử lại: Kiểm tra trạng thái xác thực và runtime rồi chọn làm mới, khởi động hoặc kết nối lại theo mục tiêu và khả năng kênh. Lỗi kết nối không tự chứng minh đã đăng xuất. Xác nhận running trước thao tác nghiệp vụ cần kết nối.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 409 · 30009
{ "request_id": "req_example", "error": { "code": "provider_not_ready", "numeric_code": "30009", "message": "Provider client is not ready" } }- provider_not_ready · 30014 · 409
Thiếu phiên bản chạy của kênh mà tài khoản cần. Đây là vấn đề khả dụng runtime, không chứng minh xác thực đã hết hạn.
Xử lý và thử lại: Kiểm tra trạng thái xác thực và runtime rồi chọn làm mới, khởi động hoặc kết nối lại theo mục tiêu và khả năng kênh. Lỗi kết nối không tự chứng minh đã đăng xuất. Xác nhận running trước thao tác nghiệp vụ cần kết nối.
Kênh áp dụng: WhatsApp
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 409 · 30014
{ "request_id": "req_example", "error": { "code": "provider_not_ready", "numeric_code": "30014", "message": "Provider instance is missing" } }- provider_not_ready · 30015 · 409
Runtime của kênh đã dừng. Kiểm tra có chủ ý không trước khi khởi động; runtime dừng không tự đồng nghĩa đã đăng xuất.
Xử lý và thử lại: Kiểm tra trạng thái xác thực và runtime rồi chọn làm mới, khởi động hoặc kết nối lại theo mục tiêu và khả năng kênh. Lỗi kết nối không tự chứng minh đã đăng xuất. Xác nhận running trước thao tác nghiệp vụ cần kết nối.
Kênh áp dụng: WhatsApp
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 409 · 30015
{ "request_id": "req_example", "error": { "code": "provider_not_ready", "numeric_code": "30015", "message": "Provider runtime is stopped" } }- call_control_failed · 30010 · 500
Kênh không hoàn thành được thao tác. message có thể kèm nguyên nhân gốc sau “Provider operation failed:”; nội dung này thay đổi và không phải giao diện lập trình ổn định.
Điều kiện: Áp dụng khi kênh không cung cấp phân loại lỗi cụ thể hơn; giữ nguyên lỗi của thao tác hiện tại.
Xử lý và thử lại: Trước khi tạo hoặc kết thúc cuộc gọi, truy vấn cuộc gọi đang được quản lý cùng call_id/state. preparing chưa phải quay số hay được trả lời; ended và failed đều là trạng thái kết thúc. Không gác lại chỉ vì failed.
Kênh áp dụng: WhatsApp
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 500 · 30010
{ "request_id": "req_example", "error": { "code": "call_control_failed", "numeric_code": "30010", "message": "Provider operation failed" } }- call_control_failed · 38004 · 500
Không thể truy vấn hoặc kết thúc cuộc gọi. Kiểm tra thao tác hiện tại và trạng thái cuộc gọi.
Xử lý và thử lại: Trước khi tạo hoặc kết thúc cuộc gọi, truy vấn cuộc gọi đang được quản lý cùng call_id/state. preparing chưa phải quay số hay được trả lời; ended và failed đều là trạng thái kết thúc. Không gác lại chỉ vì failed.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 500 · 38004
{ "request_id": "req_example", "error": { "code": "call_control_failed", "numeric_code": "38004", "message": "Failed to control call" } }- unsupported_by_provider · 30003 · 501
Kênh không hỗ trợ thao tác; chọn thao tác trong bảng hỗ trợ.
Xử lý và thử lại: Chọn kênh và thao tác được tài liệu ghi là hỗ trợ. Lặp yêu cầu không bổ sung tính năng hay cấp quyền beta.
Ví dụ · 501 · 30003
{ "request_id": "req_xxx", "error": { "code": "unsupported_by_provider", "numeric_code": "30003", "message": "Operation not supported by this provider" } }- provider_adapter_not_found · 30004 · 502
Dịch vụ kênh chưa khả dụng. Kiểm tra trạng thái hoặc thử sau; xác nhận kết quả trước khi thử ghi lại.
Xử lý và thử lại: Trước khi tạo hoặc kết thúc cuộc gọi, truy vấn cuộc gọi đang được quản lý cùng call_id/state. preparing chưa phải quay số hay được trả lời; ended và failed đều là trạng thái kết thúc. Không gác lại chỉ vì failed.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 502 · 30004
{ "request_id": "req_example", "error": { "code": "provider_adapter_not_found", "numeric_code": "30004", "message": "Provider adapter unavailable" } }- provider_unavailable · 30002 · 502
Dịch vụ kênh chưa khả dụng. Kiểm tra trạng thái hoặc thử sau; xác nhận kết quả trước khi thử ghi lại.
Xử lý và thử lại: Trước khi tạo hoặc kết thúc cuộc gọi, truy vấn cuộc gọi đang được quản lý cùng call_id/state. preparing chưa phải quay số hay được trả lời; ended và failed đều là trạng thái kết thúc. Không gác lại chỉ vì failed.
Ví dụ · 502 · 30002
{ "request_id": "req_example_provider_unavailable", "error": { "code": "provider_unavailable", "numeric_code": "30002", "message": "Provider service unavailable" } }- provider_unavailable · 30010 · 502
Kênh không hoàn thành được thao tác. message có thể kèm nguyên nhân gốc sau “Provider operation failed:”; nội dung này thay đổi và không phải giao diện lập trình ổn định.
Xử lý và thử lại: Trước khi tạo hoặc kết thúc cuộc gọi, truy vấn cuộc gọi đang được quản lý cùng call_id/state. preparing chưa phải quay số hay được trả lời; ended và failed đều là trạng thái kết thúc. Không gác lại chỉ vì failed.
Kênh áp dụng: WhatsApp
Ví dụ · 502 · 30010
{ "request_id": "req_example_operation_failed", "error": { "code": "provider_unavailable", "numeric_code": "30010", "message": "Provider operation failed: Example operation could not be completed" } }- call_service_unavailable · 38001 · 503
Dịch vụ cuộc gọi không khả dụng. Kiểm tra kết nối và cấu hình Provider/Gateway.
Xử lý và thử lại: Trước khi tạo hoặc kết thúc cuộc gọi, truy vấn cuộc gọi đang được quản lý cùng call_id/state. preparing chưa phải quay số hay được trả lời; ended và failed đều là trạng thái kết thúc. Không gác lại chỉ vì failed.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 503 · 38001
{ "request_id": "req_example", "error": { "code": "call_service_unavailable", "numeric_code": "38001", "message": "Call service unavailable" } }