Dittofi
Search
K

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. 1.
    Twilio developer account
  2. 2.
    Send SMS message docs
  3. 3.
    Build Twilio web service
  4. 4.
    Webservice template

Twilio developer account

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.
Once you've completed this, go to the Twilio console at https://www.twilio.com/console, as below.
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.

Send SMS message docs

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.

Send SMS message endpoint

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

Build Twilio web service

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. 1.
    Create a custom model
  2. 2.
    Create Twilio web service
  3. 3.
    Create endpoints, actions & events
  4. 4.
    Build your code & test

Create a custom model

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.

Create Twilio web service

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.

Create endpoint, action & events

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.

Build your code & test

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

Webservice template

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.

What was installed?

  1. 1.
    The webservice
  2. 2.
    The API endpoint
  3. 3.
    The Custom Model (SMS Message) used in the webservice.

What was not installed?

We did not auto install:
  1. 1.
    Endpoints
  2. 2.
    Actions
  3. 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.