مستندات وب‌سرویس‌ها وب سرویس های ارسال اعلان پوش API ارسال پوش گروهی با گزارش تحویل و کلیک

API ارسال پوش گروهی با گزارش تحویل و کلیک

پیام گروهی را با وب‌سرویس پوشفا ارسال کنید؛ پارامترهای مخاطبان، محتوای پیام و فعال‌سازی گزارش تحویل و کلیک را همراه با نمونه درخواست ببینید.

POST
https://pushfa.com/api/webservices/send-group-message
دانلود کالکشن Postman

کاربرد

وقتی لازم است وضعیت تحویل، کلیک و لیست گیرندگان کمپین را پیگیری کنید از این API استفاده کنید. از پنل پوشفا می‌توانید گزارش کامل هر کمپین را مشاهده کنید.

توصیه به استفاده از شناسه پایدار مخاطب (subscriber_id) به جای توکن فایربیس (fcm_token) در ذخیره و ارسال
برای ارسال تکی به یک مخاطب از subscriber_id و برای ارسال گروهی به چند مخاطب از subscriber_ids[] استفاده کنید. این شناسه‌ها با چرخش توکن تغییر نمی‌کنند و پایداری بیشتری دارند.
در حال حاضر، کلیدهای fcm_token برای ارسال تکی و fcm_tokens[] برای ارسال گروهی به دلیل پایداری کمتر منسوخ شده‌اند؛ بااین‌حال، برای حفظ سازگاری همچنان پشتیبانی می‌شوند.
ارسال هم‌زمان subscriber_id و fcm_token یا subscriber_ids و fcm_tokens، حتی با مقدار خالی، باعث خطای اعتبارسنجی ۴۲۲ می‌شود.
برای اطلاعات بیشتر به مستندات دریافت توکن مراجعه کنید.

پارامترهای ورودی

