Introduction
A config (or config file) defines each connector in the Connected Channel. While adding a new Connector or making changes to the existing ones, you must upload the config file to ensure the Connector is configured correctly.
Sample files
You can download these sample config files to get started:
File Type | Description |
---|---|
Boilerplate Code | Use this file to get started for building your Connector. |
Full Config File | This file contains input types, requests, and responses. |
Config Sections
A config file is divided into the following sections:
Section | Key | Details |
---|---|---|
Basic Info
|
basic_info |
It contains basic connector details such as name, description, and type. |
Input Variables
|
input_variables |
It displays the input fields when you are using the connector. It allows you to set the following fields:
|
Authentication
|
auth |
It is the Authentication mechanism for your app that includes no auth and basic auth. |
Request and Response | modules |
It constructs the API call that MoEngage makes to the app during campaign execution and provides an outline of the interpretation of the API responses by MoEngage. |
File Format
The following is the file format of the config file:
{
"basic_info": {
"name": "",
"description": "",
"type": "CHANNEL"
},
"input_variables": [{
"visibility_scope": "",
"key": "",
"event_export_key": "",
"name": "",
"required": "",
"type": "",
"encrypt": "",
"validations": [""]
}],
"auth": {
"auth_type": "",
"auth_info": "",
"alias": ""
},
"modules": [{
"name": "default",
"type": "REQUEST_RESPONSE",
"params": {
"request": {
"method": "",
"headers": {"": ""},
"url": "",
"url_params": {"": ""},
"body_type": "",
"body": ""
},
"response": [{
"body_type": "",
"datetime_format": "",
"evaluation_criteria": {},
"actions": []
}]
}
}]
}
Basic Info
In this section, you must define the name of your Connector and the use case it aims to solve.
Key | Required | Type | Description |
---|---|---|---|
name |
Yes | String | It is your Connector name. It is displayed when you create connections on the App marketplace. |
description |
Yes | String | It is a one-line description of the use case solved by your connector. For example, using this Connector, you can send text messages to your Telegram users via the Telegram Bot. |
type |
Yes | String | It is your Connected Apps App type. |
Input Variables
Input variables enable the rendering of input fields on the App marketplace. They facilitate the collection of required information necessary to successfully connect MoEngage to your app and effectively execute campaigns through it.
To define an Input Variable, you must add the following to your input_variables
section:
Key | Required | Type | Valid Values | Description |
---|---|---|---|---|
visibility_scope |
Yes | String |
|
It is the location of your Input Variable or can be either of the following:
|
key |
Yes | String |
|
It is used to access the value of the input variable in the subsequent steps. |
event_export_key |
Yes | String |
|
The key is sent while exporting your Events from MoEngage to other third-party apps, such as Data Warehouses. |
name |
Yes | String |
Only alphanumeric [0-9, a to z, A to Z], and_(Underscore),-(hyphen) |
It is the label for your input variable. |
required |
Yes | String |
|
If the condition is true, this input is marked as mandatory on the UI. |
type |
Yes | String |
|
It determines what to display on the UI based on the excepted values. |
encrypt |
Yes | Boolean |
|
If true, the value of this input variable is encrypted in our storage. Use this only for highly sensitive data collection, not for PII such as passwords and keys. |
validations |
No | Object |
Refer here for the validations. |
Use it when you want to restrict the values. You can add regex rules to add frontend validations. |
Visibility Scope
The Input Variables are collected in the following places:
- App Marketplace
-
Campaign Creation Form (Step 2)
App MarketPlace
Connections to your Channel App are added from the App marketplace, as shown below:
In the App marketplace, you must collect fields that serve as authentication requirements or are common to all campaigns. These fields must be independent of campaign information.
For example, collecting the Telegram Bot ID in the App marketplace is recommended. This allows you to execute multiple campaigns using the same Telegram Bot. On the other hand, collecting Telegram Chat IDs in the App marketplace is not recommended, as they are campaign-dependent and must be changed for each end-user.
info |
Information MoEngage displays the Connection name for each Connector in the App marketplace by default. This provides a visual identifier to distinguish the Connections. |
Campaign Creation Form (Step 2)
Connections to your Channel app are added from the campaign creation, as shown below:
Supported Input Types
info |
Information All input types are available in the App marketplace and the campaign creation form (Step 2). |
MoEngage currently supports the following input types:
Text
This input type allows users to enter any basic text or string value. It is displayed on the UI as a simple single-line text box, making it useful for soliciting short, free-text input, such as usernames or email addresses.
To add a Text, follow the structure:
{
"visibility_scope": "{{campaign or app_marketplace}}",
"key": "{{key used in code}}",
"event_export_key": "{{key used for events}}",
"name": "display label",
"required": {{true or false}},
"type": "text",
"validations": [{{array of validation rules if any}}]
}
Number
This input type is for numbers. It appears as a text box but only accepts numerical entries. Use it when collecting numeric values, such as age, ID, or quantity.
To add a Number, follow the structure:
{
"visibility_scope": "<campaign or app_marketplace>",
"key": "<key used in code>",
"event_export_key": "<key used for events>",
"name": "<display label>",
"required": <true or false>,
"type": "number",
"validations": [<array of validation rules if any>]
}
info |
Information You can use validations to restrict the lower and upper bounds of the numeric input if required. |
Boolean
This input type appears as a radio button and allows users to choose between two mandatory possibilities: True or False. It is used when you ask users to enable/disable a feature, agree/disagree, or make any binary choice.
To add a Boolean, follow the structure:
{
"visibility_scope": "<campaign or app_marketplace>",
"key": "<key used in code>",
"event_export_key": "<key used for events>",
"name": "<display label>",
"required": <true or false>,
"type": "bool"
}
DateTime
This input type is for date and time. It appears as a DateTime picker, allowing users to select a specific date and time. Use it when collecting data about a specific date or time, such as scheduling posts or reminders.
To add a DateTime, follow the structure:
{
"visibility_scope": "<campaign or app_marketplace>",
"key": "<key used in code>",
"event_export_key": "<key used for events>",
"name": "<display label>",
"required": <true or false>,
"type": "datetime"
}
Password
This input type is for password entry. It appears as a text box but masks user input for privacy. It must be used when requesting sensitive information from users, such as login addresses.
To add a Password, follow the structure:
{
"visibility_scope": "<campaign or app_marketplace>",
"key": "<key used in code>",
"event_export_key": "<key used for events>",
"name": "<display label>",
"required": <true or false>,
"type": "password",
"validations": [<array of validation rules if any>]
}
Drop-down List (Single and Multi-Select)
This input type allows users to choose multiple options in multi-select mode. It is recommended when you have a predetermined set of options and prefer to restrict input without allowing free-text entry.
To add a Drop-down List, follow the structure:
{
"visibility_scope": "<campaign or app_marketplace>",
"key": "<key used in code>",
"event_export_key": "<key used for events>",
"name": "<display label>",
"required": <true or false>,
"type": "dropdown",
"allow_multiple": <true or false>, // If true, multiple options can be selected
"options": [
{
"label": "Option 1", // This value will be shown on the UI
"key": "key_1" // This will be the selected value passed
},
{
"label": "Option 2",
"key": "key_2"
},
{
"label": "Option 3",
"key": "key_3"
}
]
}
Hash Maps
This input type is used for key-value pair inputs. It appears as two interconnected input boxes for key and value. Use this when you require key-value data, such as settings or configurations.
To add a Hasmap, follow the structure:
{
"visibility_scope": "{{campaign or app_marketplace}}",
"key": "{{key used in code}}",
"event_export_key": "{{key used for events}}",
"name": "display label",
"required": {{true or false}},
"type": "key_value"
}
Input Validations
When defining input types that support validation, such as Text and Password, it is necessary to establish predetermined rules for validating the values entered by the user on the UI. You can add validations with the following key inside your input variables:
"validations": [
{
"text": "Rule description",
"regex": "<regex expression>"
}
]
Here is an example of a Full Name field which has three individual rules:
"validations": [
{
"text": "Start the name with an alphabet",
"regex": "^[A-Za-z]"
},
{
"text": "Use only numbers, spaces, \"_\" or \"-\" with alphabets",
"regex": "^[a-zA-Z0-9-_ ]*$"
},
{
"text": "Use 3-25 characters",
"regex": "^[a-zA-Z0-9 -_]{3,25}$"
}
]
Each of these rules is shown to the user on the UI to guide them toward valid input:
Reference Input Variables
After collecting values for your Input Variables from the user, you can use them in the following sections:
- Authentication
- Request and Response
You can use the JINJA code to reference an input variable. This referencing mechanism is similar to personalization in MoEngage. For example, consider the following Input Variables:
- From the App marketplace:
Username: String - From the Campaign Creation Form (Step 2):
Mobile Number: String
To reference these variables, use the following JINJA code:
{{AppMarketplaceForm["username"]}}
{{CampaignCreationForm["mobile_number"]}}
These Input Variables capture the user's input, which can be used during authentication or included as part of the API request payload.
Authentication
This section allows you to define the authentication required for your App. MoEngage uses this setup to send requests to your app, and the Connected Channels support the following out-of-the-box authentication types:
- No Auth
- Basic Auth
- API Key Auth
Key | Required | Type | Description |
---|---|---|---|
auth_type |
Yes | String |
It represents the type of authentication you want to use for the Connector. The valid options are
|
auth_info |
Yes | Object | It represents the authentication details, which depend on the type of authentication you selected. |
alias |
Yes | String | NIL |
No Auth
You can choose No Auth when your App does not need authentication or you have a custom implementation of standard authentication methods. If you select No Auth, MoEngage does not execute any pre-authentication operations on your requests.
When using "No Auth," choose No Auth as the app type. If necessary, you can include custom URL parameters or headers for your API.
"auth": {
"auth_type": "no_auth",
"auth_info": {},
"alias": "valid_alias"
}
info |
Information You must pass an empty object in the |
Basic Auth
If your App supports Basic Auth, you can collect the username and password on the App marketplace and pass them as part of your Basic Auth Token for each request.
To add Basic Auth, follow the structure:
"auth": {
"auth_type": "basic_auth",
"auth_info": {
"username": "{{AppMarketplaceForm[\"account_id\"]}}",
"password": "{{AppMarketplaceForm[\"account_key\"]}}"
},
"alias": "valid_alias"
}
In the example above, we refer to the values entered by the user on the App Marketplace form. MoEngage generates a Base64-encoded Basic Auth token and includes it in each request's Authorization header.
For example, if the Account ID is ABC123 and the Account Key is 123XYZ, you must pass the following header in each of our requests:
Authorization: Basic QUJDMTIzOjEyM1hZWg==
Request and Response
In this section, you must set up the API requests that MoEngage initiates for each campaign sent. After a request is made from MoEngage, you can set up how the Campaign Stats are calculated based on your API requests' responses.
warning |
Warning MoEngage does not support stats that might be asynchronous or driven by callbacks today. |
Campaign Requests
MoEngage attempts to send API requests to your App each time a campaign is sent out.
For example, if a campaign is directed to 50 users, MoEngage makes 50 API requests for that campaign.
warning |
Warning
|
To configure a response, add this to your config:
"modules": [
{
"name": "default",
"type": "REQUEST_RESPONSE",
"params": {
"request": {},
"response": []
}
}
]
Request Format
The request format informs MoEngage about the request's payload.
"request": {
"method": "<HTTP method: GET, POST etc>",
"headers": {
"<header_name>": "<header_value>"
},
"url": "<API endpoint url>",
"url_params": {
"<url_param_name>": "<url_param_value>"
},
"body_type": "<body type: JSON, form data etc>",
"body": "<body content>"
}
Key | Required | Type | Valid Options | Description |
---|---|---|---|---|
method |
Yes | String |
|
The method defines the request's API.
|
headers |
Yes | Object |
|
You can include key-value pairs of custom headers you want to pass in your API requests. Input variable references are supported here. If you do not have any custom headers to add, you can make this an empty object. |
url |
Yes | String |
|
It is used to specify the complete endpoint of your API request. Input variable references are supported here. |
url_params |
Yes | Object |
|
You can include key-value pairs of custom headers that you want to pass in your API requests. Input variables' references are supported here. If you do not have any custom URL parameters to add, you can make this an empty object. |
body_type |
Yes | String |
|
The payload format. |
body |
Yes | String |
NIL |
It is the payload of your API request. Input variables' references are supported here. |
Response Handling
After making an API request, you can inform MoEngage how to interpret the response. You can also add multiple responses to your request by covering all your responses, such as successes and failures.
A response consists of two parts:
- Response conditions: Based on the response provided by your API, you can add conditions to its Status Code, Header Values, or even the body payload. When these conditions are fulfilled, you can perform actions in MoEngage.
- Response actions: Actions are operations performed by MoEngage.
Use Cases
There are several use cases for response handling. The following are the types of tracking used for various use cases:
- Stats tracking: This displays accurate Success and Failed stats for your campaigns.
- Event tracking: These are trigger events that occur when certain conditions are fulfilled. They can help you to create other journeys for your users.
Add a Response
To add a response, follow the structure:
"response": [
{
"body_type": "<body type: JSON, STRING etc>",
"datetime_format": "<datetime format if required>",
"evaluation_criteria": {...} , // Specify your evaluation criteria for success or failure
"actions": [...] // Actions to be taken based on evaluation
}
]
Key | Required | Type | Valid Options | Description |
---|---|---|---|---|
body_type |
Yes | String |
|
It specifies the format of the response. Currently, MoEngage supports only JSON responses.
|
datetime_format |
Yes | String |
Valid datetime formats. |
If your response returns at least one datetime value, it is recommended that you provide the format of the expected datetime value so that MoEngage can accurately parse it. |
evaluation_criteria |
Yes | Object |
Refer to the following sections for the evaluation criteria. |
The evaluation criteria for the response are as follows:
|
actions |
Yes | Object |
Refer to the following sections for the actions. |
The actions must be performed when the response conditions are fulfilled. The list of supported actions is included below. |
Response Conditions
Here, you can include multiple conditions for each response, combining both AND and OR operators. If you have prior experience with MoEngage Segmentation, you can leverage that.
The following is to add a new condition:
"evaluation_criteria": {
"filters": [
{
"name": "response_code" or "response_body" or "response_headers",
"data_type": "<data_type>",
"operator": "<operator>",
"value": "<value>",
"negate": true/false,
"case_sensitive": true/false
}
],
"filter_operator": "<operator>"
}
Each condition is called a Filter in MoEngage. The following conditions function similarly to our segmentation filters:
Key | Required | Type | Valid Options | Description |
---|---|---|---|---|
filter_operator |
Yes | String |
|
This defines how filters must be applied. It is the logical relation between filters. |
filters |
Yes | Array | An array of Filter objects |
The specific conditions are defined using an array of filter objects. |
name |
Yes | String |
|
It defines which part of the response is to be checked. For example, values can be "response_code," "response_body," and so on. |
data_type |
Yes | String |
For Status codes:
For Headers:
For Body:
Refer here for a complete list of accepted values. |
This defines the expected data type of the value. |
operator |
Yes | String |
Refer here for a complete list of accepted values. |
It represents the operator to be used for comparison |
value |
Required for all operators except 'exists' |
|
NIL |
It is a value to be used for comparison. |
value1 |
Required for operator 'between' | String Number Boolean |
NIL |
It is the second value to be used for comparison. In the case of between, it works as follows: value <= attribute_value <= value1 |
negate |
Optional | Boolean |
|
This field is used to identify which current query is negative. The default value is false. For example, email != 'test.moe.com' In this example, the operator is 'is,' negate=true, and value='test@moe.com' |
case_sensitive |
Optional | Boolean |
|
This field indicates whether the string is case-sensitive. To add the case-sensitive condition, choose case_sensitive=true. Then, the default value is false. |
Below is an example of evaluation criteria to check if the API's Response Status Code is 200 and if it returns {"ok": true}
in the payload:
"evaluation_criteria": {
"filters": [
{
"name": "response_code",
"data_type": "double",
"operator": "is",
"value": 200,
"negate": false,
"case_sensitive": false
},
{
"name": "response_body",
"data_type": "object",
"filter_operator": "and",
"filters": [
{
"name": "ok",
"data_type": "bool",
"operator": "is",
"value": true,
"negate": false,
"case_sensitive": false
}
]
}
],
"filter_operator": "and"
}
You are allowed to create conditions customized for your App. The accuracy of these conditions directly influences MoEngage's ability to trigger events and display statistics effectively.
Response Actions
Here, you can have MoEngage perform actions based on the above-mentioned conditions. Currently, MoEngage supports the Create Event actions.
Create Event
These tracks use cases like Messages sent, Users synced, and so on. With this action, you can use MoEngage to trigger an event. Below is the structure to add an Event for your response:
"actions": [
{
"type": "CREATE_EVENT",
"config": {
"event": {
"name": "Connected App Campaign Failed"
},
"attributes": [
{
"key": "Attribute Name",
"value": "Attribute Value"
}
]
}
}
]
To ensure accurate calculation of your Campaign Stats, specifically for Sent and Failed events, the following two events must be added as part of your Actions:
- Connected App Campaign Sent
- Connected App Campaign Failed
Key | Required | Type | Valid Options | Description |
---|---|---|---|---|
type |
Yes | String |
CREATE_EVENT |
It represents the type of action you want to perform. |
config |
Yes | Object |
NIL |
It represents the required details of the action that you must perform. |
event |
Yes | Object |
NIL |
It is the event that triggered this action. |
event.name |
Yes | String |
NIL |
It is the name of your event. |
event.attributes |
Yes | Object-Array |
NIL |
An array of different key-value pairs of attributes as part of your event. |
event.attributes[].key |
Yes | String |
NIL |
It is the name of the event attribute. This can be a Display Name of the attribute. |
event.attributes[].value |
Yes | String |
NIL |
It is the value of the event attribute. Input variables' references are supported here. |
MoEngage also includes the following default standard event attributes to facilitate better tracking for users.
Attribute Name | Description |
---|---|
App name |
It is the name of your Connected App. |
Integration type |
It is the name of your Channel Connector. |
Campaign name | It represents the name of the campaign associated with this event. |
Campaign Id | It is the ID of the campaign associated with this event. |
Parent Campaign ID |
It is tracked when a periodic campaign is run and represents the campaign ID of the parent periodic campaign. Child instances of this parent campaign are re-run on a recurring basis. |
Version Id | It represents the Version Name to which the journey campaign belongs and is tracked during campaign execution. |
Version Name | It represents the name of your campaign journey. |
Campaign Channel | The Campaign Channel is always Connected Apps. |
Readable Campaign Id | It provides a readable Campaign ID for easy identification. |
Campaign Type | It represents the type of campaign to which the message belongs. |
Delivery Type | It represents the Delivery type (one-time, periodic, and so on of the campaign. |
Campaign Tags | It represents the tags added to the campaign and is tracked in all campaign-related events. |
Parent Flow Id |
It represents the flow ID of the parent journey campaign and is tracked during the campaign's execution. |
Parent Flow Name | It represents the flow name of the parent journey campaign and is tracked when the journey campaign is run. |
Upload the Config File
After you are ready with your configuration file, refer here to upload it to your Connected App on the App marketplace.