Two-way Communication for Humanitarian Operations with USSD in Twilio Flex

Two-way Communication for Humanitarian Operations with USSD in Twilio Flex

“You…what?!” We admittedly were caught by surprise when one of our Twilio.org customers asked about adding USSD as an additional channel to their contact center built on Twilio Flex. So we did what we love: we took a deep dive, learned all about USSD, and made it happen.  

If you have ever called a number that starts with * and ends in # for services like balance on a prepaid card, then you have used USSD. Or if you haven’t, try it now: type *#06# on your phone’s keypad. See? You immediately received key info about your phone (IMEI number and other device information).

In this post, we share what we learned about USSD, why it is such a powerful channel and explain how you can add a USSD channel to your Twilio Flex contact center in a few simple steps.

What is USSD?

Unstructured Supplementary Service Data (USSD) is a communication protocol that connects mobile devices directly and in real-time to network operators like Asiacell, MTN or Safaricom and service providers like Africa’s Talking and Telerivet. Dialing a USSD code on the keypad of a phone creates a session with a USSD service. The user sends a USSD message that can consist of the symbols available on any mobile phone up to 182 characters long. This message is received by the service which then, based on the data provided, can respond appropriately by executing a function such as ‘reply with the amount of credit balance remaining’.

The power of USSD

