Tham chiếu API

Hội thoại

Yêu cầu truy xuất lịch sử hội thoại

Chỉ yêu cầu lịch sử cũ hơn cho trò chuyện riêng của provider=whatsapp, không gồm whatsapp-protocol. account_id phải là một đoạn đường dẫn không rỗng, không chứa khoảng trắng hay dấu gạch chéo, kể cả dạng mã hóa; đường dẫn sai trả về 400 invalid_request. Đăng ký conversation.history trước; các lô khả dụng đến bất đồng bộ với data.history.source=on_demand. HTTP 202 và status=accepted chỉ xác nhận tiếp nhận, không phải đã nhận tin nhắn hay hoàn tất. request_id dùng chẩn đoán HTTP, không phải ID tác vụ và không dùng liên kết callback. Có thể có nhiều lô, trùng lặp, đến muộn hoặc không có callback. Để truy xuất tiếp, chọn tin nhắn nội dung gốc cũ nhất đã nhận có đủ id, sent_at, direction làm before; loại bỏ bản ghi tổng hợp type=call và không thêm type vào before. Không có con trỏ trang tiếp theo hay trạng thái hoàn tất; lô rỗng, số lượng ít hơn limit hoặc hết thời gian chờ không chứng minh đã hết lịch sử. Callback có thể đến sau khi HTTP hết thời gian chờ; không tự động thử lại. 400 có thể trả invalid_request, provider_invalid_request (gồm mốc là bản ghi cuộc gọi tổng hợp), hoặc unsupported_conversation_type cho nhóm/kênh. Nhà cung cấp khác trả 501 unsupported_by_provider. Đường dẫn hợp lệ nhưng tài khoản không tồn tại hoặc không thuộc không gian làm việc hiện tại trả 404 account_not_found (numeric_code=20020); lỗi nội bộ chưa phân loại trả 500 request_conversation_history_failed (numeric_code=37016).

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/conversations/history/request

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.

Content-Type
stringbắt buộc

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

Tham số đường dẫn

account_id
stringbắt buộc

Định danh dùng cho route conversations.

Nội dung yêu cầu

conversation_id
stringbắt buộc

LID trò chuyện riêng tiêu chuẩn của WhatsApp khớp ^[0-9]+@lid$, thuộc cùng cuộc hội thoại với before. Không chấp nhận số điện thoại hay loại hội thoại khác.

pattern: ^[0-9]+@lid$

before
objectbắt buộc

Vị trí của một tin nhắn nội dung gốc trong cùng cuộc hội thoại; mọi trường phải lấy từ tin nhắn đó và không được là null. Bản ghi cuộc gọi tổng hợp type=call không hợp lệ dù đủ ba trường. Không đưa type vào yêu cầu.

message_id
stringbắt buộc

id của tin nhắn nội dung gốc, có ký tự không phải khoảng trắng. ID bản ghi cuộc gọi tổng hợp vẫn không hợp lệ sau khi bỏ khoảng trắng đầu cuối. Không thay bằng id sự kiện cấp cao nhất hoặc HTTP request_id.

minLength: 1 · pattern: \S

sent_at
stringbắt buộc

Thời gian gửi RFC3339 của tin nhắn đó, với số giây Unix lớn hơn 0. Không thay bằng occurred_at của sự kiện hoặc thời gian hiện tại.

format: date-time

direction
stringbắt buộc

Hướng tin nhắn đối với tài khoản hiện tại: inbound là nhận, outbound là gửi.

enum: inbound, outbound

limit
integer

Số lượng yêu cầu, không đảm bảo số lượng thực nhận. Chỉ mặc định 50 khi bỏ qua; null, 0, số không nguyên hoặc lớn hơn 50 trả về invalid_request. Phạm vi hợp lệ: 1..50.

minimum: 1 · maximum: 50

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 202 Accepted

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "status": "accepted",
    "conversation_id": "100000000000002@lid",
    "limit": 50
  }
}

Nội dung phản hồi

status
string

accepted confirms request acceptance only, not receipt of history or completion.

enum: accepted

conversation_id
string

Standard conversation ID for this history request.

limit
integer

Effective requested count limit for this history request, from 1 to 50.

minimum: 1 · maximum: 50

Phản hồi

202

202 Accepted

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

404

Not Found

Không tìm thấy tài nguyên provider được yêu cầu.

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.