> For the complete documentation index, see [llms.txt](https://docs.ushahidi.com/platform-user-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ushahidi.com/platform-user-manual/3.-configuring-your-deployment/3.4-data-sources/3.4.5-twilio.md).

# 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="/files/-MF-qLNd2xN1bJvan_yj" 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="/files/-MF-ucD1sQuDdG1zKRhi" 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="/files/-MF0OvmNNMPelQHyDiko" 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="/files/-MF0QwT7b0fRFO_uSrcg" 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="/files/-MF0SA3mutACizmYkdoT" 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="/files/-MF0WZXKW81LM00pegCK" 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="/files/csF03lN2CWYHZCUMLRzU" 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="/files/PqrIEK3goNPYH4uNr8Lb" 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="/files/Rb3F47iODdoGUdTI8vfh" 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="/files/-MF1-9qHCOUJsSnaVgrG" 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="/files/-MF100ooURsbBqs_kMPD" 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="/files/-MF12idlYIk-74VtTCDf" 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="/files/-MF16LhTFPH7S1Wk38x_" alt="SMS Logs"><figcaption><p>SMS Logs</p></figcaption></figure>

* Example of a single message below.

<figure><img src="/files/-MF16gErXuYXh_YxD05i" 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