Create a Channel Connector Config File

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:

  • Data type: This contains Integer (Int), String, Boolean, JSON, Dropdown, and so on.
  • Visibility: This field appears during the campaign creation or integration in the App marketplace. 

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:

File Format
{
"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
  • app_marketplace
  • campaign

It is the location of your Input Variable or can be either of the following:

  • App marketplace
  • Campaign Creation (Step 2)
key Yes String
  • Only lowercase alphabets
  • No blank spaces
  • _ (Underscore), -(hyphen)

It is used to access the value of the input variable in the subsequent steps.

event_export_key Yes String
  • Only lowercase alphabets
  • No blank spaces
  • _ (Underscore), - (hyphen)

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
  • true
  • false

If the condition is true, this input is marked as mandatory on the UI.

type Yes String
  • text
  • number
  • bool
  • datetime
  • password
  • dropdown
  • radio
  • json
  • code
  • key_value

It determines what to display on the UI based on the excepted values.

encrypt Yes Boolean
  • true
  • false

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:

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:

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:

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:

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:

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:

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.
Hashmap.png

To add a Hasmap, follow the structure:

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:

Structure
"validations": [
    {
        "text": "Rule description",
        "regex": "<regex expression>"
    }
]

Here is an example of a Full Name field which has three individual rules:

Structure
"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:

JINJA
{{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

  • no_auth
  • basic_auth
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.

Structure
"auth": {
    "auth_type": "no_auth",
    "auth_info": {},
    "alias": "valid_alias"
}
info

Information

You must pass an empty object in the auth_info key, as no additional information is required for this app type.

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:

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
The following are not supported:

  • Frequency Capping or Do-Not-Disturb (DND)
  • Throttling 
  • Bulk API requests 
  • Multiple API requests (Chained API requests) 

To configure a response, add this to your config:

Structure
"modules": [
  {
      "name": "default",
      "type": "REQUEST_RESPONSE",
      "params": {
          "request": {},
          "response": []
      }
  }
]

Request Format

The request format informs MoEngage about the request's payload. 

Structure
"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
  • GET
  • POST
  • PUT
  • PATCH
  • DELETE

The method defines the request's API.

 

 

 

headers Yes Object

{ "header_name": "header_value" } 

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
  • Valid URLs
  • If JINJA is used, it should be correctly formed

It is used to specify the complete endpoint of your API request.

Input variable references are supported here.

url_params Yes Object

{ "url_param": "param_value" } 

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

JSON

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:

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

JSON

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:

  • If the conditions are satisfied, MoEngage performs the specified actions.
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:

Structure
"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
  • and
  • or

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
  • response_code
  • response_headers
  • response_body

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:

  • double

For Headers:

  • string

For Body:

  • double
  • string
  • bool
  • datetime

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'
  • String
  • Number
  • Boolean

 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
  • true
  • false

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
  • true
  • false

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:

Structure
"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:

Structure
"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.

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

How can we improve this article?