The power of USSD is its direct connection; no internet is required and it works across all devices (from old ‘Nokia’ feature phones to the latest smartphones) so it can be used just about anywhere in the world – as long as there is a connection with a mobile network. This makes USSD a powerful channel for a range of communication services for humanitarian and development assistance, for example a hotline for people in need of an immediate answer, provision of direct assistance such as cash vouchers, referrals and location-based services including search and rescue. Some interesting uses we have come across are identity verification (also known as 2-Factor Authentication (2FA), data collection (surveys, questionnaires, needs assessments) by field staff, refugee assistance in Uganda, individual COVID-19 messaging in Kenya and COVID-19 self-assessments in Bangladesh and cash assistance for farmers in Togo.

Often, affected populations or communities requesting of humanitarian assistance will already be familiar with USSD as it is already extensively used for charging prepaid mobile credit (e.g., through a USSD code on a scratch card) or to check the remaining balance in South Sudan, free callback service in Nigeria (dial *121* number #), and sending mobile money (for example M-PESA) as cash assistance in Kenya.

Comparison with SMS

USSD is similar to Short Message Service (SMS) in that it can be used to send messages. But it has three big advantages. First, unlike SMS, writing a USSD message creates a real-time connection. This way, USSD enables two-way communication, so questions and answers are immediate (as long as a connection is in place).

A second advantage of USSD over SMS is that it offers more structured interactions with users when more than one data item is needed. For example, when you require full (both first and last name) information, location, as well as the specific service the user requests.

And last but not least, USSD is cheaper than SMS in cost, engagement, and structure. USSD is more cost-efficient considering an entire interaction. So if a typical communication session consists of 5 questions and answers, this requires 10 SMSs to be sent back and forth. With USSD, however, this only requires 1 session and as most mobile network operators charge per session, this ends up being much cheaper. While SMS might be cheaper on a per-unit basis, it is charged per segment, and long SMS messages consist of 160-character segments sent individually, so this ends up being more expensive.

USSD in humanitarian operations: cost-saving and secure

USSD can be particularly powerful in humanitarian operations and the provision of direct assistance to people affected by man-made or natural disasters, for example, in areas where access to smartphones and mobile internet is limited, or where users cannot access data packages or use other channels such as SMS due to the associated costs. USSD-capable mobile phone penetration is relatively high globally and most importantly USSD can be made  free of charge to the end user. 

Besides cost, perhaps even more important when serving people in vulnerable situations is the fact that USSD does not leave a trace on the phone. This makes USSD an ideal channel for situations where privacy and safety are vital, such as survivors of abuse or people living in areas under the control of oppressive regimes or armed groups.

Integrate USSD in Flex: step-by-step technical solution

Step 1. Prerequisites

Before starting, you need to:

• Create a Twilio Account with a Flex Project. (If you haven’t yet, you can sign up for a free account here.)
• Install the Twilio CLI 
• Get a Telerivet Account (or any other USSD service provider)

1. Once you’ve set up your accounts, you will need to get a USSD code from a provider. A USSD code is the unique code for your service e.g., *123*456#. Typically telecom providers or Mobile Network Providers in your areas will provide these services. Twilio currently does not provide USSD codes.
2. Next, decide which information you require from the user and which answers (in terms of assistance) will be provided. Some things you might want to determine are:
   
   1. Get the preferred language (English / French)
   2. Get the location (Dakar/Touba/Thies)
   3. Get the type of support needed (Shelter/Legal/Food & Clothing)
   4. If the user is requesting a call back (Yes/No)

Step 2. Solution Overview

We’ll use the code samples from the Flex USSD Channel Demo repo . There are three main parts of the solution. The first two are the server side (telerivet-server) and the third is on the Flex UI (plugin-telerivet-taskinfo).

1. The Telerivet Service (telerivet-ussd-service.js) sits on Telerivet and provides the USSD Menu that the end user interacts with. This is written in JavaScript. This service packages the user’s selection and sends it to a Twilio webhook
2. The Twilio webhook (twilio-ussd-listener.js) listens for any incoming support requests on the USSD channel. This creates a Task for Flex
3. A Flex Plugin (TelerivetTaskinfoPlugin.js) that renders the the custom attributes

Step 3. Implementation

3.1 Setup Twilio Flex

• Create a Twilio Account with a Flex Project
• Make a note of your Flex phone number

3.2 Create the Twilio USSD Handler

• Use the code from this  Flex USSD Channel Demo repo
• Get the required environment variables  
  • Login to the console and get the TaskRouter Workspace SID from Twilio. You will need this to create a task to Flex. Take note of the SID, which will look something like WSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Get the Account SID, Account Token from the Twilio Console
  

• Create a secret for Telerivet - create a safe secret - preferably a guid
• Copy .env.sample to .env and update the following from the values from previous step
  • TELERIVET_USSD_SECRET
  • ACCOUNT_SID
  • AUTH_TOKEN
  • TASK_WORKSPACE_ID
• Deploy the USSD listener to Twilio serverless environment. Run the following commands on the command line:
  • cd telerivet-server
  • twilio serverless:deploy

This will deploy your solution to Twilio - make note of the URL that is deployed, we will use it for Telerivet later.

3.3 Create the Telerivet Service to track USSD Data

• Navigate to the Services,click  the select “Add New Service” button
  

• Select Cloud Script API
  

• Select ‘When a USSD request is received’
  

• Name the service USSD-Flex-Service
• Copy the code from telerivet-ussd-service.js


• You will need to replace two pieces here- search for REPLACE_ME to find both
  • The secret - use the secret you created (.env)
  • The Twilio webhook URL
    

3.4 Add Telerivet USSD Route

You can work with Telerivet team or your vendor to create a USSD Route

3.5 Test the Telerivet Service

You can test using the simulator. Other vendors will have a simulator similar to this.

• Launch Flex by going to the console . Make yourself “Available”
• Navigate to the Services, click “Test Services”
  

• This can be a little confusing - you will need to input two numbers. The Caller number - you can use your own number. Pick the USSD route and click ‘Simulate USSD Request’
  

• Follow the prompts, you will get a confirmation
  

• You will see a task come in on Twilio Flex.
  

• You will notice that the task does not have the user entered data. We will create a plugin to render that data.

3.6 Add Flex Plugin to show Menu Data

We will add a component to show the menu data. Refer to this document to get some background information

• You will use the code from plugin-telerivet-taskinfo
• Deploy the plugin and re-test the flow using the Telerivet Simulator as described in Step 3.5. The task will look like this.
  

Using Unstructured Supplementary Service Data with Flex

Now you’ve learned why and how to add a USSD channel to your Flex Contact Center, and you can increase the reach of your services. With your Flex instance, you can implement many other interesting workflows like real time translation, WhatsApp location sharing, replying to missed calls, callback service and interagency referrals.

Please let us know if we can help with any of the above. We are always eager to learn, share or support – for example, through our Twilio.org Impact Access program.

Gunjan Gupta is a Principal Solutions Engineer at Twilio.org. Gunjan partners with social impact organizations to create tech solutions for communication workflows. Her areas of interest are digital health, cash assistance, and humanitarian aid. She is currently working on solutions using Twilio technologies like Flex, Frontline and WhatsApp. You can reach her at gugupta[at]twilio.com.

Christina Hiemstra is a Strategic Program Manager at Twilio.org and supports aid organizations with tools to engage with the people and communities they serve, for example with cash-based programming, food assistance or e-health services. She is passionate about finding new and pragmatic solutions and believes that effective communication begins with listening. You can reach her at chiemstra[at]twilio.com.

Dave Rono is a Staff Software Engineer working on Twilio's Programmable Messaging API. Dave has extensive experience in developing communication solutions delivered through USSD, SMS and MMS. He has a passion for working on solutions that bridge communication gaps between knowledge bases and consumers of information by applying appropriate technology that’s localised to the target audience.