1. Developer Guide
  2. API
  3. Content
  4. Push templates
Create Push Template API

The Create Push Template  API can be used to create a push template in MoEngage. This API helps you upload templates created outside the MoEngage ecosystem to MoEngage and use them for campaign creation. The Basic Notification and Stylized Basic template types are supported for this API. For more information, refer to Push Templates.

API Endpoint

API Endpoint
POST https://api-0X.moengage.com/v1.0/custom-templates/push

Each customer is hosted on a different data center; you can find your data center number (value of X) by checking the data center and API endpoint mapping page.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username:password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization":"Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

The username and password details can be obtained from the MoEngage Dashboard. We've revamped the settings UI in the Dashboard. If you're using the API for the first time, follow these steps for the revamped and old UIs:

Revamped UI

  1. Navigate to Settings -> Account -> APIs.
  2. Click the Copy icon in the Campaign report/Business events/Custom templates tile in the API Keys section to copy the API Key.
  3. Use the App ID as the username and the Push API Key as the password to generate the authentication header.

Old UI

  1. Navigate to Settings -> APIs -> TRANSACTION PUSH/REPORT Settings.
  2. Click on the Click here to show APP Secret link to view the API SECRET.
  3. Use the APP ID as the username and the API SECRET as the password to generate the authentication header.

Request Headers

Key Required Sample Values Description

Content-Type

Required

{"Content-Type": "application/json"}

Set the Content-Type header to application/json.

Authorization

Required

{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}

This authentication parameter, used for access control, must be passed along with the request. To generate the authentication header, refer to Authentication.

 

Request Body

Key Required Values Description
ANDROID Optional JSON Object

This field contains the definition of the template to be created for the Android platform. 

Structure:

"ANDROID": {
     "basic_details": {

        <Template's basic details>

     },

     "buttons": [List of buttons],

     "advanced": {

        <Template's advanced options>

     },

     "template_backup": {

        <Template's backup options>

     }

}

For more information, refer to Template Details.
IOS Optional JSON Object

This field contains the definition of the template to be created for the iOS platform. 

Structure:

"IOS": {
     "basic_details": {

        <Template's basic details>

     },

     "buttons": [List of buttons],

     "advanced": {

        <Template's advanced options>

     },

     "template_backup": {

        <Template's backup options>

     }

}

For more information, refer to Template Details.
meta_info Required JSON Object

This field contains information about the template being created, such as the name, version, and id of the template, the template's platform, style, and the creator's details. For more information, refer to Meta Info Object.

Note: The ANDROID and the IOS keys differ in the payload structure, which is explained below.

Template Details

The ANDROID and IOS keys contain the following JSON objects that define the template for the respective platforms. The following image shows the request fields that are responsible for rendering the title, message, summary, background color, and image in the push notification.

PushNotification_FieldsShown.png

ANDROID IOS

The following details are available in the ANDROID payload:

Basic Details

The basic_details JSON object contains the following information:

Key Required Values Description
title Required String This field contains the title of the message.
message Required String This field contains the message content.
summary Optional String This field contains a brief description of the message content.
app_name_color_code Optional String

This field contains the specification for the color of the app name in the push notification. This is available only for the Android platform. This option is not available for the Basic Notification template. Example:  "app_name_color_code": "#5450ea"

Note: Only hexadecimal values are supported.
notification_control_color Optional String

This field contains the specification for the notification control color. Allowed Values: Light, Dark 

This is available only for the Android platform. This option is not available for the Basic Notification template.
background_color_code
 		Optional String

This field contains the specification for the background color of the message in the push notification. This is available only for the Android platform. This option is not available for the Basic Notification template. Example: "background_color_code": "#f5e6cd"

Note: Only hexadecimal values are supported.
apply_background_color
 		Optional Boolean This field contains information about whether the background color should be applied to the fields with a text editor (Title, Message, and Summary). It is recommended to enable this option for lighter font colors. This option is not available for the Basic Notification template.
image_url
 		Optional String This field contains the URL of the image to be added to the notification. Allowed file formats: jpg, jpeg, png, gif
default_click_action
 		Mandatory String

This field describes the default action that should happen when a user clicks on the push notification. The allowed values are:

  1. NAVIGATE_TO_A_SCREEN
  2. DEEPLINKING
  3. RICH_LANDING
default_click_action_value
 		Mandatory String This field contains information about which screen or URL or the rich landing URL information the user should navigate to based on the click action defined above. For example, if default_click_action is NAVIGATE_TO_A_SCREEN, the screen details in the app that the user should land on when they click on the push notification should be specified in default_click_action_value.
key_value_pairs
 		Optional List of keys and values

