مرجع واجهة المشتركين البرمجية

احصل على المشتركين

نقطة النهاية:

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