API ارسال پوش به Subscriber ID؛ نمونه درخواست
با شناسه مشترک به مخاطب مشخص پوش بفرستید؛ پارامترهای send-via-subscriber-id و نمونه درخواست احراز هویت‌شده را در مستندات پوشفا ببینید.
کاربرد
شناسه ثابت مخاطب (Subscriber ID) برخلاف توکن FCM در طول زمان ثابت می‌ماند. پس از پذیرش اعلان و ثبت موفق توکن، آن را روی کاربرتان ذخیره کنید و از این API برای ارسال استفاده کنید.
پارامترهای ورودی
| پارامتر | مقدار | اجباری |
|---|---|---|
| subscriber_ids[] | آرایه‌ای از شناسه ثابت مخاطب (Subscriber ID)های مقصد | بله |
| device | محدودیت دستگاه: all، mobile یا desktop | خیر |
| api_public_key | کلید عمومی سرویس پوشفا | بله |
| api_private_key | کلید خصوصی سرویس پوشفا | بله |
| title | عنوانی که بالای اعلان نمایش داده می‌شود | بله |
| body | متن اصلی که زیر عنوان اعلان نمایش داده می‌شود | بله |
| link_url | لینک مقصد پس از کلیک روی اعلان (مثال: https://example.com) | خیر |
| image_url | آدرس تصویر ضمیمه اعلان | خیر |
| use_brackets | برای شخصی‌سازی پیام، مقدار true را بفرستید. در این حالت بخش‌های متغیر عنوان (title) و متن (body) با اطلاعات پروفایل هر گیرنده پر می‌شوند. مقدار پیش‌فرض false است. | خیر |
| 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-via-subscriber-id \
-H "Content-Type: application/json" \
-d '{
"api_public_key": "YOUR_PUBLIC_KEY",
"api_private_key": "YOUR_PRIVATE_KEY",
"subscriber_ids": ["8f3c…", "a91b…"],
"title": "عنوان پیام",
"body": "متن پیام",
"send_time": "current"
}'شرط اختیاری آخرین بازدید (last_visit)
با پارامتر اختیاری last_visit پیام فقط برای مخاطبانی ارسال می‌شود که روز آخرین بازدیدشان از سایت یا اپ (به وقت تهران) با شرط شما بخواند. نمونه زیر فقط برای کسانی ارسال می‌شود که امروز بازدید داشته‌اند. هر شناسه جداگانه بررسی می‌شود؛ شناسه‌هایی که شرط را ندارند با کد LAST_VISIT_CONDITION_NOT_MET در rejected_recipients برمی‌گردند و برای بقیه پیام ارسال می‌شود.
{
"api_public_key": "YOUR_PUBLIC_KEY",
"api_private_key": "YOUR_PRIVATE_KEY",
"subscriber_ids": ["SUBSCRIBER_UUID_1", "SUBSCRIBER_UUID_2"],
"title": "پیشنهاد امروز",
"body": "ویژه کاربرانی که امروز به ما سر زده‌اند",
"last_visit": { "operator": ">=", "date": "today" },
"send_time": "current"
}خطاها و کدهای پاسخ
خطاهای عمومی مانند INVALID_API_KEYS، VALIDATION_ERROR و INSUFFICIENT_BALANCE در همه وب‌سرویس‌های ارسال مشترک‌اند. هر شناسه جداگانه بررسی می‌شود و شناسه‌های ردشده با یکی از کدهای SUBSCRIBER_NOT_FOUND، PUSH_TOKEN_EXPIRED، PUSH_NOT_SUBSCRIBED، NO_MATCHING_DEVICE یا FREQUENCY_CAP_REACHED در data.rejected_recipients برمی‌گردند. اگر هیچ شناسه‌ای قابل ارسال نباشد، درخواست با کد مشترک شناسه‌ها یا در صورت تفاوت علت‌ها با NO_VALID_RECIPIENTS رد می‌شود. اگر شرط اختیاری 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 رد می‌شود؛ در هر دو حالت پیامی ساخته نمی‌شود و هزینه‌ای کسر نمی‌شود.شناسه پایدار مخاطب و سازگاری با کلیدهای قدیمی
از subscriber_id برای یک مخاطب و subscriber_ids[] برای چند مخاطب استفاده کنید؛ این شناسه‌ها با چرخش توکن تغییر نمی‌کنند و پایدارترند. کلیدهای fcm_token و fcm_tokens[] به دلیل پایداری کمتر منسوخ شده‌اند، اما برای سازگاری همچنان پشتیبانی می‌شوند. ارسال همزمان subscriber_id و fcm_token یا subscriber_ids و fcm_tokens، حتی با مقدار خالی، خطای اعتبارسنجی 422 می‌دهد.