Configure Custom Connector

MoEngage natively integrates with five 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 on the MoEngage Dashboard.

Configure Custom Connector

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 with the name ‘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.
info

Note

Set the following values as specified below when defining the request parameters/headers/body.

    1. Destination Number Key should be set as Moesms_destination 
    2. Message Key should be set as Moesms_message. 
    3. DLT Template ID as Moesms_dltTemplateId (this is for clients operating in India).

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 whom previous deliveries were unsuccessful). This will help you avoid sending SMS campaigns to users who've had 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 will have to 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. <Link to Analyze SMS campaign>

      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

  1. Delivery callbacks are not received for Promotional messages in India, as per TRAI's DLT regulations.
  2. Only Admins and Managers can configure Delivery Tracking in MoEngage.

Next Steps

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