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
شناسهای است که قبلاً برای معرفی کاربر به صورت یکتا به متریکس ارسال کردهاید (رجوع کنید به ردیابی کاربران ). متریکس از این شناسه برای پیدا کردن کاربر و ارسال پیام به او از طریق کانالهای مرتبط استفاده میکند.
- هدف: یک آرایه (لیست) از
-
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."
}
}'