Tài khoản

Liệt kê tài khoản

Liệt kê các tài khoản nhà cung cấp trong workspace hiện tại. Trạng thái xác thực được expose qua nhóm Authentication.

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

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.

Tham số truy vấn

limit

integer

Số tài khoản tối đa mỗi trang, từ 1 đến 100; mặc định là 20 nếu bỏ qua. Giá trị không hợp lệ hoặc truyền lặp tham số limit sẽ trả về 400 invalid_request (numeric_code=10000). Có thể thay đổi giá trị ở các trang tiếp theo.

minimum: 1 · maximum: 100

cursor

string

Con trỏ mờ của danh sách tài khoản. Bỏ qua hoặc truyền chuỗi rỗng để đọc trang đầu; truyền nguyên data.next_cursor của phản hồi trước cho trang tiếp theo. Chỉ dùng được trong workspace đã cấp con trỏ. cursor không hợp lệ, truyền lặp hoặc dùng khác workspace sẽ trả về 400 invalid_request (numeric_code=10000).

Nội dung yêu cầu

Điểm cuối này không cần nội dung JSON.

Hiểu kết quả

Đọc trường phản hồi và trạng thái HTTP được mô tả. Thành công 204 không có nội dung; dùng X-Request-Id để chẩn đoán. Xem thao tác liên quan cho bước tiếp theo.

Phản hồi 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "items": [
      {
        "id": "acc_example",
        "name": "Telegram Production",
        "provider": "telegram",
        "region": "global",
        "status": "active",
        "runtime_status": "running",
        "auth_mode": "qrcode",
        "capabilities": [
          "send_message",
          "receive_message"
        ],
        "metadata": {
          "env": "production"
        },
        "provider_account_ref": "provider-side-identifier",
        "provider_profile": {
          "id": "778899",
          "phone": "8600000000000",
          "username": "production_bot",
          "display_name": "Production Bot",
          "first_name": "Production",
          "last_name": "Bot",
          "avatar_url": "https://example.com/avatar.jpg",
          "bio": "Customer support"
        }
      }
    ],
    "has_more": false
  }
}

Nội dung phản hồi

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.

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

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.

has_more

boolean

Danh sách tài khoản có còn trang tiếp theo hay không.

next_cursor

string

Con trỏ mờ cho trang tiếp theo của danh sách tài khoản, chỉ trả về khi has_more=true. Truyền nguyên giá trị làm cursor cho trang tiếp theo; trường này được bỏ qua ở trang cuối.

Phản hồi

200

200 OK

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

500

Internal Server Error

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

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.
invalid_api_key · 11001 · 401: Kiểm tra X-Api-Key và workspace còn hoạt động.