Tham chiếu API

Tài khoản

Tạo tài khoản

Tạo tài khoản provider. auth_mode bắt buộc và phải là qrcode, code hoặc session. Khi cặp provider + auth_mode cần số điện thoại, hãy gửi provider_data.phone; giá trị được lưu cho các bước xác thực sau.

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

Kênh được hỗ trợ

all

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.

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

name
string

Tên tài khoản dễ đọc.

provider
stringbắt buộc

Mã định danh provider cho khách hàng: telegram, whatsapp, whatsapp-protocol, line, twitter, zalo hoặc tiktok.

enum: telegram, whatsapp, line, twitter, zalo, tiktok, whatsapp-protocol, x, x_client, twitter_client

region
stringbắt buộc

Khu vực của nhà cung cấp dùng để phân bổ. Hãy chọn khu vực được báo cáo allocatable: true qua Liệt kê khu vực của nhà cung cấp.

minLength: 1

status
string

Trạng thái nghiệp vụ của tài khoản, như active hoặc inactive.

runtime_status
string

Trạng thái runtime yêu cầu khi provider hỗ trợ thay đổi qua cấu hình tài khoản.

enum: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error

auth_mode
stringbắt buộc

Bắt buộc khi tạo tài khoản: qrcode, code hoặc session.

enum: qrcode, code, session

capabilities[]
string[]

Với PATCH, bỏ qua để giữ nguyên, gửi [] để xoá; null không hợp lệ.

metadata
object

Với PATCH, bỏ qua để giữ nguyên, gửi {} để xoá; null không hợp lệ.

provider_account_ref
string

Danh tính tài khoản phía provider, thường được điền sau khi xác thực.

provider_data
object

Cấu hình nhà cung cấp. Với PATCH, bỏ qua để giữ nguyên; {} xóa mà không thêm thông tin xác thực mặc định; null không hợp lệ. TikTok provider_data.enable_comment chỉ nhận Boolean, mặc định false; chuỗi, số và null trả 400 invalid_request. Thay đổi khi trực tuyến cần reconnect; start thành công không chứng minh đã áp dụng, tắt không thu hồi sự kiện đã xếp hàng. Telegram api_id và api_hash là tùy chọn cho code, qrcode và session; thông tin tùy chỉnh phải là cặp chuỗi từ cùng ứng dụng. Tạo không có thông tin tùy chỉnh và các trường xác thực bị bỏ qua khi thay bằng cấu hình không rỗng sẽ dùng mặc định của nền tảng; yêu cầu thất bại nếu mặc định cần thiết không khả dụng. Đổi mặc định không thay thông tin xác thực của tài khoản hiện có. Không ghi bí mật vào log.

proxy
object

Cấu hình proxy gửi ra tùy chọn cho tài khoản này.

Hiểu kết quả

201 xác nhận tài nguyên tài khoản đã được tạo. Lưu data.id làm account_id và tiếp tục xác thực theo kênh đã chọn. Tạo tài khoản chưa có nghĩa là đã xác thực hoặc kết nối trực tuyến.

Phản hồi 201 Created

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "acc_example",
    "name": "Telegram Production",
    "provider": "telegram",
    "region": "<REGION>",
    "status": "active",
    "runtime_status": "stopped",
    "auth_mode": "qrcode",
    "capabilities": [
      "send_message",
      "receive_message"
    ]
  }
}

Nội dung phản hồi

provider_profile
object

Hồ sơ do nhà cung cấp báo cáo, ví dụ display_name. Bị bỏ qua trước khi tài khoản được xác thực.

id
string

Định danh opaque của tài khoản trên kênh đã kết nối. Với WhatsApp, đây có thể là canonical LID không có hậu tố thiết bị.

device_id
integer

Số thiết bị đăng nhập tùy chọn trong chi tiết tài khoản WhatsApp khi xác định được phiên hiện tại. Có thể thay đổi sau khi xác thực lại và không phải mã thiết bị cố định.

minimum: 0 · maximum: 65535

phone
string

Số điện thoại đã chuẩn hóa, bỏ khoảng trắng, gạch nối và dấu + đầu.

username
string

username do provider báo cáo, nếu có.

display_name
string

Tên hiển thị của tài khoản; với WhatsApp, tên này được tạo bằng cách ưu tiên BusinessName và dùng PushName làm giá trị dự phòng.

push_name
string

PushName hiện được đặt trên tài khoản WhatsApp; các provider khác không định nghĩa ngữ nghĩa cho trường này.

business_name
string

WhatsApp BusinessName; trường này bị bỏ qua khi provider không trả về giá trị.

first_name
string

Tên do provider báo cáo, nếu có.

last_name
string

Họ do provider báo cáo, nếu có.

avatar_url
string

URL avatar tài khoản do provider báo cáo.

bio
string

Tiểu sử hoặc trạng thái tài khoản do provider báo cáo.

platform
string

Định danh nền tảng đăng nhập do WhatsApp báo cáo khi ghép nối. Hãy coi đây là chuỗi opaque và chấp nhận giá trị chưa biết; các provider khác không định nghĩa ý nghĩa của trường này. Trường này khác với device_platform.

id
string

Định danh tài khoản duy nhất (acc_...). Dùng trong các route theo phạm vi tài khoản.

name
string

Tên tài khoản dễ đọc.

provider
string

Mã định danh kênh. Dùng nguyên giá trị API trả về trong các lần gọi sau; xem enum bên dưới để biết giá trị của API này.

enum: telegram, whatsapp, line, twitter, zalo, tiktok, whatsapp-protocol

region
string

Khu vực nhà cung cấp mà tài khoản được phân bổ tới.

status
string

Trạng thái vòng đời của tài khoản, ví dụ active.

runtime_status
string

Trạng thái runtime đã chuẩn hoá: một trong unknown, starting, running, stopping, stopped, reconnecting, disconnected hoặc error.

enum: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error

auth_mode
string

Luồng xác thực mà tài khoản dùng: code, qrcode hoặc session.

capabilities[]
string[]

Các năng lực được bật cho tài khoản, ví dụ send_message và receive_message.

metadata
object

Nhãn môi trường của riêng bạn được lưu trên tài khoản.

provider_account_ref
string

Định danh phía nhà cung cấp mà bạn có thể gắn để liên kết tài khoản với hệ thống của riêng mình.

proxy
object

Cấu hình proxy gửi ra của tài khoản, khi đã thiết lập.

Phản hồi

201

201 Created

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

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.

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. Sửa tham số, tiếp tục xác thực hoặc kiểm tra runtime tùy nguyên nhân. Xác nhận kết quả cũ trước khi thử lại thao tác gửi hoặc ghi. 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.