API ارسال پوش به Subscriber ID؛ نمونه درخواست
با شناسه مشترک به مخاطب مشخص پوش بفرستید؛ پارامترهای send-via-subscriber-id و نمونه درخواست احراز هویتشده را در مستندات پوشفا ببینید.
POST
https://pushfa.com/api/webservices/send-via-subscriber-id
کاربرد
شناسه ثابت مخاطب (Subscriber ID) برخلاف توکن FCM در طول زمان ثابت میماند. پس از دریافت و ذخیره آن روی کاربرتان، از این API برای ارسال پایدار استفاده کنید.
شناسه ثابت مخاطب (Subscriber ID) را با window.Pushfa.getSubscriberId() یا از پنل (سرویسها ← مشترکین) دریافت کنید.
پارامترهای ورودی
| پارامتر | مقدار | اجباری |
|---|---|---|
| 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 IDPro | Collapse ID — رشته متنی حداکثر ۱۰۰ کاراکتر برای جایگزینی اعلان قبلی با اعلان جدید دارای همان شناسه. | خیر - فقط Pro |
| additional_dataAdditional DataPro | Additional Data (JSON) — شیء JSON دلخواه که همراه پیام ارسال میشود و در SDK/Service Worker قابل خواندن است. | خیر - فقط Pro |
| get_delivery_status | درخواست گزارش تحویل (مقدار 1/0 در ارسال تکی یا true/false در ارسال گروهی) | خیر |
| webhook_url | آدرس وبهوک بومرنگ — در صورت عدم تحویل، نتیجه به این آدرس ارسال میشود | خیر |
| get_click_status | درخواست گزارش کلیک (مقدار 1/0 در ارسال تکی یا true/false در ارسال گروهی) | خیر |
| send_time | زمان ارسال؛ current برای ارسال فوری و delay برای زمانبندیشده. اختیاری و پیشفرض current است. نام قدیمی sendTime فعلاً پشتیبانی میشود، اما نباید هر دو نام همزمان ارسال شوند. | خیر |
| time | تاریخ و ساعت ارسال را با قالب Y-m-d H:i وارد کنید. این فیلد فقط برای ارسال زمانبندیشده استفاده میشود. | اگر 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"
}'شناسه پایدار مخاطب و سازگاری با کلیدهای قدیمی
از subscriber_id برای یک مخاطب و subscriber_ids[] برای چند مخاطب استفاده کنید؛ این شناسهها با چرخش توکن تغییر نمیکنند و پایدارترند. کلیدهای fcm_token و fcm_tokens[] به دلیل پایداری کمتر منسوخ شدهاند، اما برای سازگاری همچنان پشتیبانی میشوند. ارسال همزمان subscriber_id و fcm_token یا subscriber_ids و fcm_tokens، حتی با مقدار خالی، خطای اعتبارسنجی 422 میدهد.