This field contains the list of key-value pairs. For example:

[{"key" : "user","value": "john"}]

For more information, refer to Basic Details in Push Templates.

Buttons

The buttons object contains the list of buttons in the notification and is optional. Each button is a JSON Object and contains the following information:

Key Required Values Description

btn_name

 Required String This field contains the name of the button.
click_action_type Required String

This field contains the click action associated with the button. The allowed values are:

  1. NAVIGATE_TO_A_SCREEN
  2. DEEPLINKING
  3. RICH_LANDING
  4. CALL
  5. SHARE
  6. COPY
  7. SET_USER_ATTRIBUTE
  8. TRACK_EVENT
  9. CUSTOM_ACTION
  10. SNOOZE
  11. REMIND_LATER

For more information, refer to Click Actions Supported for Android.
click_action_name Optional String This field is used when the click action is chosen as SET_USER_ATTRIBUTE or TRACK_EVENT. In both these cases, a KV pair input is required, and the key is set in this field while the value is set for the same in click_action_value.
click_action_value Required String This field contains information about which screen or URL the user should navigate to or the action that should happen for the click action type defined for the button. For example, if click_action_type is NAVIGATE_TO_A_SCREEN, the screen details in the app that the user should land on when they click the button should be specified in click_action_value.
key_value_pairs Optional List of keys and values

This field contains the list of key-value pairs. For example:

[{"key" : "user","value": "john"}]

For more information, refer to Basic Details in Push Templates.

Advanced Options

The advanced JSON object contains the following information:

Key Required Values Description
coupon_code Optional String This field contains the coupon code.
icon_type_in_notification Optional String This field contains the type of icon to be used in the notification. Allowed Values: appicon, upload, url.
large_icon_url Optional String This field contains the URL that contains the large icon to be added to the notification.
auto_dismiss_notification Optional Boolean This field contains information about whether notification should be auto-dismissed from the user's notification tray.
dismissal_time_multiplier Optional String This field contains the time duration in days, hours, or minutes, and this will be multiplied with the dismissal_time_value to calculate the duration, after which the notification will automatically be removed from the user's notification tray after the push notification is delivered to the user. Allowed Values: DAYS, HOURS, MINUTES. For example, if you want the notification to be dismissed in two hours, specify the dismissal_time_multiplier as HOURS and the dismissal_time_value as 2.
dismissal_time_value Optional Integer This field contains the value that will be multiplied with the dismissal_time_multiplier to arrive at the time duration, after which the notification will automatically be removed from the user's notification tray after the push notification is delivered to the user. For example, if you want the notification to be dismissed in thirty minutes, specify the dismissal_time_multiplier as MINUTES and the dismissal_time_value as 30.
make_notification_sticky Optional Boolean This field contains information about whether the notification should be made sticky in the user's notification tray. If this value is true, the notifications cannot be dismissed by swiping or clicking. The user would have to click on the dismiss button provided in the notification to dismiss it. This option is not available for the Basic Notification template.
dismiss_button_text Optional String This field contains the name of the dismiss button when sticky notifications are turned on. This option is not available for the Basic Notification template.

For more information, refer to Basic Details in Push Templates.

Template Backup

Some of the options available in the higher SDK versions are not supported for devices that have lower SDK versions (versions lesser than Android SDK version 10.3.00). In such cases, a backup notification is sent, and this information is configured in the Template Backup section.

Note: This option does not apply to the Basic notification template and is applicable only to the Stylized basic template. The stylized elements would not be applied to the notification, and the notification will be treated as plain text when sent.

The template_backup JSON object contains the following information:

Key Required Values Description
title Required String This field contains the title of the message.
message Required String This field contains the message content.
summary Optional String This field contains a brief description of the message content.
image_url
 		Optional String This field contains the URL of the image to be added to the notification. Allowed file formats: jpg, jpeg, png, gif
default_click_action
 		Mandatory String

This field describes the default action that should happen when a user clicks on the push notification. The allowed values are:

  1. NAVIGATE_TO_A_SCREEN
  2. DEEPLINKING
  3. RICH_LANDING
default_click_action_value
 		Mandatory String This field contains information about which screen or URL or the rich landing URL information the user should navigate to based on the click action defined above. For example, if default_click_action is NAVIGATE_TO_A_SCREEN, the screen details in the app that the user should land on should be specified in default_click_action_value.
key_value_pairs
 		Optional List of keys and values

This field contains the list of key-value pairs. For example:

[{"key" : "user","value": "john"}]

For more information, refer to Basic Details in Push Templates.

Meta Info

The meta_info JSON object contains the following information:

