Tham chiếu API

Hội thoại

Liệt kê hội thoại

Liệt kê hội thoại theo thời gian thực. limit 1..100, mặc định 20. type dùng giá trị chính xác user / group / channel và không trim. Với WhatsApp, bỏ label_id chỉ trả hội thoại starred / “特别关注”. Cursor sai được xử lý khác nhau theo provider.

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

Kênh được hỗ trợ

TelegramWhatsAppLINEXTikTok

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

Tham số truy vấn

type
string

Các giá trị enum khớp chính xác, phân cách bằng dấu phẩy: user, group hoặc channel. Không cắt khoảng trắng, không đổi chữ hoa/thường và không bỏ qua mục rỗng. Giá trị không hợp lệ trả về 400 invalid_conversation_type. Với WhatsApp, group bao gồm cả nhóm thông báo cộng đồng; mọi hội thoại nhóm WhatsApp đều trả về type=group.

cursor
string

Con trỏ opaque của provider. Truyền nguyên vẹn next_cursor từ phản hồi trước; bỏ qua hoặc để trống cho trang đầu. Con trỏ giả mạo, hết hạn hoặc tái sử dụng giữa các truy vấn có thể bị bỏ qua, đặt lại về trang đầu hoặc gây lỗi provider. Không được dựa vào phản hồi 400 thống nhất.

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

label_id
string

Định danh label chính xác. Với WhatsApp, bỏ qua sẽ trả về hội thoại starred / “特别关注”.

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ả

Đánh giá kết quả theo các trường phản hồi và trạng thái HTTP của API này, rồi chọn bước tiếp theo từ các thao tác liên quan.

Phản hồi 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "items": [
      {
        "conversation_id": "peer_example",
        "type": "user",
        "title": "Display name",
        "avatar_url": "",
        "unread_count": 3,
        "last_message_at": "2026-05-13T10:00:00Z"
      }
    ],
    "next_cursor": "",
    "has_more": false
  }
}

Nội dung phản hồi

conversation_id
string

Định danh cuộc trò chuyện. Dùng làm đích khi gửi tin nhắn hoặc gọi các route cuộc trò chuyện.

type
string

Loại hội thoại chuẩn: user, group hoặc channel. Nhóm thông báo cộng đồng WhatsApp vẫn sử dụng group.

enum: user, group, channel

title
string

Tiêu đề hiển thị của cuộc trò chuyện.

username
string

Username cuộc trò chuyện phía provider, khi có.

avatar_url
string

URL ảnh đại diện, hoặc chuỗi rỗng khi không được đặt.

description
string

Mô tả nhóm hoặc kênh, khi có sẵn.

last_message_at
string

Dấu thời gian RFC3339 của tin nhắn gần nhất.

format: date-time

last_message_text
string

Bản xem trước văn bản của tin nhắn gần nhất, khi có.

unread_count
integer

Số tin nhắn chưa đọc trong cuộc trò chuyện.

format: int64

members_count
integer

Số thành viên; trả về cho các cuộc trò chuyện nhóm.

format: int64

subscribers_count
integer

Số người đăng ký của cuộc trò chuyện dạng kênh, khi có.

format: int64

is_pinned
boolean

Tài khoản kết nối có ghim cuộc trò chuyện hay không.

is_muted
boolean

Tài khoản kết nối có tắt tiếng cuộc trò chuyện hay không.

created_at
string

Thời gian tạo cuộc trò chuyện do provider báo cáo, khi có.

format: date-time

extra
object

Các trường mở rộng riêng của nhà cung cấp. Hội thoại nhóm WhatsApp có thể có phân loại nhóm thông báo; danh sách hội thoại không đảm bảo cung cấp phân loại này.

is_announcement_group
boolean

Chỉ có cho nhóm WhatsApp. true xác nhận đây là nhóm thông báo cộng đồng; false nghĩa là dữ liệu lần này xác nhận nhóm không đáp ứng điều kiện của nhóm thông báo. Thiếu trường nghĩa là chưa rõ; không trả về null. Phân loại này không cho biết tài khoản hiện tại có quyền gửi tin nhắn.

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