SMS Connector Configuration Guide

SMS Connector can be configured to run in integration with:

  • Hybrid Chat - to enable SMS and WhatsApp channel on the Hybrid Chat solution
  • CRM - for SMS delivery notification to the CRM 
  • ECM - To fetch and send SMS campaign messages from the ECM database

Integration with Hybrid Chat Server


REST API URL of the Chat Server. For example, https://<FQDN>/chat.

SMS Connector calls this chat server REST API to send a customer's message to the Chat solution. 

On this page

Twilio Integration

SMS Connector provides out-of-the-box integration with Twilio API for SMS and WhatsApp.

To register a mobile number in Twilio, which will be used to send customer messages to Twilio Whatsapp number or Twilio SMS number, follow these steps:

  1. Navigate to Phone Numbers from left menu and select 'Verified Caller IDs' or navigate to this  link.
  2. Click on '+' icon to add a new number.
  3. A form will open in popup.
  4. Fill the form and enter code sent to the phone number via call or text then submit.
  5. A toast will appear stating number added successfully and now number is added to send message to Twilio account through SMS or Whatsapp.

SMS via Twilio Integration Steps

We need to have an SMS capable Twilio account to send and receive SMS. Once we sign up, we get Account SID and Auth token (can be viewed from Twilio dashboard) that can be used as username and password respectively for basic authentication of Twilio REST APIs. 

To register a mobile number, that will be used to receive customer SMS and to send SMS from, follow below steps:

  1. Expand left side menu panel by click on three dots and click on phone numbers  under Super Network on Twilio dashboard
  2. Click on Plus sign under Active Numbers and choose a phone number from available number.
  3. Once a number is registered then click on it and it's details will open where we can do different configurations and see messages and events logs.
  4. On Configure tab, scroll down to Messaging section, here we will configure our sms connector inbound API as web-hook to receive any incoming sms that is sent to configured number in step 2. Keep all things default and pass sms connector inbound sms API complete URL (SMS-FQDN:PORT/sms/msg-client/receive) in text field against A MESSAGE COMES IN label. Twilio will use this API to push any incoming SMS. 
  5. The number configured should be set in sms-connector TWILIO_FROM_NUMBER environment variable.

If sms-connector SSL_TRUST_STORE_PATH environment variable is set, then we will need to add Twilio SSL certificate to our trust store. Open in chrome, export certificate and follow these steps to add certificate to trust store.

WhatsApp via Twilio Integration Steps

  1. Navigate to whatsapp sandbox using the link.
  2. Keep all things default and pass sms connector inbound message API complete URL (SMS-FQDN:PORT/sms/msg-client/receive) in text field against WHEN A MESSAGE COMES IN label. Twilio will use this API to push any incoming Whatsapp messages(HTTP POST). 
  3. See Getting Started with Twilio for WhatsApp to setup Twilio to send and receive WhatsApp messages.
  4. Navigate to whatsapp tab from Programmable SMS section or use this link.
  5. You will see a line like the following message "To begin testing, connect to your sandbox by sending a WhatsApp message from your device to +1 415 523 8886 with code join worker-anything."
    • The number mentioned after to is the number you will add as TWILIO_FROM_NUMBER.
    • Send join message to twilio number e.g. Join message in above mentioned example is "join worker-anything"
    • Now send a one-way message and two-way message to your number.
  6. Now in order to start chat using whatsapp you need to send message mentioned above in bold to TWILIO_FROM_NUMBER using a number from Verified Caller IDs.
  7. We only need to add whatsApp capability to our registered number mentioned in step 6.
  8. Rest of the things like web-hook configuration and delivery notification are same SMS configuration.

Environment Variables for Twilio Integration 

Variable NameDescription


Unique 34 character SID of the Twilio Account, e.g., AC496763443da6c75e0f1b5f27ddb3f515


Twilio auth token

example: 100865823c710ff641409f5703f50f98


Number registered with Twilio to send outbound SMS from. Use same format that is mentioned in Twilio dashboard.


Number registered with Twilio to send outbound whatsapp messages from. It consisting of whatsapp: followed by the sending WhatsApp number (usingE.164 formatting). For example, 


Twilio Outbound SMS REST API URL

If this variable is not set the default URL is constructed using TWILIO_API_ACCOUNT. For example,


