Skip to Content
AI Powered Docs! 🤖 These docs are translated with AI, so keep an eye out for minor quirks. We're always improving!
Technical DocumentationRest APIMessaging API

Messaging

Using the Metrix Messaging API, you can send targeted notifications and messages to your users through various channels. These channels include Web Push, App Push, Email, SMS, and even In-App/On-Site messages.

Overall Message Submission Format

To send a message to users, you must send a POST request to the messaging-specific endpoint:

https://entry.metrix.ir/push

Overall request structure:

Your request must include headers and a JSON-formatted body. The headers are the same as for other Metrix API requests:

  • Header:

    • X-Application-Id: Your APP_ID
    • X-API-Key: Your API_Key
    • Content-Type: application/json

  • Body (JSON format):

{
  "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
  }
}

Explanation of main body fields:

  • recipients:

    • Purpose: An array (list) of the customUserId for the users you want to send the message to.
    • Important Note: customUserId is the unique identifier you previously sent to Metrix to introduce a user (for REST docs, refer to Tracking Users ). Metrix uses this ID to find the user and send them the message through the relevant channels.

  • channel:

    • Purpose: The type of communication channel you intend to send the message through.
    • Allowed values: SMS, WEB_PUSH, APP_PUSH, EMAIL, WEB_HOOK, IN_APP, ON_SITE.

  • message:

    • Purpose: Contains the main content of the message to be sent to users.
    • Format: The structure and internal fields of this object (message) will vary depending on the chosen channel. The details for each channel are explained below.

Supported Messaging Channels

The following section provides details on the message object for each messaging channel, along with a corresponding curl request example.

1. Web Push (WEB_PUSH)

For sending notifications to users via their web browser.

{
  "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
  }
}

2. App Push (APP_PUSH)

For sending notifications to users via their mobile application.

{
  "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
  }
}

3. Email

For sending messages via email. The message body can contain 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
  }
}

4. SMS

For sending a short text message (SMS).

{
  "recipients": ["user_id_1", "user_id_2"],
  "channel": "SMS",
  "message": {
    "body": "Please visit our website for new offers!" // SMS text body
  }
}

5. In-App Message (IN_APP)

For displaying messages directly inside mobile applications for users.

{
  "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")
  }
}

6. On-Site Message (ON_SITE)

For displaying messages directly inside websites for users.

{
  "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")
  }
}

Sample Curl Command for Sending a Message

The following example shows how to send an SMS message to multiple users:

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."
    }
}'

npm run devHere is the full English translation:

Campaign Log Report

How to Retrieve the Campaign ID

After sending a message through this API, Metrix generates a Campaign ID for that delivery. This Campaign ID is usually obtained from:

  • The API response returned after sending the request
  • The Logs section in the dashboard
  • A Webhook event (if you have enabled it)

Using the Campaign ID in the Campaign Log Page

Once you receive the Campaign ID from the API, you can use it to view the campaign report.

To access the logs related to each campaign, go to:

Workspace → Settings → Channel Integration

On this page, there is a section where you can enter the Campaign ID. By entering the ID in this form, you will be able to view:

  • Campaign execution status
  • Number of successful and failed deliveries
  • Full event logs
  • Sent messages
  • Execution timing and detailed metadata

This section helps you track and analyze everything related to your campaign using the Campaign ID.

Tracking EventsFAQs