Skip to content

SMS Configuration

To send and receive Short Message Service (SMS), you need an SMS service provider to communicate with Volt MX Engagement server. Volt MX Engagement server currently supports three SMS service providers TWILIO, NEXMO, CLICKATELL, and SALESFORCE for Text SMS and two SMS service providers TWILIO and NEXMO for Voice SMS. The SMS Configuration page enables you select the required service provider and enter the associated properties details.

To send and receive Text SMS, NEXMO and CLICKATELL support the following protocols:

HTTP : The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed and collaborative information systems. It is a generic, stateless, protocol that use request methods, error codes, and headers.

SMPP : The Short Message Peer-to-Peer (SMPP) protocol is an open, industry standard protocol. SMPP sends and receives medium-to-high volumes of SMS texts. VoltMX Engagement services supports SMPP version 3.4 (transceiver mode of communication).

Note: TWILIO and SALESFORCE supports HTTP protocol only.

To configure SMS notification, follow these steps:

  1. From the Settings section, click Configuration from the left panel.

    The Configuration page appears. By default, the General tab is set to active.

  2. Click the SMS Configuration tab.

    The SMS Configuration page appears. The SMS Configuration page includes two tabs:

    Outbound

    The Outbound tab includes SMS configuration and provider properties sections.

    SMS Configuration

    The SMS Configuration section includes the Provider drop-down list. You can select the required SMS service provider as TWILIO, NEXMO, CLICKATELL, or SALESFORCE. By default, the service provider is set to TWILIO.

  3. Based on your requirement, choose the service provider as:

    Provider Properties

    TWILIO

    If you select the service provider as TWILIO, enter details for the following fields:

    • Account SID: TWILIO provides you a unique Account SID for your account. Enter the Account SID in the Account SID field.

    • Auth Token: TWILIO provides you a unique Auth Token for your account. Enter the Auth Token in the Auth Token field.

      Note: TWILIO uses an Account SID and an Auth Token to authenticate you with its servers. Your Account SID and Auth Token are only known to you and TWILIO. It is important to keep both the keys confidential to protect your account.

    • From: Enter the phone number or client identifier that initiated the call. The phone numbers are formatted with a + sign and a country code such as +16175551212. The client identifiers begin with the client URL scheme. For example, for a call from a client named xxxx, the From parameter is client:xxxx.

    • Host URL: Based on a selected provider, the field is populated with the Host URL details.

    • Header Content Type: Based on a selected provider, the field is populated with the header content type as application/x-www-form-urlencoded.

      Note: The application/x-www-form-urlencoded is the content-type header  for HTTP POST requests that browsers must support.
      The request sends a list of name-value pairs to the server.

    • Maximum Character Limit: Based on a selected provider, the field is populated with the maximum number of characters allowed in an SMS message.

    • Enable Inbound Security: Select the check box, if you want to enable inbound security. The inbound security is applicable only for HTTP and not for SMPP. For SMPP, the request origin is always from a trusted source.

      If Enable Inbound Security option is enabled, all the inbound SMS requests are validated to check, if the request is from a valid source. For TWILIO, a header that TWILIO sends validates SMS requests.
      For CLICKATELL or NEXMO, SMS requests are validated by the IP address of the request origin. So for CLICKATELL or NEXMO you need to provide a list of white listed IPs.

      For White listing IPs, the load balance or reverse proxy server IP must be white listed. Volt MX Engagement Services accepts inbound requests from providers without any authentication (as provider do not have facility of authentication).
      In this scenario, any user can misuse and spend all the SMS credits. Thus to ensure security and check the authenticity of the request origin, inbound security option is enabled.

    • Click the Test Connection button to check if the connectivity is successful.
      The system displays the notification that the connection is successful. Click OK to continue.

      Note: The fields with a red asterisk are mandatory.

    NEXMO

    The NEXMO service provider supports the following protocols:

    Based on your requirement, select the protocol as HTTP or SMPP.

    HTTP

    By default, the protocol is set to HTTP.

    Provider Properties

    For HTTP protocol, enter details for the following properties:

    • API Key: NEXMO provides you a unique API Key for your account. Enter the provided API Key in the API Key field.
      The API keys track and prevents malicious use of an API. The API key acts as a unique identifier for authentication, and can be based on the Universally Unique Identifier (UUID) system to ensure that each API key is unique to each user. For example api_key=n3xm0rocks
    • API Secret: Enter the API Secret in the API Secret field.
      To sign up for API requests, NEXMO provides you an account API Secret. It is a pair of alphanumeric characters. For example, api_secret=12ab34cd
    • From: Enter the sender address in the From field. The sender address can be alphanumeric. For example, from=MyCompany20.
    • Host URL: Based on a selected provider, the field is populated with the Host URL details.

    • Header Content Type: Based on a selected provider, the field is populated with the header content type as application/x-www-form-urlencoded

      Note: The application/x-www-form-urlencoded is the content-type header for HTTP POST requests that browsers must support.
      The request sends a list of name-value pairs to the server.

    • Maximum Character Limit: Based on a selected provider, the field is populated with the maximum number of characters allowed in an SMS message. If the SMS message length exceeds the defined limit, Volt MX Engagement services truncates the SMS to the defined limit.

    • Enable Inbound Security: Select the checkbox, if you want to enable inbound security.

      If you enable the Enable Inbound Security option, all the inbound SMS requests are validated if the request is from a valid source. For TWILIO, a header that TWILIO sends validates SMS requests.
      For CLICKATELL or NEXMO, SMS requests are validated by the IP address of the request origin. So for CLICATELL or NEXMO you need to provide a list of white listed IPs.

      For White listing IPs, load balance or reverse proxy server IP must also be white listed. Volt MX Engagement Services accepts inbound requests from providers without any authentication (as provider do not have facility of authentication).
      In this scenario, any user can misuse and spend all the SMS credits. Thus to ensure security and check the authenticity of the request origin, the inbound security option is enabled.

    • Click Test Connection to check if the connectivity is successful.
      The system displays the notification that the connection is successful. Click OK to continue.

    SMPP

    For SMPP protocol, enter details for the following properties:

    Provider Properties

    For more details about API Key, API Secret, From,and Maximum Character Limit fields, see Provider Properties under HTTP section.

    • Host: By default, this field is populated with the Nexmo SMPP host address.
    • Port: By default, this field is populated with the port number of the Nexmo SMPP host.

    SMPP Properties

    • Use SSL: Select the check box to use the Secure Sockets Layer (SSL). When SSL is enabled, you may also need to change the port number.
    • Keep-Alive Interval(Seconds): The field populates with an already set value for the Keep-Alive interval.
      As SMPP protocol uses persistent socket connection, you need to periodically send ENQUIRE_LINK commands to the gateway. The Keep-Alive interval value determines how frequently Volt MX Engagement server needs to send the ENQUIRE_LINK commands.
      To keep the session alive for Nexmo, Volt MX Engagement server periodically sends ENQUIRE_LINK commands to the gateway every 20 seconds.

    • Async Window Size: The typical SMPP message flow involves the sender submitting a message to the server, and the receiver returning a response to acknowledge receipt of the message.

      Volt MX Engagement Services uses the asynchronous mode for submitting the messages to the gateway. For example, Volt MX Engagement Services does not need to wait for an acknowledgment of the previous message before submitting the next message. Instead, Volt MX Engagement Services sends the defined Window Size number of messages without receiving an acknowledgment.

      Based on SMPP specification, a default value of 10 is recommended, but you can increase this value if the network latency is high.

    • System Type: This value identifies the type of the system connecting to the gateway. Some providers may want the clients to send a specific value.

    • Source Address TON: For SMPP environment, you need to specify the Type of Number(TON) value for source address.

    • Source Address NPI: For the SMPP environment, you need to specify specific Numbering Plan Identification (NPI) values for the source address.

      Note: Source Address TON and Source Address NPI:These settings are applied to the sender address that is associated with messages submitted by Volt MX Engagement server.
      If a sender ID is in the international format (starts with a + character), provide a value 1  for TON and NPI. If you do not know the values, provide the value as 0 for TON and NPI.

    • Destination Address TON: For the SMPP environment, you need to specify a Type of Number(TON) value for the destination address.

    • Destination Address NPI: For SMPP environment you need to specify specific Numbering Plan Identification (NPI) values for the destination address.

      Note: Destination Address TON and Destination Address NPI: These settings are applied to the recipient addresses for messages submitted by Volt MX Engagement Services to the gateway. As the recipient addresses in Volt MX Engagement Services are in the international format(starts with +), the values are always one and one.

    • Optional TLV Parameters: Enter details.

      SMPP protocol has the support for optional TLV parameters. Some providers may want the clients (VoltMX Engagement Services here) to pass few additional parameters while interfacing with them. These additional parameters may include operator information, pricing information, and security information and so on.

      Volt MX Engagement services has the support to include multiple vendor specific optional TLV parameters. TLV stands for Tag, Length and Value that is the basic format for these parameters.

      Tag: Tag is a hexa-numeric value used to uniquely identify the optional parameter. The value should be in the range of 0x1400 - 0x3FFF. Enter the value without any hex prefix such as 0x.

      Type: The type of the optional parameter. Integer, String and CString are allowed. CString is the String type terminated with null.

      Length: The length of the optional parameter value in octets.
      For Integers, this value is required to specify if it is 1, 2 or 4 byte integer. If no value is provided for Integer type, Volt MX Engagement Services assumes it as a 4 byte integer.

      For String types (String and CString), the length is not required, the Engagement services calculates the length automatically. When provided for String types, the string value may be terminated to the specified length or padded with nulls. This is useful, if the provider expects the value to be of a fixed length always.

      Value: This is the value of the optional parameter.

      Multiple optional parameters can be added. All these parameters are used in the SUBMIT_SM command while submitting the message to the gateway.

      Note: The fields with a red asterisk are mandatory.

    CLICKATELL

    The CLICKATELL service provider supports the following protocols:

    Based on your requirement, select the protocol as HTTP or SMPP.

    HTTP

    By default, the protocol is set to HTTP.

    Provider Properties

    For HTTP protocol, enter details for the following properties:

    • User Name: Enter the user name in the User Name field.
    • Password: Enter the password in the Password field. The User Name and Password values are used to authenticate the user account details.
    • From: Enter the sender address in the From field.
    • Header Content Type: Based on a selected provider, the field is populated with the header content type as application/x-www-form-urlencoded
    • Maximum Character Limit: Based on a selected provider, the field is populated with the maximum number of characters allowed in an SMS message.
    • API ID: Enter the API ID.
    • Mobile Originated: For Clickatell, if inbound SMS is enabled, this parameter should be set to 1 to enable the reply for a message. This parameter when set to 1 will enable Clickatell to use a specific carrier to deliver the message. This can be left blank, if two way messaging is not enabled for the account.

    • Enable Inbound Security: Select the check box, if you want to enable the inbound security.

      If Enable Inbound Security option is enabled, then all inbound SMS request are validated if the request is from a valid source. For Twilio, an encrypted header sent by Twilio is used to validate the request. For Clickatell or Nexmo, SMS requests are validated by the IP address of the request origin. So for Clicatell or Nexmo you need to provide a list of white listed IPs.

    • WhiteList ips: If load balancer or reverse proxy server are used, their IP's must be white listed. Volt MX Foundry Engagement Services accepts inbound requests from providers without any authentication (as provider do not have facility of authentication). In this scenario, any user can misuse and spend all the SMS credits. Thus to ensure security and check the authenticity of the request origin inbound security option is enabled.

    SMPP

    For SMPP protocol, enter details for the following properties:

    Provider Properties

    For more details about User Name, Password, From, and Maximum Character Limit fields, see Provider Properties under the HTTP section

    • Host: Enter the SMPP Host URL details.
    • Port: Enter the port number of the CLICKATELL SMPP host.

    SMPP Properties

    • Use SSL: Select the check box to use Secure Sockets Layer (SSL). Change the port number if you enable SSL.
    • Keep-Alive Interval (Seconds): As SMPP protocol uses persistent socket connection, you need to periodically send the ENQUIRE_LINK commands to the gateway. The value determines how frequently Volt MX Engagement server needs to send the ENQUIRE_LINK commands.
      For CLICKATELL, Volt MX Engagement services sends the ENQUIRE_LINK command for every 20 seconds.

    • Async Window Size: In the typical SMPP message flow, the sender submits a message to the server and the receiver returns a response to acknowledge receipt of the message.

      Volt MX Engagement services uses the asynchronous mode to submit the messages to the gateway. For example, Volt MX Engagement Services does not need to wait for an acknowledgment of the previous message before submitting the next message. Instead, Volt MX Engagement Services sends the defined Window Size number of messages without receiving an acknowledgment. A default value of 10 is recommended for async window size, but you may increase the default value if the network latency is high.

    • System Type: CLICKATELL expects to send the API ID as the System Type. Enter the API ID value in this field. The entered value identifies the type of the system connecting to the gateway.

    • Source Address TON: For SMPP environment, enter the Type of Number (TON) value for the source address.

    • Source Address NPI: For SMPP environment, enter the Numbering Plan Identification (NPI) value for the source address.

      Note: Source Address TON and Source Address NPI: These settings are applied to the sender address that is associated with messages submitted by the Volt MX Engagement Services. If a sender ID is in international format  (starts with a + charac