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.com/chat .
SMS Connector calls this chat server REST API to send a customer's message to the Chat solution.
On this page
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:
- Navigate to Phone Numbers from left menu and select 'Verified Caller IDs' or navigate to this link.
- Click on '+' icon to add a new number.
- A form will open in popup.
- Fill the form and enter code sent to the phone number via call or text then submit.
- 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:
- Expand left side menu panel by click on three dots and click on phone numbers under Super Network on Twilio dashboard
- Click on Plus sign under Active Numbers and choose a phone number from available number.
- 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.
- 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/msg-client/inbound) in text field against A MESSAGE COMES IN label. Twilio will use this API to push any incoming SMS.
- The number configured should be set in sms-connector
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 vis Twilio Integration Steps
- Navigate to whatsapp sandbox using the link.
- Keep all things default and pass sms connector inbound message API complete URL (SMS-FQDN:PORT/msg-client/inbound) in text field against WHEN A MESSAGE COMES IN label. Twilio will use this API to push any incoming Whatsapp messages(HTTP POST).
- See Getting Started with Twilio for WhatsApp to setup Twilio to send and receive WhatsApp messages.
- Navigate to whatsapp tab from Programmable SMS section or use this link.
- 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.
- 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.
- We only need to add whatsApp capability to our registered number mentioned in step 6.
- Rest of the things like web-hook configuration and delivery notification are same SMS configuration.
Environment Variables for Twilio Integration
Unique 34 character SID of the Twilio Account, e.g., AC496763443da6c75e0f1b5f27ddb3f515
Twilio auth token
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
Twilio Outbound SMS REST API URL
If this variable is not set the default URL is constructed using
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.
For example, https://sms.hybrid-chat.com:8080/sms-client/delivery-notification, where
To pull scheduled SMS tasks from ECM to send out SMS messages to the customer.
ECM database driver name, mysql or sqlserver
|ECM_DB_URL||ECM complete database URL|
To push delivery notification to a 3rd party CRM via REST.
|IS_CRM_UPDATE_DISABLED||If 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
|CRM_API_USER||CRM API username for basic auth|
|CRM_API_PASSWORD||CRM API password|
Enables/Disables SSL over sms-connector APIs. Possible values are:
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.
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.
Key store type.
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.
|SSL key password|
When integrated with Hybrid Chat, SMS Connector receives messages from HybridChat ActiveMQ queue.
Enables/Disables connection over SSL between SMS Connector and ActiveMQ. Possible values are:
Default is "false"
ActiveMQ host IP or FQDN. Default is "127.0.0.1"
ActiveMQ port. Default is "61616"
|If 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
|Trust store password|
|Key Store path|
|Key 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
SMS Connector Limitations
- sms connector inbound API for incoming SMS and delivery-notification API for delivery notifications should be available over the internet.
- Only one Twilio account can be used with SMS Connector at a time.
SMS Connector APIs
Rest APIs documentation can be found here.
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- 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