MoEngage natively integrates with the following SMS service providers - Gupshup, Kaleyra, ICS, Sinch, and Twilio. If you wish to integrate with any other SMS service provider, you can configure them as a Custom Connector (Service Provider) on the MoEngage Dashboard.
| info |
Information We've revamped our dashboard settings. This article describes the steps to be followed to configure the General Settings for the SMS channel in the revamped settings UI and the older UI. |
Configure Service Provider in Revamped UI
To configure a Service Provider on the MoEngage Dashboard:
- Navigate to Settings -> Channel -> SMS.
- Click on the Sender Configuration tab. You’ll find the list of integrated and custom service providers here.
- Click +Add Sender at the top right corner. In the Add Sender screen, you can either add a new custom service provider or a sender to a configured service provider.
- Click +Add custom service provider.
-
Fill in the following details in the General Details screen:
Field Description Mark as default
Turn on this toggle to mark the sender as the default sender for the service provider being configured. If marked as default, this sender would be used for sending all SMS campaigns from MoEngage unless you select a different sender while creating the campaign.
Service provider name This field identifies the service provider you are configuring on the MoEngage Dashboard and has to be unique. Type the name of the connector here.
Sender name
This field identifies the Sender. Type the name of the sender here.
Sender type
The Sender type can either be Promotional or Transactional. Choose the Sender type as Promotional when you would be using the Sender for sending information about your brand, promoting deals, or engaging with users. Choose the Sender type as Transactional when you would be using the Sender for sending alerts about transactions, OTPs, security information, or any information that can be classified as transactional in nature.
API URL
This field contains information about the URL that should be used to send an API request to the Sender. You can get this information from the API Documentation of the Sender. Type the API Endpoint of the sender here.
Method
Select one of the following HTTP Methods as per the specifications mentioned in the API Documentation of the Sender:
- GET
- POST
- DELETE
Note: Every service provider should have a distinct domain.
URL Parameters
Add the URL Parameters to be passed to the API as Key-Value pairs using this option. You can get this information from the API Documentation of the Sender. For example, if the API URL call uses the GET method, all the parameters, such as API Key, Authorization, and so on, are passed as URL Parameters.
Headers
Add the Request Headers to be passed to the API as Key-Value pairs using this option. You can get this information from the API Documentation of the Sender. For example, Authorization Headers and Content-Type Headers are added as KV pairs depending on the Sender's API specifications.
Body Type
Choose one of the following when the POST method is used to send information as part of the API request. This information can be found in the API Documentation of the Sender.
- Form
- JSON
- Raw
Form and JSON -Add Key-Value pairs for this request type.
Raw -Paste the request body when you choose Raw as the Body Type.
Enable authentication settings
If your connector request involves a basic non-changing access token, you can simply add those as a key-value pair in the header.
If your connector request involves an OAuth 2.0 authentication, perform the following steps:
- Turn on the Enable authentication settings toggle.
- From the Select authorization setting drop-down list, select an OAuth configuration.
info Information
You can see the OAuth settings configured in the MoEngage system at Settings > Advanced settings > Authorization configuration. For more information, refer to OAuth 2.0.
You must select a healthy OAuth setting, which is in "Active" status. If you select an OAuth setting in "Failed" status, you cannot create a Connector campaign.
- The Key field is populated as "Authorization" by default.
- In the Prefix field, enter a prefix. You can enter the name of a prefix added in the selected OAuth configuration. You can also override those prefixes and create your own prefix.
- In the Reattempt error codes field, enter error codes to initiate a reattempt in case of a failed response. For example, use the error code "400" for the expired error code to inform MoEngage to reattempt creating a Connector campaign.
Send test SMS
Click Send test SMS to verify your configuration. The Send Test SMS screen has the following fields:
- Mobile Number - Select the Country Code from the dropdown and type the mobile number in the textbox. The Test SMS will be sent to this number.
- Message - This field denotes the message body.
- After a successful test, Click Save to save the settings.
| info |
Note Set the following values as specified below when defining the request parameters, headers, or body:
|
Once the sender configuration is saved, you can enable Delivery Tracking for your messages.
Delivery Tracking
Delivery tracking allows you to track the delivery status of the SMS messages sent using custom connectors (service providers). Delivery tracking, when enabled, will show a metric - Delivered, which helps you understand whether messages have been delivered to the user and analyze delivery failures and errors. You can use this information to clean up your delivery list periodically (by removing users for previous deliveries that were unsuccessful). This will help you avoid sending SMS campaigns to users with repeated delivery failures, thus saving costs.
You can add the Delivery Tracking information once you save the connector (service provider) settings for the first time.
Steps to Enable Delivery Tracking
To enable delivery tracking:
- Click on the ellipsis icon by hovering on the newly added sender in the SMS Settings screen.
- Select Edit. The Sender Details screen opens.
- Click Next to enable delivery tracking.
- The Track sms delivery toggle is turned on. Turn it off to disable delivery tracking.
-
Copy the SMS delivery tracking URL and paste it into the callback webhook settings of the partner's dashboard. MoEngage generates a unique identifier called custom_connectorID under the SMS delivery tracking URL, as shown below. All senders in a connector will have the same custom_connectorID and delivery tracking URL.
https://api-0X.moengage.com/sms/dlr/custom/<custom_connectorID> -
Map attributes/fields in the delivery response
You can either map the fields from the delivery response or map the fields manually by choosing the desired option. This mapping helps MoEngage understand the service provider's delivery response. To map the attributes in the delivery response, choose one of the following options:
- Map attributes of the delivery response
- Map fields manually
Field Name Description Attribute storing unique ID of the sent response
This field uniquely identifies the request. The value of this field should ideally match the value present in the Transaction or msg ID field.
Attribute storing Unique delivery ID field of delivery response This field stores the unique identifier of the delivery response. The value in this field should match the value in the sent response. This will help MoEngage identify the delivery response for any given SMS.
Attribute storing delivery status
This field contains the delivery status of the sent SMS. This is used to calculate the Delivered metric by MoEngage.
Success values for delivery status
The values denote that the SMS has been delivered successfully. We mark a message as delivered if any values mentioned in this field are received as part of the response. If any other value is received in the response, it will be considered a failure by default.
Attribute storing failure reason
This field contains the failure reason when an SMS delivery is unsuccessful. The failure reason can be seen in campaign analytics. For more information, refer to Failure Reasons.
To map the fields from the delivery response:
- Click Send a Test SMS to send a test SMS and receive a response from your service provider. Once MoEngage receives this information, it will be shown in the Dashboard. You can map the fields from this response.
- The dropdowns are auto-populated with the field names parsed from the delivery response. The following image shows the sample SMS sent and delivery response. The auto-population of the dropdowns from this response for mapping on the Dashboard is also illustrated in the image.
To manually map the fields in the response, select this option and enter the details in all fields mentioned in the table above. Refer to the API documentation of the custom connector to identify the values to be filled.
- Once the delivery response has been mapped, click Save to save the delivery callback configuration.
| info |
Note
|
Configure Service Provider in Old UI
To configure a Custom SMS Connector on the MoEngage Dashboard:
- Navigate to Settings -> Channel -> SMS & Connectors.
- Click on the SMS Connector Config tab. You’ll find the list of integrated connectors on the left-hand side.
-
Click +CREATE beside the Custom Connectors option on the left menu to add a new connector.
Once you click Create, a new connector named ‘New Connector’ gets added to the left menu. Select this newly added connector to set up your custom connector. - Fill in the following information and click Save. This saves your Custom Connector Configuration.
Field Description Sender Type
The Sender Type can either be Promotional or Transactional. Choose the Sender Type as Promotional when you would be using the Sender for sending information about your brand, promoting deals, or engaging with users. Choose the Sender Type as Transactional when you would be using the Sender for sending alerts about transactions, OTPs, security information, or any information that can be classified as transactional in nature.
Connector Name
This field identifies the Custom Connector you are configuring on the MoEngage Dashboard and has to be unique. Type the name of the connector here.
Sender Name
This field identifies the Sender. Type the name of the sender here.
API URL
-
- This field contains information about the URL that should be used to send an API request to the Sender. You can get this information from the API Documentation of the Sender. Type the API Endpoint of the sender here.
- Select GET, POST, or DELETE in the dropdown as per the specifications mentioned in the API Documentation of the Sender. Note: Every connector should have a distinct domain.
URL Parameters
Add the URL Parameters to be passed to the API as Key-Value pairs using this option. You can get this information from the API Documentation of the Sender. For example, if the API URL call uses the GET method, all the parameters, such as API Key, Authorization, and so on, are passed as URL Parameters.
Headers
Add the Request Headers to be passed to the API as Key-Value pairs using this option. You can get this information from the API Documentation of the Sender. For example, Authorization Headers and Content-Type Headers are added as KV pairs depending on the Sender's API specifications.
Body Type
Choose either Form, JSON, or Raw when the POST method is used to send information as part of the API request. This information can be found in the API Documentation of the Sender.
Form and JSON -Add Key-Value pairs for this request type.
Raw -Paste the request body when you choose ‘Raw’ as the Body Type.
-
- Click Send test SMS to verify whether the configuration is correct. After a successful test, Click Save to save the settings.
Delivery Tracking
Delivery tracking allows you to track the delivery status of the SMS messages sent using custom connectors. Delivery tracking will show a metric - Delivered, which helps you understand whether messages have been delivered to the user and analyze delivery failures and errors. You can use this information to clean up your delivery list periodically (by removing users for previous deliveries that were unsuccessful). This will help you avoid sending SMS campaigns to users with repeated delivery failures, thus saving costs.
You can add the Delivery Tracking information once you save the connector settings for the first time. Click Configure delivery tracking and follow these steps to map the fields in your delivery response to your connector.
-
Integrate delivery tracking URL
SMS delivery tracking URL is created for every custom connector and is available on the MoEngage Dashboard. Add this SMS delivery tracking URL in the API request sent to the custom connector. Alternatively, for some connectors, you must add the Delivery Tracking URL to the callback webhook settings of the custom connector's dashboard. MoEngage generates a unique identifier called custom_connectorID under the SMS delivery tracking URL, as shown below.
https://api-0X.moengage.com/sms/dlr/custom/<custom_connectorID>All senders in a connector will have the same custom_connectorID and delivery tracking URL.
-
Map attributes/fields in the delivery response
You can either map the fields from the delivery response or map the fields manually by choosing the desired option. This mapping helps MoEngage to understand the custom connector's delivery response.
Field Description Transaction or msg ID
This field, as part of the delivery response, uniquely identifies the request.
Unique sent ID
This field, as part of the sent response, uniquely identifies the request. The value of this field should ideally match the value present in the Transaction or msg ID field.
Delivery status
This field, as part of the delivery response, contains the delivery status of the sent SMS. This is used to calculate the Delivered metric by MoEngage.
Success values for delivery status
The values, as part of the delivery response, denotes that the SMS has been delivered successfully. We mark a message as delivered if any values mentioned in this field are received as part of the response. If any other value is received in the response, it will be considered a failure by default.
Failure reason
This field, as part of the delivery response, contains the failure reason when an SMS delivery is unsuccessful. The failure reason can be seen in campaign analytics. For more information, refer to Failure Reasons.
To map the fields from the delivery response:
- Click Send test SMS.
- Choose the country code and mobile number to which you want to send the test SMS and add a test message.
-
Click Send. Once you receive a success message, you can see the following message on the Dashboard.
It may take up to 15 minutes to receive the delivery callback information. Once MoEngage receives this information, it will be shown in the Dashboard. -
You can map the fields from this response. The dropdowns are auto-populated with the field names parsed from the delivery response. The first image shows a sample SMS delivery response, and the image below shows the auto-population of the dropdowns from this response for mapping on the Dashboard.
To map the fields in the response manually, select this option and enter the details in all fields mentioned in the table above. Refer to the API documentation of the custom connector to identify the values to be filled.
- Click Save to save the delivery callback configuration.
| info |
Note
|