پارامترمقداراجباری
subscriber_ids[] پیشنهادی یا fcm_tokens[] آرایه شناسه‌های ثابت گیرندگان (UUID) یا توکن‌های fcm_tokens[] — در صورت استفاده از topic نباید ارسال شود اگر topic ارسال نشود، الزامی است
topic شناسه تاپیک مقصد؛ برای ارسال به همه کاربران مقدار all را وارد کنید اگر subscriber_ids ارسال نشود، الزامی است
device محدودیت دستگاه: mobile، desktop یا all خیر
api_public_key کلید عمومی سرویس پوشفا بله
api_private_key کلید خصوصی سرویس پوشفا بله
title عنوانی که بالای اعلان نمایش داده می‌شود بله
body متن اصلی که زیر عنوان اعلان نمایش داده می‌شود بله
link_url لینک مقصد پس از کلیک روی اعلان (مثال: https://example.com) خیر
image_url آدرس تصویر ضمیمه اعلان خیر
use_brackets برای شخصی‌سازی پیام، مقدار true را بفرستید. در این حالت بخش‌های متغیر عنوان (title) و متن (body) با اطلاعات پروفایل هر گیرنده پر می‌شوند. مقدار پیش‌فرض false است. خیر
btn_left[title] عنوان دکمه سمت چپ در صورت تعریف دکمه چپ، الزامی است
btn_left[url] لینک دکمه سمت چپ (مثال: https://example.com) در صورت تعریف دکمه چپ، الزامی است
btn_right[title] عنوان دکمه سمت راست در صورت تعریف دکمه راست، الزامی است
btn_right[url] لینک دکمه سمت راست (مثال: https://example.com) در صورت تعریف دکمه راست، الزامی است
throttle_rate_per_minute نرخ ارسال این پیام بر حسب پیام در دقیقه. فقط وقتی Push Throttling سرویس فعال و اجازه Override روشن باشد مقدار ارسالی جایگزین نرخ پیش‌فرض می‌شود. خیر
silentپوش بی‌صدا مقدار true اعلان را بدون صدا و لرزش نمایش می‌دهد؛ این گزینه اعلان را پنهان نمی‌کند. خیر
collapse_idCollapse ID Collapse ID — رشته متنی حداکثر ۱۰۰ کاراکتر برای جایگزینی اعلان قبلی با اعلان جدید دارای همان شناسه. خیر
additional_dataAdditional DataPro Additional Data (JSON) — شیء JSON دلخواه که همراه پیام ارسال می‌شود و در SDK/Service Worker قابل خواندن است. خیر - فقط Pro
last_visit[operator] شرط اختیاری آخرین بازدید مخاطب — عملگر مقایسه: >=، >، <=، < یا = اگر last_visit ارسال شود، الزامی است
last_visit[date] تاریخ مبنای شرط: today (امروز)، today-N (N روز قبل، مثلاً today-7) یا تاریخ میلادی با قالب Y-m-d. پیام فقط برای مخاطبانی ارسال می‌شود که روز آخرین بازدیدشان (به وقت تهران) با این شرط بخواند؛ مثلاً operator برابر >= و date برابر today یعنی فقط کسانی که امروز بازدید داشته‌اند. اگر last_visit را نفرستید، ارسال بدون این شرط انجام می‌شود. اگر last_visit ارسال شود، الزامی است
get_delivery_status درخواست گزارش تحویل (مقدار 1/0 در ارسال تکی یا true/false در ارسال گروهی) خیر
webhook_url آدرس وب‌هوک بومرنگ — در صورت عدم تحویل، نتیجه به این آدرس ارسال می‌شود خیر
get_click_status درخواست گزارش کلیک (مقدار 1/0 در ارسال تکی یا true/false در ارسال گروهی) خیر
send_time زمان ارسال؛ current برای ارسال فوری و delay برای زمان‌بندی‌شده. اختیاری و پیش‌فرض current است. نام قدیمی sendTime فعلاً پشتیبانی می‌شود، اما نباید هر دو نام همزمان ارسال شوند. خیر
time تاریخ میلادی و ساعت تهران (Asia/Tehran) را با قالب Y-m-d H:i وارد کنید؛ ثانیه صفر در نظر گرفته می‌شود. در حالت delay زمان باید بعد از اکنون باشد. تاریخ شمسی پذیرفته نمی‌شود. این قرارداد برای همه وب‌سرویس‌های ارسال، از جمله ارسال به تاپیک، یکسان است. اگر send_time برابر delay باشد، الزامی است
ttl مدت اعتبار پیام برای تحویل، بر حسب ثانیه. مقدار پیش‌فرض 86400 ثانیه، یعنی ۲۴ ساعت است. خیر

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

curl -X POST https://pushfa.com/api/webservices/send-group-message \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "topic": "all",
    "title": "عنوان کمپین",
    "body": "{name:کاربر} عزیز، قیمت {product_name:محصول} به {new_price:نامشخص} تومان رسید.",
    "use_brackets": true,
    "silent": false,
    "collapse_id": "campaign_summer_sale",
    "additional_data": { "campaign": "summer_sale" },
    "get_delivery_status": true,
    "get_click_status": true,
    "send_time": "current"
  }'

ارسال به شناسه‌های ثابت مخاطبان 

{
  "api_public_key": "YOUR_PUBLIC_KEY",
  "api_private_key": "YOUR_PRIVATE_KEY",
  "subscriber_ids": ["f1444a41-b3af-4e30-8655-9a70de1e0915"],
  "title": "پیام جدید",
  "body": "متن پیام",
  "send_time": "current"
}

شرط اختیاری آخرین بازدید (last_visit)

با پارامتر اختیاری last_visit پیام فقط برای مخاطبانی ارسال می‌شود که روز آخرین بازدیدشان از سایت یا اپ (به وقت تهران) با شرط شما بخواند. نمونه زیر فقط برای کسانی ارسال می‌شود که امروز بازدید داشته‌اند. با topic فقط اعضای واجد شرط پیام می‌گیرند و اگر هیچ عضوی شرط را نداشته باشد، خطای 422 با کد LAST_VISIT_CONDITION_NOT_MET برمی‌گردد. با subscriber_ids یا fcm_tokens هر شناسه جداگانه بررسی می‌شود و شناسه‌های فاقد شرط با همین کد در rejected_recipients برمی‌گردند.

مقدار date می‌تواند today، today-N (مثلاً today-7) یا تاریخ میلادی Y-m-d باشد و operator یکی از >=، >، <=، < یا = است. شرط و مقدار today هنگام ثبت درخواست محاسبه می‌شوند، حتی در ارسال زمان‌بندی‌شده. این شرط به روشن‌بودن ثبت آخرین بازدید در تنظیمات سرویس نیاز دارد؛ در غیر این صورت خطای 403 با کد LAST_VISIT_TRACKING_DISABLED برمی‌گردد.
{
  "api_public_key": "YOUR_PUBLIC_KEY",
  "api_private_key": "YOUR_PRIVATE_KEY",
  "topic": "all",
  "title": "پیشنهاد امروز",
  "body": "ویژه کاربرانی که امروز به ما سر زده‌اند",
  "last_visit": { "operator": ">=", "date": "today" },
  "send_time": "current"
}
توضیح کامل شرط last_visit

خطاها و کدهای پاسخ

خطاهای عمومی مانند INVALID_API_KEYS، VALIDATION_ERROR و INSUFFICIENT_BALANCE در همه وب‌سرویس‌های ارسال مشترک‌اند. با subscriber_ids یا fcm_tokens هر شناسه جداگانه بررسی می‌شود و شناسه‌های ردشده با یکی از کدهای SUBSCRIBER_NOT_FOUND، FCM_TOKEN_NOT_FOUND، PUSH_TOKEN_EXPIRED، PUSH_NOT_SUBSCRIBED یا FREQUENCY_CAP_REACHED در data.rejected_recipients برمی‌گردند؛ اگر هیچ شناسه‌ای قابل ارسال نباشد، درخواست با کد مشترک شناسه‌ها یا NO_VALID_RECIPIENTS رد می‌شود. با topic اگر ارسال ممکن نباشد، کل درخواست با یکی از کدهای TOPIC_NOT_FOUND، NO_ACTIVE_PUSH_SUBSCRIPTION، NO_MATCHING_DEVICE یا FREQUENCY_CAP_REACHED رد می‌شود. اگر شرط اختیاری last_visit را بفرستید، LAST_VISIT_TRACKING_DISABLED و LAST_VISIT_CONDITION_NOT_MET هم ممکن است برگردند. معنی هر کد و اینکه چه زمانی باید توکن یا شناسه را حذف کنید در صفحه خطاها آمده است.

در ارسال زمان‌بندی‌شده (send_time برابر delay)، time باید تاریخ میلادی با قالب Y-m-d H:i و ساعت تهران (Asia/Tehran) باشد. قالب نامعتبر با VALIDATION_ERROR و زمان گذشته یا همین لحظه با خطای 422 و کد INVALID_SEND_TIME رد می‌شود؛ در هر دو حالت پیامی ساخته نمی‌شود و هزینه‌ای کسر نمی‌شود.
خطاها و کدهای پاسخ وب‌سرویس‌های ارسال
Ctrl+I