Contacts

Liệt kê liên hệ

Liệt kê liên hệ theo thời gian thực. limit 1..100, mặc định 50. Cursor sai hoặc hết hạn được mỗi provider xử lý khác nhau.

GEThttps://api.unifyport.ai/v1/accounts/{account_id}/contacts

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.

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

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ố đường dẫn

account_id

stringbắt buộc

Định danh dùng cho route contacts.

Tham số truy vấn

cursor

string

next_cursor opaque. Bỏ qua để bắt đầu; cursor sai hoặc hết hạn được các provider xử lý khác nhau.

limit

integer

Kích thước trang từ 1 đến 100; giá trị mặc định nằm trong mô tả endpoint.

minimum: 1 · maximum: 100

q

string

Bộ lọc tìm kiếm khớp với display_name, phone hoặc username.

updated_since

string

Dấu thời gian RFC3339; chỉ trả về các liên hệ được cập nhật kể từ thời điểm đó, phục vụ đồng bộ tăng dần khi nhà cung cấp hỗ trợ.

format: date-time

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": "user_example",
        "conversation_id": "peer_example",
        "display_name": "Alice",
        "avatar_url": "",
        "provider_user_id": "user_example",
        "extra": {
          "phone": "8600000000000"
        }
      }
    ],
    "next_cursor": "",
    "has_more": false
  }
}

Nội dung phản hồi

id

string

Định danh liên hệ.

conversation_id

string

Định danh cuộc trò chuyện cho liên hệ này; dùng để gửi tin nhắn hoặc định vị cuộc trò chuyện.

display_name

string

Tên hiển thị của liên hệ, hoặc chuỗi rỗng khi thiếu.

avatar_url

string

URL ảnh đại diện của liên hệ, hoặc chuỗi rỗng khi thiếu.

provider_user_id

string

Định danh người dùng phía nhà cung cấp cho liên hệ.

is_blocked

boolean

Liên hệ có bị tài khoản kết nối chặn hay không.

extra

object

Các trường bổ sung riêng của nhà cung cấp, ví dụ phone.

phone

string

WhatsApp phone JID 中解析出的纯手机号。

first_name

string

当前账号通讯录中保存的联系人简称或名字部分。

full_name

string

当前账号通讯录中保存的完整联系人名称。

push_name

string

联系人自行在 WhatsApp 设置的个人名称。

business_name

string

WhatsApp Business 账号的商业或认证名称。

redacted_phone

string

Provider 仅返回部分号码时的遮蔽手机号。

next_cursor

string

Con trỏ mờ cho trang tiếp theo. Truyền lại làm cursor; chuỗi rỗng nghĩa là không còn trang nào nữa.

has_more

boolean

true khi còn kết quả ngoài trang này.

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

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.

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.