Cuộc gọi

Tạo cuộc gọibeta

Tính năng này đang trong giai đoạn thử nghiệm kín. Hãy liên hệ bộ phận hỗ trợ kỹ thuật để yêu cầu cấp quyền cho không gian làm việc.

Hiện chỉ hỗ trợ cuộc gọi thoại và video một đối một trên WhatsApp. Chuẩn bị join_url riêng tư, dùng một lần. Mở liên kết và nhấn Start call để bắt đầu gọi.

POSThttps://api.unifyport.ai/v1/calls

Kê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.

Xác nhận không gian làm việc có quyền thử nghiệm kín. 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.

Gọi trong trình duyệt cần quyền dùng micrô; quyền dùng camera là tùy chọn.

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
to.id · to.type: Dùng nguyên conversation_id do API trả về cho hội thoại riêng đích thuộc tài khoản này trong to.id; đặt to.type=user. Không thay bằng chuỗi số điện thoại. Chi tiết hội thoại

Yêu cầu

curl -X POST 'https://api.unifyport.ai/v1/calls' \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_example",
  "to": {
    "id": "<conversation_id>",
    "type": "user"
  },
  "media_type": "video"
}'

Tham số yêu cầu

Tiêu đề

X-Api-Key

stringbắt buộc

API 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-Type

stringbắt buộc

Dùng application/json khi gửi nội dung yêu cầu JSON.

Nội dung yêu cầu

account_id

stringbắt buộc

ID 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_-]*$

to

objectbắt buộc

Người nhận cuộc gọi riêng.

id

stringbắt buộc

Nhập conversation_id của cuộc hội thoại đích thuộc tài khoản hiện tại, giữ nguyên giá trị do API trả về.

minLength: 1

type

stringbắt buộc

Hiện chỉ hỗ trợ user; group/channel trả lỗi không hỗ trợ.

enum: user, group, channel

media_type

stringbắt buộc

voice là âm thanh; video là cuộc gọi có hỗ trợ video.

enum: voice, video

Hiểu kết quả

201 với state=preparing xác nhận đã chuẩn bị cuộc gọi, chưa quay số. Lưu call_id, mở join_url riêng tư và nhấn Start call trước expires_at trả về. Xác nhận kết nối qua trạng thái cuộc gọi hoặc call.answered.

Ghi chú

Chuẩn bị cuộc gọi thoại hoặc video WhatsApp riêng tư (media_type: voice/video). to.id là conversation_id và to.type là user; không nhận chuỗi số điện thoại hoặc cuộc gọi nhóm. Thời gian chuẩn bị mặc định là 2 phút từ khi tạo; lấy expires_at trả về làm hạn thực tế. Mở join_url và nhấn Start call trước khi hết hạn. Hạn này không giới hạn thời lượng cuộc gọi đã kết nối. Bắt buộc cho phép micrô; camera tùy chọn. Không công khai liên kết dùng một lần.

Phản hồi 201 · 201

{
  "request_id": "req_example",
  "data": {
    "call_id": "call_example",
    "direction": "outbound",
    "media_type": "video",
    "state": "preparing",
    "join_url": "https://calls.example.com/call/call_example#ticket=example-only",
    "expires_at": "2026-09-07T12:02:00Z"
  }
}

Nội dung phản hồi

call_id

string

Mã cuộc gọi, cũng dùng để kết thúc.

direction

string

Hướng cuộc gọi.

enum: outbound

media_type

string

voice là âm thanh; video là cuộc gọi có hỗ trợ video.

enum: voice, video

state

string

Trạng thái cuộc gọi hiện tại.

enum: preparing

join_url

string

Liên kết HTTPS ngắn hạn, dùng một lần. Không ghi nhật ký hoặc công khai.

format: uri

expires_at

string

Thời điểm hết hạn chuẩn bị theo RFC3339.

format: date-time

Phản hồi

201

201 · 201

Yêu cầu thành công. Xem ví dụ nội dung phản hồi.

400

Bad Request

Body, đường dẫn hoặc tham số yêu cầu không hợp lệ.

401

Unauthorized

Header X-Api-Key thiếu hoặc không hợp lệ.

403

Forbidden

Yêu cầu đã được nhận diện nhưng thao tác không được phép.

404

Not 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.

409

Conflict

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ó.

500

Internal Server Error

Dịch vụ gặp lỗi không mong muốn.

501

Not Implemented

Provider đã chọn chưa triển khai thao tác này.

502

Bad Gateway

Adapter hoặc upstream provider không thể hoàn tất thao tác.

503

Service 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 quyền thử nghiệm, 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

invalid_request · 10000 · 400: Kiểm tra trường bắt buộc, định dạng và điều kiện kênh rồi sửa yêu cầu.
missing_api_key · 11000 · 401: Kiểm tra X-Api-Key và workspace còn hoạt động.
invalid_api_key · 11001 · 401: Kiểm tra X-Api-Key và workspace còn hoạt động.
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.
unsupported_by_provider · 30003 · 501: Xem hướng dẫn khả năng kênh và chọn kênh hoặc thao tác được hỗ trợ. Gửi lại không bổ sung hỗ trợ.
beta_feature_not_enabled · 41002 · 403: Liên hệ hỗ trợ kỹ thuật để xin quyền thử nghiệm kín cho không gian làm việc. Gửi lại hoặc sửa is_beta trong yêu cầu không cấp quyền.
call_already_active · 38000 · 409: Truy vấn cuộc gọi hiện tại để lấy call_id. Chờ kết thúc hoặc kết thúc cuộc gọi đó trước khi tạo cuộc gọi mới.