Skip to Content
مستندات متریکس همواره در حال بهبود است! 🚀 آخرین به‌روزرسانی‌ها را از اینجا دنبال کنید.
مستندات فنیRest APIMessaging API

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)
    "ttl": 30 // Optional: Time-to-live, how long (in seconds) FCM stores the message if the device is offline (e.g. 3600 = 1 hour) set it null or ignore it if you want to notification send whenever user got online
  }
}

۳. ایمیل (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."
    }
}'
Tracking EventsFAQs