Create Custom Connection

FrontlineSMS has an HTTP interface from where you can create a custom connection.

A custom connection is a connection to an aggregator that is not natively supported in FrontlineSMS. This allows you to Send SMS that has a REST API.

To create a custom connection go to Settings -> Connections to mobile networks.
This is the page for managing all your connections on FrontlineSMS. You can update, delete or create connections from this page


Click the Connect to a mobile network button to launch a sidebar from where you can create a custom connection.
The sidebar contains all aggregators that FrontlineSMS supports.

Choose the custom aggregator option.

The form for creating a custom aggregator has various fields and is divided into three sections. Name Section, Sending settings section, and Receiving settings sections. I will explain what type of information is required by each of the fields to successfully create a custom aggregator for sending and receiving SMS messages.




Name section.
Each custom aggregator requires a name. The name can contain any characters and it does not have to be unique.


Sending Settings section.
This section contains the information required by an aggregator when sending an SMS via their API. This section contains 5 fields.

  • Endpoint URL(required): The HTTP link for connecting to the aggregator
    HTTP Method: The supported methods are GET and POST. Choose the appropriate one as required by the aggregator.
  • Content-Type: The type contents in the API request. Frontline has support for URL-ENCODED, JSON, and XML. You can also supply any Content-Type via the Request headers. Choose others to specify the content-type in the request header.
  • Request Headers: The headers required for a request to the successfully made.
  • Single messaging Payload: These are the parameters required in the api request. The message is store in the ${text} variable while the mobile number is stored in ${destination} variable. Supply these values to the corresponding parameters required by the aggregator. This field has support for URL encoded data, JSON, XML, or any other content type. Use this when sending a single SMS to one recipient at a time.
  • Bulk messaging payload: Works the same way as the single message payload and is used for including the parameters required by the aggregator for sending bulk messages. The text message is stored in the ${text} variable while the mobile numbers are stored in the ${destinations} variable. Use this when sending bulk messages.

NOTE:The parameters for both the single messaging payload and bulk messaging payload should correspond to what the aggregator expects in the API request for sending an SMS.

  • Condition for marking the message as sent(required): This field uses an expression provided to determine whether a message has been successfully sent. It uses the status code sent back by the aggregator after sending a request. The status code is stored in responseCode variable. An example of an expression that can be used is:
    ${responseCode >= 200 && responseCode < 300 && responseCode != 203}. When the expression above returns true, the messages will be marked as successfully sent on FrontlineSMS.


Receiving settings
These are settings for handling the response sent back to FrontlineSMS when using a two-way API. i.e receiving responses for the SMS messages sent. This section contains two fields

  • Message Expression: The expression for evaluating the replied message. To access the contents message use: ${params.msg} for form-encoded data or ${parseJSON(requestText).msg}
  • Sender Number expression: The expression for evaluating the mobile number of the message sender. To access the contents message use: ${params.src} for form-encoded data or ${parseJSON(requestText).src}

Once you save the values above, the aggregator will be available for use for sending SMS messages. The aggregator used will be dependent on the routing rules.

Have more questions? Submit a request


Please sign in to leave a comment.