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

API ارسال پوش گروهی Lite؛ پارامترها و نمونه کد

راهنمای ارسال گروهی سبک با API پوشفا؛ ورودی‌ها و نمونه درخواست send-group-lite-message را برای ارسال پوش به گروه مخاطبان ببینید.

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

کاربرد

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

توصیه به استفاده از شناسه پایدار مخاطب (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 است. خیر
last_visit[operator] شرط اختیاری آخرین بازدید مخاطب — عملگر مقایسه: >=، >، <=، < یا = اگر last_visit ارسال شود، الزامی است
last_visit[date] تاریخ مبنای شرط: today (امروز)، today-N (N روز قبل، مثلاً today-7) یا تاریخ میلادی با قالب Y-m-d. پیام فقط برای مخاطبانی ارسال می‌شود که روز آخرین بازدیدشان (به وقت تهران) با این شرط بخواند؛ مثلاً operator برابر >= و date برابر today یعنی فقط کسانی که امروز بازدید داشته‌اند. اگر last_visit را نفرستید، ارسال بدون این شرط انجام می‌شود. اگر last_visit ارسال شود، الزامی است
send_time زمان ارسال؛ current برای ارسال فوری و delay برای زمان‌بندی‌شده. اختیاری و پیش‌فرض current است. نام قدیمی sendTime فعلاً پشتیبانی می‌شود، اما نباید هر دو نام همزمان ارسال شوند. خیر
time تاریخ میلادی و ساعت تهران (Asia/Tehran) را با قالب Y-m-d H:i وارد کنید؛ ثانیه صفر در نظر گرفته می‌شود. در حالت delay زمان باید بعد از اکنون باشد. تاریخ شمسی پذیرفته نمی‌شود. این قرارداد برای همه وب‌سرویس‌های ارسال، از جمله ارسال به تاپیک، یکسان است. اگر send_time برابر delay باشد، الزامی است
ttl مدت اعتبار پیام برای تحویل، بر حسب ثانیه. مقدار پیش‌فرض 86400 ثانیه، یعنی ۲۴ ساعت است. خیر

نمونه شخصی‌سازی‌شده 

{
  "topic": "all",
  "api_public_key": "YOUR_PUBLIC_KEY",
  "api_private_key": "YOUR_PRIVATE_KEY",
  "title": "{name:کاربر} عزیز",
  "body": "قیمت {product_name:محصول} به {new_price:نامشخص} تومان رسید.",
  "use_brackets": 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