Tài liệu tham khảo API Người đăng ký

Lấy danh sách người đăng ký

Endpoint:

GET /v2/:page_id/subscribers?page=:page&per_page=:per_page&search=:search_query

Số trang mặc định là 1.
Giá trị per_page mặc định là 50 và tối đa là 100 mục mỗi trang.
Tham số search tùy chọn được dùng để lọc người đăng ký theo địa chỉ email hoặc số điện thoại.

Phản hồi ví dụ

[
  {
    "id": "cm1111x6ofgsd5666mzxcw978qh",
    "email": "ali@instatus.com",
    "phone": null,
    "webhook": null,
    "webhookEmail": null,
    "confirmed": false,
    "all": true,
    "components": []
  },
  {
    "id": "cm1111x6ofgsd5666mzxcw978qh",
    "email": null,
    "phone": "5417543010",
    "webhook": null,
    "webhookEmail": null,
    "confirmed": false,
    "all": true,
    "components": []
  }
]

Thêm một người đăng ký

Endpoint:

POST /v1/:page_id/subscribers

Khi ai đó đăng ký, cách xử lý xác nhận tuân theo thiết lập subscriberConfirmationMode của trang. Dùng autoConfirm trên endpoint này để ghi đè hành vi đó cho một người đăng ký cụ thể.

Yêu cầu ví dụ

{
  "email": "sarah@instatus.com",
  "all": true,
  "autoConfirm": false
}

autoConfirm — tùy chọn. Khi bằng true, người đăng ký được thêm ngay mà không gửi email xác nhận hay email chào mừng, bất kể thiết lập của trang. Chỉ dành cho Pro.

Phản hồi ví dụ

{
  "id": "cm1111x6ofgsd5666mzxcw978df",
  "name": null,
  "email": "sarahs@instatus.com",
  "phone": null,
  "confirmed": false,
  "all": true,
  "createdAt": "2024-10-01T03:48:41.474Z",
  "updatedAt": "2024-10-01T03:48:41.474Z",
  "siteId": "cm1111x6ofgsd5666mzxcw978qh",
  "unsubscribeToken": "e3b51de6-1234-4664-zxyv-1679gg524260",
  "webhook": null,
  "webhookEmail": null,
  "discord": null,
  "discordTeam": null,
  "slack": null,
  "slackTeam": null,
  "language": "en",
  "company": null,
  "microsoftTeamsWebhook": null,
  "googleChatWebhook": null,
  "googleChatSpace": null,
  "failedAttempts": 0,
  "approved": true,
  "importedFrom": null,
  "hideUnsubLink": false,
  "webhookIncidentBody": null,
  "webhookMaintenanceBody": null,
  "webhookComponentBody": null,
  "webhookHttpMethod": "POST",
  "webhookHeaders": null,
  "site": {
    "id": "cm1111x6ofgsd5666mzxcw978qh"
  }
}

Đăng ký theo dõi một số thành phần cụ thể

Yêu cầu ví dụ

{
  "email": "adam@instatus.com",
  "all": false,
  "components": ["cl2xv23rl0119e7jlk2mweepd"],
  "autoConfirm": false
}

Phản hồi ví dụ

{
  "id": "cl09gt11151422bjluflghewx",
  "email": "adam@instatus.com",
  "site": {
    "id": "ckg8a112344s5v86wrn",
    "name": "Test",
    "logoUrl": null,
    "subdomain": "test",
    "publicEmail": null,
    "language": "en"
  }
}

Thêm nhiều người đăng ký

Endpoint:

POST /v1/:page_id/subscribers/bulk

Endpoint này cho phép bạn tạo nhiều người đăng ký trong một yêu cầu duy nhất.

Yêu cầu ví dụ

{
  "subscribers": [
    {
      "email": "sarah@instatus.com",
      "all": true
    },
    {
      "email": "john@instatus.com",
      "components": ["cl2xv23rl0119e7jlk2mweepd"]
    },
    {
      "name": "Jane Doe",
      "phone": "5417543010",
      "all": true
    }
  ],
  "autoConfirm": false
}

autoConfirm áp dụng cho mọi người đăng ký trong lô. Chỉ dành cho Pro.

Phản hồi ví dụ

{
  "success": true,
  "created": 3,
  "failed": 0,
  "results": {
    "created": [
      {
        "id": "cm1111x6ofgsd5666mzxcw978df",
        "email": "sarah@instatus.com",
        "phone": null,
        "confirmed": false,
        "all": true,
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      },
      {
        "id": "cm2222x6ofgsd5666mzxcw978df",
        "email": "john@instatus.com",
        "phone": null,
        "confirmed": false,
        "all": false,
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      },
      {
        "id": "cm3333x6ofgsd5666mzxcw978df",
        "email": null,
        "phone": "5417543010",
        "name": "Jane Doe",
        "confirmed": false,
        "all": true,
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      }
    ],
    "failed": []
  }
}

Phản hồi khi một số người đăng ký bị lỗi

Nếu một số người đăng ký không tạo được (ví dụ trùng email, sai định dạng), phản hồi sẽ kèm chi tiết về các lỗi đó:

{
  "success": false,
  "created": 2,
  "failed": 1,
  "results": {
    "created": [
      {
        "id": "cm1111x6ofgsd5666mzxcw978df",
        "email": "sarah@instatus.com",
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      },
      {
        "id": "cm2222x6ofgsd5666mzxcw978df",
        "email": "john@instatus.com",
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      }
    ],
    "failed": [
      {
        "index": 2,
        "subscriber": {
          "email": "duplicate@instatus.com",
          "all": true
        },
        "error": {
          "code": "creation_failed",
          "message": "Subscriber with this email already exists"
        }
      }
    ]
  }
}

Lưu ý:

Tối đa 100 người đăng ký mỗi yêu cầu
Mỗi object người đăng ký có thể dùng các trường giống endpoint thêm một người đăng ký
Hỗ trợ thành công một phần — những người đăng ký tạo thành công vẫn được trả về ngay cả khi một số bị lỗi

Cách xử lý xác nhận

Trang trạng thái quyết định cách xử lý người đăng ký mới qua subscriberConfirmationMode trên endpoint Cập nhật một trang trạng thái:

Giá trị	Hành vi
`REQUIRED`	Người đăng ký phải xác nhận qua email trước khi nhận cập nhật. Mặc định.
`WELCOME`	Người đăng ký được thêm ngay và nhận một email chào mừng. Chỉ dành cho Pro.
`NONE`	Người đăng ký được thêm ngay mà không có email nào. Chỉ dành cho Pro.

Tham số autoConfirm trên các endpoint tạo mới sẽ ghi đè thiết lập của trang cho yêu cầu đó và hoạt động như NONE.

Gỡ một người đăng ký

Endpoint:

DELETE /v1/:page_id/subscribers/:subscriber_id

Phản hồi ví dụ

{
  "id": "cm1zvzm3434dlp9255d6jgy8",
  "name": null,
  "email": "sarah@instatus.com",
  "phone": null,
  "webhook": null,
  "webhookEmail": null,
  "discord": null,
  "microsoftTeamsWebhook": null,
  "company": null,
  "site": {
    "id": "cm180slpo000g9343478qh"
  }
}