Lên lịch

Mọi endpoint đăng bài đều có thể phát hành ngay lập tức hoặc vào thời điểm sau. Bạn chọn chế độ thời gian cho từng request.

Đăng ngay

Đây là mặc định. Bỏ qua mọi trường lên lịch và bài đăng sẽ được phát hành ngay lập tức.

Lên lịch cho một thời điểm cụ thể

Thêm scheduled_at (ISO-8601) và tùy chọn timezone (tên IANA). MADIAD Hub giữ bài đăng và phát hành vào đúng thời điểm đó.

  -F "scheduled_at=2026-06-01T15:00:00Z" \
  -F "timezone=Asia/Ho_Chi_Minh"

scheduled_at được đọc theo UTC khi kết thúc bằng Z. Cung cấp timezone để xử lý chính xác giờ địa phương và giờ mùa hè.
Các bài đăng đã lên lịch trả về status: "scheduled". Chúng sẽ được đăng sau, bạn có thể theo dõi kết quả qua webhooks.
Bạn có thể lên lịch trước tối đa một năm.

Dùng hàng đợi định kỳ

Thay vì một mốc thời gian cụ thể, hãy đưa bài đăng vào hàng đợi của Profile bằng add_to_queue=true. Bài sẽ được phát hành vào khe thời gian mở tiếp theo theo lịch đăng đó.

  -F "add_to_queue=true"

scheduled_at và add_to_queue loại trừ lẫn nhau: chỉ đặt một trong hai, không dùng cả hai cùng lúc.

Cấu hình hàng đợi

Mỗi Profile có cấu hình hàng đợi riêng (timezone, ngày hoạt động, khe thời gian). Đọc cấu hình:

curl "https://api.madiad.com/v1/queue/settings?profile_id=$PROFILE_ID" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

Cập nhật bằng cách gửi ID của Profile kèm các trường bạn muốn đổi:

curl -X POST https://api.madiad.com/v1/queue/settings \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "'$PROFILE_ID'", "timezone": "Asia/Ho_Chi_Minh", "days": ["mon","wed","fri"], "slots": ["09:00","18:00"] }'

Quản lý bài đã lên lịch

Liệt kê các bài đang chờ lên lịch của một Profile:

curl "https://api.madiad.com/v1/schedule?profile_id=$PROFILE_ID" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

Lên lịch lại hoặc sửa một bài trước khi phát hành, truyền bất kỳ trong scheduled_at, timezone, hoặc caption:

curl -X PATCH https://api.madiad.com/v1/schedule/$JOB_ID \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-07-01T09:00:00Z", "timezone": "Asia/Ho_Chi_Minh" }'

Hủy một bài:

curl -X DELETE https://api.madiad.com/v1/schedule/$JOB_ID \
  -H "Authorization: Bearer $MADIAD_API_KEY"

$JOB_ID là job_id mà lệnh đăng trả về khi status là scheduled. Lệnh đăng không lên lịch trả job_id: null. Chỉ hủy hoặc sửa được một bài khi nó còn đang chờ trong lịch. Khi bài đã bắt đầu đăng, đã chạy xong, hoặc đã bị hủy trước đó, cả hai lệnh trả 400 invalid_request và không có gì thay đổi. Nếu lúc đó không đọc được lịch thì lệnh trả 502 và cũng không có gì thay đổi: hãy gọi lại. Xem một bài đang ở đâu bằng GET /v1/posts/status?job_id=$JOB_ID: câu trả lời là scheduled khi bài còn chờ tới giờ, sau đó là các trạng thái như mọi bài khác. Sau khi hủy thành công, câu trả lời là canceled, dù tra bằng job_id hay bằng request_id của bài, và giữ nguyên như vậy: bài sẽ không chạy nữa, nên vòng poll dừng ở đó. GET /v1/posts/history cũng ghi bài này là canceled. Nếu một phần của bài đã kịp đăng trước khi lệnh hủy tới, trạng thái là partial, và nền tảng đã đăng nằm trong results; lịch sử có thể vẫn ghi bài đó là canceled cho tới lần kiểm tra hằng ngày kế tiếp.

Hủy một bài đã lên lịch không xoá lượt đăng đã được ghi nhận từ lúc đó. Vì đăng bài không giới hạn trên các gói trả phí nên điều này không gây thiệt hại gì, khe đã hủy chỉ đơn giản vẫn nằm trong số liệu sử dụng của bạn.

Xem trước khung giờ hàng đợi

Kênh áp dụng: mọi kênh. Hàng đợi tính theo Profile, không theo kênh.

GET /v1/queue/settings cho biết khung giờ bạn đã đặt. Hai endpoint dưới trả lời câu khác: bài tiếp theo sẽ đi lúc nào.

curl "https://api.madiad.com/v1/queue/preview?profile_id=$PROFILE_ID&count=10" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

curl "https://api.madiad.com/v1/queue/next-slot?profile_id=$PROFILE_ID" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

count từ 1 đến 50 (mặc định 10). Mỗi khung trong preview cho biết đã có bao nhiêu bài, sức chứa là bao nhiêu, và khung đó còn trống hay không.

next_slot trả về null khi không còn khung trống trong 30 ngày tới. Đó là câu trả lời, không phải lỗi.

Múi giờ mặc định của hàng đợi là America/New_York, khung 9:00 / 12:00 / 17:00. Với Việt Nam đó là 20:00 / 23:00 / 04:00. Nếu bạn dùng add_to_queue, hãy đặt lại múi giờ bằng POST /v1/queue/settings trước.

Bắt đầu

Khái niệm

Tích hợp

Tham chiếu API

Đăng ngay

Lên lịch cho một thời điểm cụ thể

Dùng hàng đợi định kỳ

Cấu hình hàng đợi

Quản lý bài đã lên lịch

Xem trước khung giờ hàng đợi

​Đăng ngay

​Lên lịch cho một thời điểm cụ thể

​Dùng hàng đợi định kỳ

​Cấu hình hàng đợi

​Quản lý bài đã lên lịch

​Xem trước khung giờ hàng đợi

Đăng ngay

Lên lịch cho một thời điểm cụ thể

Dùng hàng đợi định kỳ

Cấu hình hàng đợi

Quản lý bài đã lên lịch

Xem trước khung giờ hàng đợi