Twilio
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
Before you start integrating with Twilio, you need to create a developer account. To do this, go to https://www.twilio.com/try-twilio.
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.
You also need a Twilio number. To get access to this number you can buy one here. The numbers cost $1 with a starting balance of approximately $15.
To use Twilio to send an SMS message, go to https://www.twilio.com/docs/sms. From here, scroll down to the section "Send message with the API" & click on this heading.
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.
post
http://api.twilio.com/
2010-04-01/Accounts/{AccountSid}/Messages.json
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.
Field | Kind |
price | Number with Decimal |
error_code | Number with Decimal |
messaging_service_sid | Text |
error_message | Text |
price_unit | Text |
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.
Next, we need to enter the Twilio API endpoints that we want to hit. In this example, we are hitting the endpoint Send SMS Message described in the previous section & in the Twilio API docs.
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.
Name / Label | Expression |
From | This is the Twilio number that you purchased. You can set this by adding an event variable & entering in the Twilio number as an expression. |
To | This is the number that you are sending a message to. This can either be set as a static number, pulled from a data model & passed to your endpoint or input by your application users. |
Authorization | Go to the address & enter your Twilio AccountSid as your username, & your Twilio AuthToken as your password. Then press Generate Header. This will generate a string. Take this string & copy it & apply it to an expression inside your event variable. |
Content-Type | Add the string "application/x-www-form-urlencoded" as an expression inside an event variable. |
Accept | Add the string "application/json" as an expression inside an event variable. |
AccountSid | Add your AccountSid as an expression inside an event variable. |
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:
- 1.Endpoints
- 2.Actions
- 3.Events
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.
Last modified 2yr ago