مرجع API مشترکان

دریافت مشترکان

نقطه پایانی:

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

• شماره صفحه پیش‌فرض ۱ است.
• مقدار پیش‌فرض per_page برابر ۵۰ و بیشینه ۱۰۰ آیتم در هر صفحه است.
• پرس‌وجوی جست‌وجوی اختیاری برای فیلتر کردن مشترکان بر اساس نشانی ایمیل یا شماره تلفن به کار می‌رود.

نمونه پاسخ

[
  {
    "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": []
  }
]

افزودن یک مشترک

نقطه پایانی:

POST /v1/:page_id/subscribers

وقتی کسی مشترک می‌شود، رفتار تأیید از تنظیم subscriberConfirmationMode صفحه پیروی می‌کند. برای بازنویسی این رفتار برای یک مشترک خاص، از autoConfirm در این نقطه پایانی استفاده کنید.

نمونه درخواست

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

• autoConfirm — اختیاری. وقتی true باشد، مشترک را بی‌درنگ و بدون فرستادن ایمیل تأیید یا خوش‌آمد اضافه می‌کند، فارغ از تنظیم صفحه. فقط Pro.

نمونه پاسخ

{
  "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"
  }
}

اشتراک در اجزای مشخص

نمونه درخواست

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

نمونه پاسخ

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

افزودن چند مشترک

نقطه پایانی:

POST /v1/:page_id/subscribers/bulk

این نقطه پایانی به شما امکان می‌دهد چند مشترک را در یک درخواست بسازید.

نمونه درخواست

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

• autoConfirm روی همه مشترکان دسته اعمال می‌شود. فقط Pro.

نمونه پاسخ

{
  "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": []
  }
}

پاسخ وقتی ساخت برخی مشترکان ناموفق باشد

اگر ساخت برخی مشترکان ناموفق باشد (مثلاً ایمیل تکراری یا قالب نادرست)، پاسخ شامل جزئیات ناکامی‌ها خواهد بود:

{
  "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"
        }
      }
    ]
  }
}

نکته‌ها:

• حداکثر ۱۰۰ مشترک در هر درخواست
• هر شیء مشترک می‌تواند همان فیلدهای نقطه پایانی تک‌مشترکی را داشته باشد
• موفقیت جزئی پشتیبانی می‌شود — مشترکانی که با موفقیت ساخته شده‌اند برگردانده می‌شوند حتی اگر برخی ناموفق باشند

رفتار تأیید

صفحه‌های وضعیت نحوه برخورد با مشترکان جدید را از طریق subscriberConfirmationMode در نقطه پایانی به‌روزرسانی یک صفحه وضعیت کنترل می‌کنند:

مقدار	رفتار
REQUIRED	مشترکان باید پیش از دریافت به‌روزرسانی‌ها با ایمیل تأیید کنند. پیش‌فرض.
WELCOME	مشترکان بی‌درنگ اضافه می‌شوند و ایمیل خوش‌آمد دریافت می‌کنند. فقط Pro.
NONE	مشترکان بی‌درنگ و بدون هیچ ایمیلی اضافه می‌شوند. فقط Pro.

پارامتر autoConfirm در نقاط پایانی ساخت، تنظیم صفحه را برای آن درخواست بازنویسی می‌کند و مانند NONE رفتار می‌کند.

حذف یک مشترک

نقطه پایانی:

DELETE /v1/:page_id/subscribers/:subscriber_id

نمونه پاسخ

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