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

NameDescription
CHAT_SOLUTION_URL

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 https://twilio.com 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

TWILIO_API_ACCOUNT

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

TWILIO_API_TOKEN

Twilio auth token

example: 100865823c710ff641409f5703f50f98

TWILIO_FROM_NUMBER

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

TWILIO_WHATSAPP_FROM_NUMBER

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, 

whatsapp:+14155238886
TWILIO_OUTBOUND_API_URL (optional)

Twilio Outbound SMS REST API URL

If this variable is not set the default URL is constructed using TWILIO_API_ACCOUNT. For example, https://api.twilio.com/2010-04-01/Accounts/AC496763443da6c75e0f1b5f27ddb3f515/Messages.json

TWILIO_STATUS_CALLBACK

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) sms.hybrid-chat.com 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_DB_DRIVER

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
CRM_API_URL

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

example:http://<FQDN>/smsDeliveryNotification

CRM_API_USERCRM API username for basic auth
CRM_API_PASSWORDCRM API password

Enabling SSL 

Variable NameDescription
ENABLE_SSL

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.

SSL_TRUST_STORE_PATH

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

SSL_KEY_ALIAS

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

SSL_KEY_STORE_TYPE

Key store type. 

example: jks

SSL_KEY_STORE

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
AMQ_SSL_ENABLED

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

  1. true
  2. false

Default is "false"

AMQ_HOST

ActiveMQ host IP or FQDN. Default is "127.0.0.1" 

AMQ_PORT

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
respectively
AMQ_TRUST_STORE_PASS_PHRASETrust store password
AMQ_KEY_STORE_PATHKey Store path
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?>
AMQ_OUTBOUND_QUEUE

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
SMPP_SECURE
true if SMPP is secure i.e. using SSL certificates else false. For SMPP Sim its value is "false"
SMPP_REMOTE_IP_ADDRESS

IP address of SMPP Server e.g. "192.168.10.10"

SMPP_REMOTE_PORT

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

For smppsim port is "2775"

SMPP_FROM_NUMBER

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

SMPP_SYSTEM_ID
SMPP server system id used to connect to SMPP server.
For SMPP SIM it is "smppclient1"
SMPP_PASSWORD
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 API

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.

{ 
  "number":"<customerNumber>", 
  "text":"<smsText>" , 
  "id":"<messageId>" 
}

where,

  • 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

link