Tài Liệu API

REST API của AgentSend. Tất cả yêu cầu và phản hồi đều dùng JSON. URL cơ sở: https://api.agentsend.io.

Tổng Quan

API AgentSend là một REST API cho phép các agent của bạn truy cập lập trình vào hộp thư, tin nhắn, chuỗi hội thoại, webhook, tên miền, tệp đính kèm, và cài đặt tài khoản. Mọi body yêu cầu và phản hồi đều là JSON.

Tất cả các endpoint API đều có sẵn dưới URL cơ sở:

https://api.agentsend.io

Xác Thực

API AgentSend hỗ trợ hai phương pháp xác thực. Bạn chỉ cần một phương pháp cho mỗi yêu cầu.

Bearer Token

Truyền API key của bạn dưới dạng Bearer token trong header Authorization. Đây là phương pháp được ưu tiên cho yêu cầu phía máy chủ.

curl https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>"

Header API Key

Hoặc, truyền API key của bạn trực tiếp trong header x-api-key.

curl https://api.agentsend.io/inboxes \
  -H "x-api-key: <your-api-key>"

Định Dạng Yêu Cầu

Gửi body yêu cầu dưới dạng JSON và bao gồm header Content-Type: application/json trên tất cả yêu cầu có body.

curl -X POST https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Support Agent"}'

Phân Trang

Các endpoint trả về danh sách hỗ trợ tham số truy vấn limit và offset để phân trang. Giới hạn mặc định là 20.

Tất cả phản hồi dạng danh sách đều bao gồm mảng data và số total của tất cả bản ghi khớp:

{
  "data": [ /* mảng các đối tượng */ ],
  "total": 142
}

Để lấy trang tiếp theo, tăng offset theo giá trị limit. Ví dụ, để lấy trang 3 với kích thước trang 20: ?limit=20&offset=40.

Xử Lý Lỗi

Lỗi trả về body JSON với đối tượng error chứa code dễ đọc bởi máy, message dễ đọc bởi con người, và status HTTP.

{
  "error": {
    "code": "INBOX_NOT_FOUND",
    "message": "Không tìm thấy hộp thư với ID đó.",
    "status": 404
  }
}

Các mã trạng thái HTTP phổ biến được API trả về:

Giới Hạn Tốc Độ

Tất cả các endpoint API đều có giới hạn tốc độ để bảo vệ sự ổn định nền tảng. Khi bạn vượt quá giới hạn, API trả về phản hồi 429 Too Many Requests.

Mỗi phản hồi API bao gồm header giới hạn tốc độ để bạn có thể theo dõi việc sử dụng:

Idempotency

Các yêu cầu POST có thể bao gồm header Idempotency-Key để thử lại yêu cầu an toàn mà không tạo tài nguyên trùng lặp. Nếu một yêu cầu với cùng idempotency key được nhận trong khoảng thời gian idempotency, phản hồi gốc sẽ được trả về thay vì tạo tài nguyên mới.

curl -X POST https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-request-id-abc123" \
  -d '{"displayName": "Support Agent"}'

Các Phần API

Duyệt tài liệu đầy đủ cho mỗi tài nguyên: