# 3.4.5 Twilio

Twilio allows you to programmatically make and receive phone calls and send and receive text messages using its web service APIs.

***NB: You need a Twilio account to be able to configure this as a data source. To sign up, go to*** **\*\*\[\_**<https://www.twilio.com/try-twilio**_](https://www.twilio.com/try-twilio>)

To get started with Twilio set up,

* Log into your twilio account.
* You’ll need to buy a number to use. Click on the ***hashtag icon***

<figure><img src="https://content.gitbook.com/content/GBEUb85x3qZ9AiwfCkhF/blobs/7LrYj5D69SjX3APomxij/_2__Twilio.png" alt="Buy a number - # icon highlighted in the sidebar"><figcaption><p>Buy a number - # icon highlighted in the sidebar</p></figcaption></figure>

* Click on the ***red "Plus" icon.***

<figure><img src="https://content.gitbook.com/content/GBEUb85x3qZ9AiwfCkhF/blobs/j7MrAaAxcV5WcMHwNzZy/_2__Twilio.png" alt="Click on the red (+) icon highlighted"><figcaption><p>Click on the red (+) icon highlighted</p></figcaption></figure>

* Select the desired criteria for your phone number In the number selection/purchase screen
  * Select the country where you need a phone number. This is the number that people will use when sending a report through SMS.
  * Location/Number: You can search numbers by digits/phrases or by location. This is optional.
  * Capabilities (Voice, SMS, Fax, MMS): Make sure you tick the "SMS" checkbox. We want to make sure Twilio only shows us numbers with SMS capabilities. If it can't be ticked/clicked, then it means that Twilio doesn't have any numbers with SMS capabilities in that country.

<figure><img src="https://content.gitbook.com/content/GBEUb85x3qZ9AiwfCkhF/blobs/ed8nEcm63NNuoaUtHFN8/Twilio_Console_-_Phone_Numbers_Search.png" alt="Setting up a Twilio number. Capabilities selected: SMS. Select your Country, and a number. Then hit the search button."><figcaption><p>Setting up a Twilio number. Capabilities selected: SMS. Select your Country, and a number. Then hit the search button.</p></figcaption></figure>

* Click on **\*\*\_**&#x53;earch\*\*\_. A list of available numbers with their rates based on the criteria set above will appear
* Click ***Buy*** on the number you’d like to use.

<figure><img src="https://content.gitbook.com/content/GBEUb85x3qZ9AiwfCkhF/blobs/Wh4Cav5FxqoYkNWCQEG0/Twilio_Console_-_Phone_Numbers_Search_Buy_Results.png" alt="List of Twilio numbers. Click Buy to get one."><figcaption><p>List of Twilio numbers. Click Buy to get one.</p></figcaption></figure>

* You will be shown a screen like this one below where they confirm all capabilities, the number, and other details.&#x20;

<figure><img src="https://content.gitbook.com/content/GBEUb85x3qZ9AiwfCkhF/blobs/g4t2goz2DnXSQZtfLM9w/_2__Twilio.png" alt="Click the buy button purchase the number"><figcaption><p>Click the buy button purchase the number</p></figcaption></figure>

* Click the buy button at the bottom right hand of the screen to purchase your number.
* Once you have a phone number, note it down as you’ll need it to configure your data source later on.

### Configuring Ushahidi Platform to use your Twilio phone number

**First, we need to get the following information from your Twilio account:**

* ***Phone Number***: the number you just purchased. If you forgot it, you click the "***Hashtag***" icon in Twilio again to see your available numbers.
* ***Account SID***
  * Go to <https://www.twilio.com/console/>
  * You will see a panel like the one below with details about your project. Get the Account SID from it (we've highlighted it in the screenshot as a reference)

<figure><img src="https://content.gitbook.com/content/GBEUb85x3qZ9AiwfCkhF/blobs/a4sfl3DXE6ABsjsKe2Lf/_2__Twilio.png" alt="Account SID field highlighted"><figcaption><p>Account SID field highlighted</p></figcaption></figure>

* **Auth Token**
  * In the same panel as the account SID, you will see a "***view***" link next to "***Auth token***" as shown on the diagram above.&#x20;
  * Click it, and it will display your account's auth token.

**Next, with the Account SID, Auth Token and Phone number you just obtained:**

* Go to your Datasources settings page on your Ushahidi deployment.
* Click on ***the drop down icon on the right as shown***

<figure><img src="https://1490970077-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGBEUb85x3qZ9AiwfCkhF%2Fuploads%2FUG7pXjuhjP3AFWvmBUAO%2F3.4.20.png?alt=media&#x26;token=4bbbc03f-9c13-43e9-9eee-66b2072dd91b" alt="Twilio data source configuration."><figcaption><p>Twilio data source configuration.</p></figcaption></figure>

* You will see a list of fields like this one

<figure><img src="https://1490970077-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGBEUb85x3qZ9AiwfCkhF%2Fuploads%2F3qhfCFHn9hmkF5BqEchd%2F3.4.21.png?alt=media&#x26;token=0d8cd048-ebff-4d6c-9591-19366b2e937e" alt="Twilio datasource configuration in Ushahidi Platform."><figcaption><p>Twilio datasource configuration in Ushahidi Platform.</p></figcaption></figure>

* Enter the following details, which you got earlier from your Twilio Account
  * ***From***: Enter the phone number you got from Twilio.
  * ***ACCOUNT SID***: Enter the account SID of your Twilio account
  * ***AUTH TOKEN***: Enter the Auth Token retrieved from your Twilio account Dashboard page
  * ***SMS Auto Response***: This will be sent automatically when a user sends a message to your Twilio number. You could use it to provide reference information, like *thanking the user* or *just confirm receipt.*
  * Click on ***Save*** *\*\**&#x61;nd this data source’s settings will be saved. Unstructured posts from SMS will now be pulled into the platform from Twilio.
* To enable/disable the Twilio data source and choose which survey to import to, simply click on the green toggles.

<figure><img src="https://1490970077-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGBEUb85x3qZ9AiwfCkhF%2Fuploads%2FE5Jm2AkkdZRGtkPkSRVJ%2F3.4.22.png?alt=media&#x26;token=987d2e72-d77b-49f4-b1a6-721a15160655" alt="Enable survey submissions from Twilio."><figcaption><p>Enable survey submissions from Twilio.</p></figcaption></figure>

* At this point, your Twilio setup in Ushahidi Platform is ready to use but we need to do some follow up tasks in Twilio to connect both of them.

### Twilio setup for Ushahidi Platform SMS connectivity

Go to <https://www.twilio.com/console/phone-numbers/runtime/twiml-apps> where you can create Twiml apps. This is where we can make Twilio aware of the existence of your Ushahidi deployment and help them connect with each other.

<figure><img src="https://content.gitbook.com/content/GBEUb85x3qZ9AiwfCkhF/blobs/26o6ICeOrHeYhni8R8Br/_2__Twilio.png" alt="Twilio Page - TwiML Apps to setup Ushahidi Platform SMS connectivity"><figcaption><p>Twilio Page - TwiML Apps to setup Ushahidi Platform SMS connectivity</p></figcaption></figure>

* Click on the red "+" button to create a new app. You will see a screen like the one below.

<figure><img src="https://content.gitbook.com/content/GBEUb85x3qZ9AiwfCkhF/blobs/0ZnO3199KHBa1tplLUjR/_2__Twilio.png" alt="Create TwiML App"><figcaption><p>Create TwiML App</p></figcaption></figure>

Fill in these details;

* **Friendly name:** Write down a name that helps you remember what this app does. We usually choose the deployment name as the "friendly name" in Twilio.
* **Messaging: I**n this *\*\**&#x73;ection you will need to add your deployment's Twilio endpoint URL. This is the API Url to your deployment + the endpoint to connect to.

  For [Ushahidi.io](http://ushahidi.io) deployments, the rule is always the same. Given a deployment with the following url "https\://\*\*yourdeploymentname\*\*.\[ushahidi.io]\(<http://ushahidi.io>)" + the API Url will be = "https\://\*\*yourdeploymentname.api\*\*.\[ushahidi.io]\(<http://ushahidi.io>)".

  * Follow this formula to get your ***Request URL***:
    * Your deployment URL: "<https://**yourdeploymentname**.ushahidi.io>"
    * The API URL: "<https://**yourdeploymentname.api**.ushahidi.io>"
    * The ***Request URL*** then would be ["https://**yourdeploymentname.api**.*ushahidi.io*/sms/twilio".](https://yourdeploymentname.api.ushahidi.io/sms/twilio) is what you will enter in the "Request URL" field.
* After you are done with adding Messaging and friendly name, you can click the red "***Save***" button.

### Configure your phone number to send messages to Ushahidi platform

* Go to your list of active phone numbers and click on the number you purchased <https://www.twilio.com/console/phone-numbers/incoming>
* Click on your number.
* Scroll down and you will see a form like this one.

<figure><img src="https://content.gitbook.com/content/GBEUb85x3qZ9AiwfCkhF/blobs/8hzCbuiA3Dg5dIbhol83/Twilio_Cloud_Communications___Web_Service_API_for_building_Voice_and_SMS_Applications.png" alt="Configure with &#x22;TwiML App&#x22; and Enter the TWIML App friendly name"><figcaption><p>Configure with "TwiML App" and Enter the TwiML App friendly name</p></figcaption></figure>

* In the **configure with** fiel&#x64;***:*** Select **TwiML App**
* in the **TWIML APP** fiel&#x64;**:** Enter the **Friendly name** you created above for your deployment. This will ensure that when you get an SMS, Twilio sends a request to Ushahidi platform to save the message.

### Trying this out

#### Checking that Twilio gets the message

* Send an SMS to the phone number you purchased and configured (ie from your own phone).
* You can validate that messages are getting to Twilio by going to the Programmable SMS logs <https://www.twilio.com/console/sms/logs>
* You will see the messages your Twilio number has received and sent in the list
* The list will look like this. You can click on the red link under "Date" to see the details of each message.

<figure><img src="https://content.gitbook.com/content/GBEUb85x3qZ9AiwfCkhF/blobs/bCtliRQMvrfNYZe1g1lz/_2__Twilio.png" alt="SMS Logs"><figcaption><p>SMS Logs</p></figcaption></figure>

* Example of a single message below.

<figure><img src="https://content.gitbook.com/content/GBEUb85x3qZ9AiwfCkhF/blobs/RNkUOon4n2VXRMVkS7QL/_2__Twilio.png" alt="Details of a single Message"><figcaption><p>Details of a single Message</p></figcaption></figure>

### Checking that Ushahidi Platform gets the message

* Go to the Ushahidi Platform
* Go to the data view
* You should see the messages you sent in the data view list