SMS Connector receives SMS delivery status notification on http[s]://SMS-CONNECTOR-HOST:[PORT]/sms-client/delivery-notification. When this variable is set, it is pushed with every outbound sms to Twilio and Twilio uses this value a web-hook to push sms delivery notification back to sms connector.

  1. Specify exact callback API URL according to your host IP/FQDN and the port the connector is running on.
  2. Specify the same callback API URL against Twilio statusCallBack

For example, https://<FQDN>/sms-client/delivery-notification, where

(a) is the FQDN of your HOST where SMS Connector is running and

(b) 8080 is the service port.

ECM Integration

To pull scheduled SMS tasks from ECM to send out SMS messages to the customer. 

Variable NameDescription

ECM database driver name, mysql or sqlserver

example:  com.mysql.jdbc.Driver

ECM_DB_URLECM complete database URL
example: jdbc:mysql://mysql:3306/ecm?user=root&password=root

CRM Integration

To push delivery notification to a 3rd party CRM via REST. 

Variable NameDescription
IS_CRM_UPDATE_DISABLEDIf set to false, no sms delivery notification will be sent to third-party app like CRM

Any third party REST API URL and its credentials to push delivery notification after it is
received from Twilio.


CRM_API_USERCRM API username for basic auth

Enabling SSL 

Variable NameDescription

Enables/Disables SSL over sms-connector APIs. Possible values are:

  1. true
  2. false

Must be set to true if SMS Connector has to route the request to an SSL enabled application. The default value is false.


Path to SSL trust store, if not set then default keyStore.jks will be used that is shipped with the docker image. This will be a path from container and an outside volume shold be mounted to this path to have proper trust store files inside container.

example: /app/ssl/trustStore/trustStore.jks


This and below 3 variables are used to enable SSL over sms connector APIs if the aboA MESSAGE COMES INve variable (ENABLE_SSL) is set to true. If ENABLE_SSL is set to true and this and below 3 variables are not set then default certificates keys are used to enable SSL.

example: localhost


Key store type. 

example: jks


SSL Key store path. A volume from the host machine that contains Key store file should be mounted into sms-connector container and this variable will hold mounted path of container.

example: /app/ssl/keyStore/keyStore.jks

SSL_KEY_PASSSSL key password

ActiveMQ Integration

When integrated with Hybrid Chat, SMS Connector receives messages from HybridChat ActiveMQ queue. 

Variable NameDescription

Enables/Disables connection over SSL between SMS Connector and ActiveMQ. Possible values are:

  1. true
  2. false

Default is "false"


ActiveMQ host IP or FQDN. Default is "" 


ActiveMQ port. Default is "61616" 

AMQ_TRUST_STORE_PATHIf this and below 3 variables are not set then default truststore and keystore will be used
shipped with sms-connector image inside /app directory and names client.ts and client.ks
AMQ_KEY_STORE_PASSKey Store passwordAny limitations on the integration? For example, the Hybrid Chat solution works only with plain text. What other formats/messages would this integration not support?>

ActiveMQ queue from where sms-connector will read messages that are submitted by chat server and push them to Twilio for sending

example: outbound-sms

SMPP Integration

When integrated with Hybrid Chat, Customer Channel Manager receives messages from SMPP server and send messages to SMPP server. 

Variable NameDescription
true if SMPP is secure i.e. using SSL certificates else false. For SMPP Sim its value is "false"

IP address of SMPP Server e.g. ""


Port exposed by SMPP server e.g. "2775"

For smppsim port is "2775"


Number associated with SMPP server on which inbound messages are recieved e.g. "3221469577"

SMPP server system id used to connect to SMPP server.
For SMPP SIM it is "smppclient1"
SMPP server password for above mentioned system Id.
For SMPP SIM it is "password"

SMS Connector Limitations

  1. sms connector inbound API for incoming SMS and delivery-notification API for delivery notifications should be available over the internet.
  2. Only one Twilio account can be used with SMS Connector at a time.

SMS Connector APIs


Rest APIs documentation can be found here.

ActiveMQ API

SMS Connector will consume and push to Twilio messages from queue with name set in AMQ_OUTBOUND_QUEUE variable. The type of messages should be with name SendSms and the content should be in JSON format with the following definition.

  "text":"<smsText>" , 


  • number - is the phone number where the SMS should be sent 
  • text - SMS text
  • id - (optional) any application assigned identifier for tracking this message in the application

Related docs & files