Configure Custom Connector (Service Provider)

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:

  1. Navigate to Settings -> Channel -> SMS.
  2. Click on the Sender Configuration tab. You’ll find the list of integrated and custom service providers here.
  3. 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.
  4. Click +Add custom service provider.
  5. 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:

    1. GET
    2. POST
    3. 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.

    1. Form
    2. JSON
    3. 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.

    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.

    Send a Test SMS.gif

  6. 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:

  • Destination Number Key as Moesms_destination
  • Message Key as Moesms_message
  • DLT Template ID as Moesms_dltTemplateId (This is for clients operating in India)
  • Campaign ID as Moesms_campaignId (You can use this attribute in the POST and GET methods, not in the DELETE method).

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:

  1. Click on the ellipsis icon by hovering on the newly added sender in the SMS Settings screen.
  2. Select Edit. The Sender Details screen opens.
  3. Click Next to enable delivery tracking.
  4. The Track sms delivery toggle is turned on. Turn it off to disable delivery tracking.
  5. 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.

    SMS Delivery Tracking URL
    https://api-0X.moengage.com/sms/dlr/custom/<custom_connectorID>
  6. 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:

    1. Map attributes of the delivery response
    2. Map fields manually
    If you have not tested your configuration with Send a Test SMS during the previous step, click on Send a test SMS to map the attributes from the delivery response. 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.
    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.

    Map fields from the delivery response Map fields manually

    To map the fields from the delivery response:

    1. 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. 
    2. 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.

    MapFieldsFromResponse.png

  7. Once the delivery response has been mapped, click Save to save the delivery callback configuration.
info

Note

  • The delivery callback is a POST request and accepts a JSON payload.
  • To optimize system usage, reduce costs, and increase reliability, the delivery callback response payload should not exceed 150 KB in size. MoEngage will send a 413 Bad Request error if the response exceeds this limit. It is recommended to change the payload to a reduced size and send the response again in such a case. MoEngage recommends updating your payload creation code if this error is observed consistently.
  • Only Admins and Managers can configure Delivery Tracking in MoEngage.

Configure Service Provider in Old UI

To configure a Custom SMS Connector on the MoEngage Dashboard:

  1. Navigate to Settings -> Channel -> SMS & Connectors.
  2. Click on the SMS Connector Config tab. You’ll find the list of integrated connectors on the left-hand side.
  3. 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.
  4. 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

      1. 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.
      2. 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.

  5. 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.

  1. 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.

  2. 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.

    Map fields from the delivery response Map fields manually

    To map the fields from the delivery response:

    1. Click Send Test SMS
    2. Choose the country code and mobile number to which you want to send the test SMS and add a test message. 
    3. 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.
    4. 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. Karix_DeliveryResponse.pngDelivery_Response_Mapping.png
  3. Click Save to save the delivery callback configuration.
info

Note

  • The delivery callback is a POST request and accepts a JSON payload.
  • The delivery callback response payload should not exceed 150 KB in size to optimize infrastructure usage, cost, and increased reliability in both systems. In case the response exceeds this limit, MoEngage will send a 413 Bad Request error. It is recommended to change the payload to a reduced size and send the response again in such a case. If this error is observed consistently, MoEngage recommends updating your payload creation code.
  • Only Admins and Managers can configure Delivery Tracking in MoEngage.

Next Steps

  1. Create an SMS campaign.
  2. Set the Frequency Capping for SMS.
  3. Set the Current Service Provider.
Was this article helpful?
4 out of 7 found this helpful

How can we improve this article?