Messaging (پیامرسانی)
با استفاده از Messaging API متریکس، میتوانید اعلانها و پیامهای هدفمند را از طریق کانالهای مختلف به کاربران خود ارسال کنید. این کانالها شامل وبپوش، اپپوش، ایمیل، اس ام اس، و حتی وبهوک و پیامهای درونبرنامهای/درونسایتی میشوند.
فرمت کلی درخواست ارسال پیام
برای ارسال پیام به کاربران، باید یک درخواست POST به Endpoint مخصوص پیامرسانی ارسال کنید:
https://entry.metrix.ir/push
ساختار کلی درخواست:
درخواست شما باید شامل هدرها و بدنهای با فرمت JSON باشد. هدرها همانند سایر درخواستهای API متریکس هستند:
-
Header (هدرها):
X-Application-Id
:APP_ID
شماX-API-Key
:API_Key
شماContent-Type
:application/json
-
Body (بدنه درخواست - JSON):
{
"recipients": ["customUserId1", "customUserId2", "customUserId3"], // List of customUserIds of recipients
"channel": "SMS", // Communication channel (e.g., "SMS", "WEB_PUSH", "APP_PUSH", "EMAIL", "WEB_HOOK", "IN_APP", "ON_SITE")
"message": {
"title": "Important update", // Message title (optional, varies by channel)
"body": "A new version of the application is available now!" // Message body (mandatory, format varies by channel)
// ... other channel-specific message fields
}
}
توضیح فیلدهای اصلی بدنه درخواست:
-
recipients
:- هدف: یک آرایه (لیست) از
customUserId
کاربرانی که میخواهید پیام را برای آنها ارسال کنید. - نکته مهم:
customUserId
شناسهای است که قبلاً برای معرفی کاربر به صورت یکتا به متریکس ارسال کردهاید (برای مستندات REST رجوع کنید به ردیابی کاربران). متریکس از این شناسه برای پیدا کردن کاربر و ارسال پیام به او از طریق کانالهای مرتبط استفاده میکند.
- هدف: یک آرایه (لیست) از
-
channel
:- هدف: نوع کانال ارتباطی که قصد دارید پیام را از طریق آن ارسال کنید.
- مقادیر مجاز:
SMS
,WEB_PUSH
,APP_PUSH
,EMAIL
,WEB_HOOK
,IN_APP
,ON_SITE
.
-
message
:- هدف: حاوی محتویات اصلی پیام است که باید برای کاربران ارسال شود.
- فرمت: ساختار و فیلدهای داخلی این شیء (
message
) بسته بهchannel
انتخابی متفاوت خواهد بود. در ادامه، جزئیات هر کانال را توضیح میدهیم.
کانالهای پیامرسانی پشتیبانی شده
در ادامه، جزئیات مربوط به شیء message
برای هر کانال پیامرسانی و نمونه درخواست curl
مربوط به آن آورده شده است.
۱. وبپوش (WEB_PUSH)
برای ارسال اعلان به کاربران از طریق مرورگر وب.
{
"recipients": ["user_id_1", "user_id_2"],
"channel": "WEB_PUSH",
"message": {
"title": "New Notification",
"body": "You have a new message!",
"url": "https://example.com/notifications", // Optional: URL to open when notification is clicked
"icon": "https://example.com/icon.png", // Optional: URL of notification icon
"images": [{ "url": "https://example.com/image1.png" }], // Optional: List of image URLs
"buttons": [{ "label": "View", "link": "https://example.com/view" }] // Optional: List of action buttons
}
}
۲. اپپوش (APP_PUSH)
برای ارسال اعلان به کاربران از طریق اپلیکیشن موبایل.
{
"recipients": ["user_id_1", "user_id_2"],
"channel": "APP_PUSH",
"message": {
"title": "App Notification",
"body": "Check out the latest update!",
"url": "https://example.com/app-update", // Optional: URL to open (can be deep link or external URL)
"icon": "https://example.com/app-icon.png", // Optional: URL of notification icon
"images": [{ "url": "https://example.com/app-image.png" }], // Optional: List of image URLs
"buttons": [{ "label": "Open App", "link": "app://open" }] // Optional: List of action buttons (link can be deep link)
}
}
۳. ایمیل (EMAIL)
برای ارسال پیام از طریق ایمیل. بدنه پیام میتواند شامل HTML باشد.
{
"recipients": ["user_id_1", "user_id_2"],
"channel": "EMAIL",
"message": {
"title": "Important Update",
"body": "<html><body><p>A new version of your application is now available!</p></body></html>" // HTML content for email body
}
}
۴. اس ام اس (SMS)
برای ارسال پیام کوتاه (SMS).
{
"recipients": ["user_id_1", "user_id_2"],
"channel": "SMS",
"message": {
"body": "Please visit our website for new offers!" // SMS text body
}
}
۵. پیام درونبرنامهای (IN_APP)
برای نمایش پیامها مستقیماً در داخل اپلیکیشن موبایل کاربران.
{
"recipients": ["user_id_1", "user_id_2"],
"channel": "IN_APP",
"message": {
"title": "In-App Notification",
"body": "<html><body><p>You have a new message!</p></body></html>", // Supports HTML content
"duration": 5000, // Optional: Display duration in milliseconds (e.g., 5000 for 5 seconds)
"alignment": "CENTER" // Optional: Message alignment ("TOP", "CENTER", "BOTTOM")
}
}
۶. پیام درونسایتی (ON_SITE)
برای نمایش پیامها مستقیماً در داخل وبسایت کاربران.
{
"recipients": ["user_id_1", "user_id_2"],
"channel": "ON_SITE",
"message": {
"title": "On-Site Notification",
"body": "<html><body><p>You have a new message!</p></body></html>", // Supports HTML content
"duration": 3000, // Optional: Display duration in milliseconds
"alignment": "TOP" // Optional: Message alignment ("TOP", "CENTER", "BOTTOM")
}
}
نمونه دستور Curl برای ارسال پیام
مثال زیر نحوه ارسال یک پیام SMS را به چندین کاربر نشان میدهد:
curl --location 'https://entry.metrix.ir/push' \
--header 'content-type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'x-application-id: YOUR_APP_ID' \
--data-raw '{
"recipients": ["user_id_from_your_db_1", "user_id_from_your_db_2"],
"channel": "SMS",
"message": {
"body": "New special offers are waiting for you! Visit our app now."
}
}'