What is Twilio & how to integrate it into your Dittofi software application.
The Twilio API allows you to power your app with features that facilitate user communications. For a complete list of the services offered by Twilio API go to https://www.twilio.com/docs/all. This page lists all of the services Twilio has to offer.
In this tutorial we are going to look integrating with programmable SMS. To do this we will look at:
- 1.Twilio developer account
- 2.Send SMS message docs
- 3.Build Twilio web service
- 4.Webservice template
Sign up for a free trial by entering your user details. Next, enter the phone number that you want to use for the account & verify it.
On this page, you need to take note of your Account SID & Auth Token. You'll need these later on in the process.
In this section, you can read how to:
- Send an SMS message from your Twilio phone number
- Track your message's status
- Include media in your message (US & Canada only)
- Handle replies with AI-powered SMS bots
Here, we are going to show you how to setup Send an SMS message from your Twilio phone number.
To send SMS messages you need to implement the following POST endpoint.
Endpoint to send a text message from one phone number to another.
The endpoint requires that you send a request & then you get back a response. Details of what are included in the request & response are below.
Send SMS message
At a high level, we are looking to leverage the Twilio API to send a SMS messages from our Dittofi software application. To do this, we need to build a connection to the Twilio API from Dittofi.
Having studied Twilio's Send SMS Message endpoint we know that we are going to send a request to the API & get a response from the API. In order to accomplish this, we need to first do some basic setup tasks.
- 1.Create a custom model
- 2.Create Twilio web service
- 3.Create endpoints, actions & events
- 4.Build your code & test
The custom model will hold the response from the Send SMS Message endpoint. To set this up, go to the Custom Model tab inside the Dittofi Design Studio.
From within this view press "+ New Custom Model" > "Generate Model".
Next, select the option "Generate from JSON". This will generate your Custom Model directly from a JSON structure.
After you've selected "Generate from JSON", copy & paste in the response to the Send SMS Message endpoint.
Next we need to go through & make the following adjustments to the auto generated model.
- First: change the labels & names of the Custom Models to something more reflective of what they are doing.
- Second: make sure the Kinds are set correctly for each field in the Custom Model. On this topic, any fields marked as "null" in the Twilio API documentation cannot be automatically & accurately assigned Kinds inside Dittofi.
Lastly, click "Generate" & this will build your Custom Models.
Next, open your Dittofi application & head on over to the Web Services tab.
Go to the top right hand corner of the screen & press "+ New Webservice" & "New Webservice".
Give your webservice a name e.g. "Twilio API". Next, using the Twilio endpoint docs that we covered above, we first pick the protocol HTTPS, & second set the host to "api.twilio.com" & press Save.
To implement this API endpoint inside Dittofi, start by pressing "+ Add Endpoint" from inside your new webservice.
Next, fill in the form that slides out as below.
Notice that the Resp. Variable is set to SMS Message. This is the Custom Model that we created in the previous step. Notice also that the Req. Content Type is set to application/x-www-form-urlencoded. The reason for this is that the Twilio API sends the data back in this format. You can read this in their documentation (as shown below).
In the variables section of the API Endpoint, set the variable names as below. Notice that these are "uninitialized" or empty variables. We will set their values at a later stage.
After you've completed this, click Save & close down your API endpoint.
The next step of the process is to create an endpoint, action & event that will run the Twilio API Endpoint that we have created. To do this, let's start by creating an endpoint in the following way.
Notice that the Body Variable is a Custom Model to store the SMS message content that is being sent to the Twilio API. This Custom Model includes one field, as shown below.
Next create an Action & associate this action with the Send Message endpoint.
Next (A) add an HTTP event to the actions & events graph, (B) select our Webservice Twilio API & (C) pick the Webservices Endpoint Send SMS Message.
Lastly, we need to set the values for each of our variables. This can be done from several locations. The table below explains what each of these variables is.
After you've added your variables, save your event & your action.
The final step is to build your code & test. You can test by running the endpoint from your Endpoints tab. Alternatively, you can build a frontend interface & set this up to send a trigger to start your endpoint, action, event & web service.
Example interface for Twilio integration
Dittofi allows users to save & publish web service configurations. Once saved & published an web service can be installed in a single click by other users.
We have saved & published the work done in this article. You can install it by clicking on (A) "+ New Webservice" > (B) "Install Webservice" > (C) "Details" & (D) "Install".
Let's take a quick look at what was installed & what was not.
- 1.The webservice
- 2.The API endpoint
- 3.The Custom Model (SMS Message) used in the webservice.
We did not auto install:
These items contain variable information such as AccountSid that will be specific to each user. Furthermore, whilst the method of accessing the API will be over HTTPS for all users, the implementation of phone numbers to message & with what message may all be different.