Key Required Values Description
platform Required List of Strings This field contains the list of platforms where the template can be used. Allowed values: ANDROID, IOS
template_style Required String This field contains the style of the template. Allowed values: BASIC, STYLIZED
template_id Required String This field contains the ID for the template and is unique. This ID should be generated by you and will be used for updating or retrieving the template using the template APIs.
template_name Required String This field contains the name of the template. This value should be generated by you and would be used for identifying the template.
template_version Required String This field contains the version of the template. This value should be generated by you and would be used for tracking the template's version.
created_by Required String This field contains details about who created the template. This value should be generated by you. For example, you can pass the email id of the user creating the template here.

Response

Key Data Type Description
external_template_id String This field contains the unique template id corresponding to a successful template creation request and needs to be stored by you. This template id would be used for searching a specific template and updating it.
error JSON Object

This field contains the reason for the request's failure.

Structure:

 "error": {

    "code": "<error_code>", 

    "message": "<error_message>" ,

     "details": [],

    "request_id": "<unique identifier for the request>

}

The error object contains the following fields:

  • code - This field contains the error code that provides a brief explanation of the error and is a String. For example, 400 - Bad Request, 401- Authentication required, and so on. This field is present in the response only in the case of errors.
  • message - This field describes why the request has failed and is a String. For example, in the case of a duplicate request (400- Bad Request), the following message will be present: 'Duplicate - template_id and template_version'.
  • details - This is a List of the error details objects. Each object contains the following information:

           { 

             "code": "<Descriptive Error Code>",

             "target": "<Denotes the field causing the issue or a brief description of the error message in some cases >",

              "message": "<Descriptive Error Message>"

            }

  • request_id -  This field contains the unique id pertaining to the request.

For example, in the case of a 400 request where the request is trying to create a template that is already present, the following error object is returned.

