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
    "customContent": {"key_example": "value_example"} // Optional: Custom key-value pairs to include in the push payload
  }
}

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

گزارش لاگ کمپین

چطور Campaign ID را دریافت کنیم؟

بعد از ارسال پیام از طریق این API، متریکس (Metrix) یک Campaign ID برای این ارسال تولید می‌کند. این Campaign ID معمولاً:

  • در ریسپانس API برگشت داده می‌شود
  • یا در بخش گزارشات (Logs) در داشبورد نمایش داده می‌شود
  • یا از طریق Webhook قابل دریافت است (اگر فعال کرده باشید)

استفاده از Campaign ID در صفحه گزارش کمپین

وقتی Campaign ID را از API دریافت کردید، می‌توانید از آن برای مشاهده گزارش کمپین استفاده کنید.

برای مشاهده لاگ‌های مربوط به هر کمپین، کافی است وارد مسیر زیر شوید:

Workspace → Settings → Channel Integration

در این صفحه، بخشی برای وارد کردن Campaign ID وجود دارد. با وارد کردن شناسه کمپین در این فرم، می‌توانید موارد زیر را مشاهده کنید:

  • وضعیت اجرای کمپین
  • تعداد ارسال‌های موفق و ناموفق
  • لاگ کامل رویدادها
  • پیام‌های ارسال‌شده
  • زمان‌بندی و جزئیات اجرای کمپین

این بخش به شما کمک می‌کند تمام جزئیات مربوط به کمپین را با استفاده از Campaign ID ردیابی و تحلیل کنید.

Tracking EventsFAQs