Module twilio
sandudstest/twilio
Twilio Connector
Connects the twilio communication services
Introduction
Twilio’s APIs power its platform for communications. Behind these APIs is a software layer connecting and optimizing communications networks around the world to allow your users to call and message anyone, globally. Twilio has a whole host of APIs, from SMS to Voice to Wireless! You can find Twilio's API reference documentation throughout twilio product documentation. For more information, Please browse the various Twilio APIs here. As twilio supports for HTTP Basic authentication. It needs the URL authentication for each request using the credentials provided by the twilio. You can find both your account SID and auth token in the Twilio Console after signing up for a free Twilio trial account. Twilio uses webhooks to asynchronously let your application know when events happen, like getting an incoming call or receiving an SMS message.
Connector Overview
The Twilio connector allows you to send SMS, voice and WhatsApp messages through the Twilio REST API and also connector provides the facility to receive inbound HTTP(S) requests (also known as webhooks) from Twilio's servers. The Twilio connector consists with two modules
-
Twilio client module - The default module that has the twilio client which can be used to communicate through the SMS, VoiceCalls and Whatsapp messages.
-
Webhook listener module - The module that provides the listener supports for the twilio events such as SentSMSEvent, VoiceCallRinging etc.
Prerequisites
-
Twilio Account to obtain Account SID, Auth Token and Twilio phone number
-
Java 11 Installed. Java Development Kit (JDK) with version 11 is required.
-
Ballerina Swan Lake Alpha Beta 1 is required.
-
(optional)ngork is requried to test listner samples using localhost
Configuration
Twilio Client Connector Configuration
-
Create a twilio account and follow this link to obtain a twilio phone number. If you use a trail account, you may need to verify your recipient phone numbers before having any communication with them.
-
Go to this follow this link to obtain twilio Account, Auth Token.
-
If you want to use Whatsapp service, Please configure your twilio phone number to use whatsApp services. You can find more detail on Twilio Whatsapp service here
-
Now you can use the obtained credential to use Twilio client connector. To do that, you may create a twilio client as shown in the samples with the following configuration record. You can also use Ballerina configurable variables to provide the credentials.
twilio:TwilioConfiguration twilioConfig = { accountSId: <YOUR ACCOUNT SID>, authToken: <YOUR AUTH TOKEN> };
Supported Versions & Limitations
Supported Versions
Version | |
---|---|
Ballerina Language | Swan Lake Alpha5 |
Twilio Basic API | 2010-04-01 |
Java Development Kit (JDK) | 11 |
Limitations
- The connector doesn't support to Authy based operation at the moment.
- The connector only supports limited number of operations of the twilio APIs.
Quickstart(s)
Module - ballerinax/twilio
Feature Overview
- Send SMS, WhatsApp messages
- Make voice calls
- Get Account Details
Getting started
-
Have a Quick Tour section to download and install Ballerina.
-
To use Twilio endpoint, you need to provide the following:
- Account SId
- Auth Token
-
Import the Twilio module to your Ballerina program as follows. You can use configurable variables to provide the necessary credentials.
import ballerina/log; import ballerinax/twilio; configurable string accountSId = ?; configurable string authToken = ?; public function main() { //Twilio Client configuration twilio:TwilioConfiguration twilioConfig = { accountSId: accountSId, authToken: authToken }; //Twilio Client twilio:Client twilioClient = new (twilioConfig); //Get account detail remote function is called by the twilio client var details = twilioClient->getAccountDetails(); //Response is printed as log messages if (details is twilio:Account) { log:printInfo("Account Detail: " + details.toString()); } else { log:printInfo(details.message()); } }
Getting started
-
Have a Quick Tour section to download and install Ballerina.
-
Import the Twilio listener module to your Ballerina program as follows.
import ballerina/log; import ballerinax/twilio; import ballerinax/twilio.'listener as twilioListener; configurable string & readonly twilioAuthToken = ?; configurable string & readonly callbackUrl = ?; configurable int & readonly port = ?; listener twilioListener:Listener tListener = new (port, twilioAuthToken, callbackUrl); service / on tListener { remote function onSmsDelivered(twilioListener:SmsStatusChangeEvent event) returns error? { log:printInfo("Delivered", event); } }
Samples
Twilio Client Operations
Get Account details
This shows you how to obtain the account details of your twilio account. Sample is available at: samples/client samples/getAccountDetail.bal
import ballerina/log; import ballerinax/twilio; configurable string accountSId = ?; configurable string authToken = ?; public function main() { //Twilio client configuration twilio:TwilioConfiguration twilioConfig = { accountSId: accountSId, authToken: authToken }; //Twilio client twilio:Client twilioClient = new (twilioConfig); //Get account detail remote function is called by the twilio client var details = twilioClient->getAccountDetails(); //Response is printed as log messages if (details is twilio:Account) { log:printInfo("Account Detail: " + details.toString()); } else { log:printInfo(details.message()); } }
Send an SMS
This section shows how to use the connector to send an SMS. You will need a verified phone number if you are using a trial account to send the message from your twilio phone number. if the SMS is sent successfully it will provides SMSResponse record with details of the SMS otherwise it will provide the error occurred. Sample is available at: samples/client samples/sendSMS.bal
import ballerina/log; import ballerinax/twilio; configurable string fromMobile = ?; configurable string toMobile = ?; configurable string accountSId = ?; configurable string authToken = ?; configurable string message = "Wso2-Test-SMS-Message"; public function main() { //Twilio client configuration twilio:TwilioConfiguration twilioConfig = { accountSId: accountSId, authToken: authToken }; //Twilio client twilio:Client twilioClient = new (twilioConfig); //Send SMS remote function is called by the twilio client var details = twilioClient->sendSms(fromMobile, toMobile, message); //Response is printed as log messages if (details is twilio:SmsResponse) { log:printInfo("SMS_SID: " + details.sid.toString() + ", Body: " + details.body.toString()); } else { log:printInfo(details.message()); } }
Send a whatappMessage
As the following example, the connector supports to send whatsApp messages and if the message is successfully sent , you will get WhatsAppResponse record otherwise an error message. Sample is available at: samples/client samples/sendWhatsappMessage.bal
import ballerina/log; import ballerinax/twilio; configurable string accountSId = ?; configurable string authToken = ?; configurable string fromMobile = ?; configurable string toMobile = ?; public function main() { //Twilio Client configuration twilio:TwilioConfiguration twilioConfig = { accountSId: accountSId, authToken: authToken }; //Twilio Client twilio:Client twilioClient = new (twilioConfig); //Send whatsapp remote function is called by the twilio client var details = twilioClient->sendWhatsAppMessage(fromNo = fromMobile, toNo = toMobile, message = "Test Whatsapp"); //Response is printed as log messages if (details is twilio:WhatsAppResponse) { log:printInfo("Message Detail: " + details.toString()); } else { log:printInfo(details.message()); } }
Make a voice call
You can make voice call with twilio voice enabled phone number. The following should be provided in addition to the account access credentials.
⋅⋅* fromNo
- the voice-enabled Twilio phone number you added to your account earlier
⋅⋅* toNo
- the person you'd like to call
⋅⋅* twiml
- Instructions in the form TwiML that explains what should happen when the other party picks up the phone
⋅⋅* statusCallback
- Optionally, instead of passing the Twiml parameter, you can provide a Url that returns TwiML Voice instructions.
Sample is available at: samples/client samples/makeVoiceCall.bal
import ballerina/log; import ballerinax/twilio; configurable string accountSId = ?; configurable string authToken = ?; configurable string fromMobile = ?; configurable string toMobile = ?; configurable string messageOrLink = ?; public function main() returns error?{ //Voice message type: twilio:MESSAGE_IN_TEXT or twilio:TWIML_URL twilio:VoiceCallInput voiceInput = { userInput:messageOrLink, userInputType: twilio:MESSAGE_IN_TEXT }; //Twilio Client configuration twilio:TwilioConfiguration twilioConfig = { accountSId: accountSId, authToken: authToken }; //Twilio Client twilio:Client twilioClient = check new (twilioConfig); //Make voice Call remote function is called by the twilio client var details = twilioClient->makeVoiceCall(fromMobile, toMobile, voiceInput); //Response is printed as log messages if (details is twilio:VoiceCallResponse) { log:printInfo("Message Detail: " + details.toString()); } else { log:printInfo(details.message()); } }
Get a message
This section shows you how to get a message details from your account. you need to provide message sid to retreive the details from the message list of your account. If the request is successful, it will send the MessageResourceResponse record else an error message with the details. Sample is available at: samples/client samples/getMessage.bal
import ballerina/log; import ballerinax/twilio; configurable string accountSId = ?; configurable string authToken = ?; public function main() { //Twilio client configuration twilio:TwilioConfiguration twilioConfig = { accountSId: accountSId, authToken: authToken }; //Twilio client twilio:Client twilioClient = new(twilioConfig); //Set Message resource SID to get themessage detial string messageSid = "<Add Mesaage SID>"; //Get SMS remote function is called by thetwilio client var details = twilioClient->getMessag(messageSid); //Response is printed as log messages if (details istwilio:MessageResourceResponse) { log:printInfo("Message Detail: " +details.toString()); } else { log:printInfo(details.message()); } }
Building from the source
- You need to obtain a twilio Account SID, an Auth Token and a valid twilio phone number to use the twilio connector operations.
- Clone the repository and Be sure to change the branch which has the name as the Ballerina version. Eg: slAlpha5
- Note: You need to install the relevant Ballerina version before going to the next step.
- First, If you want to run tests, you will need to add to a Config.toml file to the client module tests directory with the following credentials.
[ballerinax.twilio] twilioAccountSid ="<ACCOUNT SID>" twilioAuthToken ="<AUTH TOKEN>" fromNumber ="<YOUR TWILIO NUMBER>" toNumber ="RECIPIENT NUMBER" test_message ="<SMS MESSAGE>" twimlUrl ="<TWIML LINK>" fromWhatsappNumber="<TWILIO WHATSAPP NUMBER>"
-
Run
./gradlew build
to build the java wrapper. -
Run
bal build twilio
to build with tests or else Runbal build --skip-tests twilio
.