{
"error": {
"code": "400 Bad Request",
"message": "Duplicate - template_id and template_version",
"details": [
{
"code": "InvalidValue",
"target": "Duplicate - template_id and template_version",
"message": "template_id:<template_id> template_version:<template_version> is already present."
}
],
"request_id": "cLCcgLQj"
}

Response Codes

Status Code Request State Description

200

Success

This response is returned when the request is processed successfully. 

400

Bad Request

This response is returned when the required parameters are missing from the request or when the provided parameters are invalid, or when a template already exists with the same version, name, or id.

401

Authorization Failure

This response is returned when the authorization parameters are missing in the HTTP Auth Header.

415

Unsupported File Type

This response is returned when the header Content-Type is not provided/is not supported.

429

Rate Limit Breach

This response is returned when the number of requests per minute has exceeded the rate limit or the number of templates has exceeded the allowed quota per channel.

5xx

Internal Server Error

This response is returned when the system runs into an unexpected error.

Rate Limit

Sample cURL Requests

Sample Requests with the Stylized Template payload

Android and iOS Payloads Only Android Payload Only iOS Payload 
curl --location 'https://api-0X.moengage.com/v1.0/custom-templates/push' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U==' \
--data '{
    "ANDROID": {
        "basic_details": {
            "app_name_color_code": "#ffffff",
            "notification_control_color": "Light",
            "background_color_code": "#ffffff",
            "title": "TITLE_OF_ANDROID_TEMPLATE",
            "message": "MESSAGE_OF_ANDROID_TEMPLATE",
            "summary": "SUMMARY",
            "image_url": "https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg?w=1260&h=750&auto=compress&cs=tinysrgb",
            "default_click_action": "DEEPLINKING",
            "default_click_action_value": "https://www.google.com",
            "key_value_pairs": [{
                "key": "KEY",
                "value": " VALUE"
            }]
        },
        "buttons": [
            {
                "btn_name": "NAME_OF_THE_BUTTON",
                "click_action_type": "DEEPLINKING",
                "click_action_name": "Bhuvan",
                "click_action_value": "https://www.google.com"
            }
        ],
        "advanced": {
            "coupon_code": "COUPON_CODE",
            "icon_type_in_notification": "appicon",
            "auto_dismiss_notification": true,
            "dismissal_time_multiplier": "minutes",
            "dismissal_time_value": 1,
            "make_notification_sticky": true,
            "dismiss_button_text": "DISMISS_BUTTON_TEXT_HERE"
        },
        "template_backup": {
            "title": "TITLE_OF_ANDROID_BACKUP_TEMPLATE",
            "message": "MESSAGE_OF_ANDROID_BACKUP_TEMPLATE",
            "summary": "SUMMARY",
            "image_url": "https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg?w=1260&h=750&auto=compress&cs=tinysrgb",
            "default_click_action": "DEEPLINKING",
            "default_click_action_value": "https://www.google.com",
            "key_value_pairs": [{
                "key": "KEY",
                "value": " VALUE"
            }]
        }
    },
    "IOS": {
        "basic_details": {
            "background_color_code": "#ffffff",
            "title": "TITLE_OF_IOS_TEMPLATE",
            "subtitle": "SUBTITLE_OF_IOS_TEMPLATE",
            "message": "MESSAGE_OF_IOS_TEMPLATE",
            "rich_media_value": "RICH_MEDIA_URL_HERE",
            "default_click_action": "DEEPLINKING",
            "default_click_action_value": "https://www.google.com",
            "allow_bg_refresh":true
        },
        "buttons": [
            {
                "button_category": "CATEGORY_OF_BUTTON"
            }
        ],
        "advanced": {
            "coupon_code": "COUPON_CODE",
            "sound_file": "SOUND_FILE",
            "enable_ios_badge": true
        },
        "template_backup": {
            "title": "TITLE_OF_IOS_TEMPLATE",
            "subtitle": "SUBTITLE_OF_IOS_TEMPLATE",
            "message": "MESSAGE_OF_IOS_TEMPLATE",
            "rich_media_value": "RICH_MEDIA_URL_HERE",
            "default_click_action": "DEEPLINKING",
            "default_click_action_value": "https://www.google.com",
            "allow_bg_refresh":true
        }
    },
    "meta_info": {
        "platform": [
            "ANDROID",
            "IOS"
        ],
        "template_style": "STYLIZED",
        "template_id": "1234567890",
        "template_name": "BT1",
        "template_version": "1",
        "created_by": "User1"
    }
}'

Sample Requests with the Basic Template payload

Both Android and iOS Payloads Only Android Payload Only iOS Payload 
curl --location 'https://api-0X.moengage.com/v1.0/custom-templates/push' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U==' \
--data '{
    "ANDROID": {
        "basic_details": {
            "title": "TITLE_OF_ANDROID_TEMPLATE",
            "message": "MESSAGE_OF_ANDROID_TEMPLATE",
            "summary": "SUMMARY",
            "image_url": "https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg?w=1260&h=750&auto=compress&cs=tinysrgb",
            "default_click_action": "DEEPLINKING",
            "default_click_action_value": "https://www.google.com",
            "key_value_pairs": [{
                "key": "KEY",
                "value": " VALUE"
            }]
        },
        "buttons": [
            {
                "btn_name": "NAME_OF_THE_BUTTON",
                "click_action_type": "DEEPLINKING",
                "click_action_name": "Bhuvan",
                "click_action_value": "https://www.google.com"
            }
        ],
        "advanced": {
            "coupon_code": "COUPON_CODE",
            "icon_type_in_notification": "appicon",
            "auto_dismiss_notification": true,
            "dismissal_time_multiplier": "minutes",
            "dismissal_time_value": 1
        }
    },
    "IOS": {
        "basic_details": {
            "title": "TITLE_OF_IOS_TEMPLATE",
            "subtitle": "SUBTITLE_OF_IOS_TEMPLATE",
            "message": "MESSAGE_OF_IOS_TEMPLATE",
            "rich_media_value": "RICH_MEDIA_URL_HERE",
            "default_click_action": "DEEPLINKING",
            "default_click_action_value": "https://www.google.com",
            "allow_bg_refresh":true
        },
        "buttons": [
            {
                "button_category": "CATEGORY_OF_BUTTON"
            }
        ],
        "advanced": {
            "coupon_code": "COUPON_CODE",
            "sound_file": "SOUND_FILE",
            "enable_ios_badge": true
        }
    },
    "meta_info": {
        "platform": [
            "ANDROID",
            "IOS"
        ],
        "template_style": "BASIC",
        "template_id": "12345",
        "template_name": "Basic template - Android and IOS",
        "template_version": "1",
        "created_by": "User1"
    }
}'

Sample Response

200 400 401 415 429 5xx 
Sample Response for a successful request
{
  "external_template_id": "d05a44f0-a7cf-471a-bcb6-63054800a367"
}

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.

FAQs

  • Can I create a template that is supported only on iOS?
    Yes, you can send only the iOS payload if you want to create a template for iOS.
  • What are the different types of image, video, and audio files supported by MoEngage?
    • Audio and video file formats - all types of video and audio file formats supported by standard FCM/APNS platforms
    • Images- the following formats are supported
      • “image/png”,
      • “image/jpeg”,
      • “image/jpg”,
      • “image/gif”
  • Can I create multiple templates with the same name?
    Yes, you can create multiple templates with the same name, provided they have different versions.

Previous

Next

Was this article helpful?
1 out of 1 found this helpful

How can we improve this article?