Ushahidi USSD integration features looking for alpha testers.

In 2019, David wrote about the need for USSD and the impact integrating this technology may have on our users. At the time, he was introducing the first version of a USSD integration prototype. We had worked with Tim (2019 GSOC intern) to understand how USSD could be integrated into the Ushahidi Platform.

The use case for USSD, from David's 2019 post.

Despite remarkable efforts, Internet access is still not a reality for all demographic groups across many regions of the globe. In many cases, basic cell phone coverage is still the best that is available.

In these scenarios, collection of information by SMS has been the method used by Ushahidi Platform deployers, in order to reach their audience.

One of the issues with SMS is that it’s not a great tool to fill in forms. In Ushahidi Platform, as soon as a survey includes a field other than “Description”, there’s an additional step needed to dissect each received SMS message and fill in the survey fields with that data. This is the process that some teams know as structuring. This is intensive manual work that causes a burden on teams, and at Ushahidi, we love nothing more than making life easier for users of the technology we produce.

Why USSD can help where SMS fails.

With USSD technology, filling each of the survey fields is done naturally by the target users, directly on their phones. Each of the questions in the survey will be asked on the user’s phone in succession and submitted into your deployment as a single response. The technology works on both smartphones and feature phones, making it possible to use it in many scenarios where the Ushahidi mobile website, or even mobile application, would leave users behind.

The USSD integration allows a user to respond to many types of fields, and has specific workflows for them that aren't possible in our SMS integration. For instance, our USSD integration allows a user to enter their location with an assistive UI and assigned to the correct field, rather than entering it as plain text in a generic description field. This results in greater accuracy and less manual work for deployers, and a much better experience for users trying to answer long questionnaires than they'd have with the [enterprise only] targeted surveys functionality for SMSs that was available before.

Earlier experiments with Ushahidi Platform.

The work Tim did meant that, if needed, we would be able to get someone set up with a basic USSD integration through Africa's Talking relatively quickly. It was always meant to be a foundational project rather than the final solution, and as with any early prototypes, there were a few things to resolve and think about:

  • How to go about productizing USSD so that *everyone* can have access to it with minimal cost (rather than needing our engineering team to set them up one by one)
  • How do we continue building on this, and create a system that enables different USSD and messaging providers to be plugged into the Ushahidi platform easily?
  • How do we maintain this long term so that we can expand on the capabilities, rather than make our team spread too thin across too many new things?

It was thanks to the confidence in having this prototype in the wild that we were able to make a bigger bet on USSD. By 2020, we were ready to work on a project that would enable us to take the work done in the 2019 prototypes into a productized version of USSD that anyone could use, and ensure that as the project grows it can be improved and maintained by anyone who already knows how PHP works. (PHP is the language we rely on the most for the Ushahidi Platform APIs)

The current status of the USSD integration functionality.

There is an open source integration for USSD built on PHP, which uses an open source chatbot framework called BotMan. We use BotMan to make it easier to build on top of the USSD engine and add more integrations later on. BotMan allowed us to use generic interfaces that are supported by a community and which we can extend. Extensibility is important for us because we want to be able to add more USSD providers, but also to continue adding chatbots on top of the engine as we need them, for example, we want to be able to add a Facebook bot that follows the same logic as the USSD engine. The USSD engine is also using the PHP SDK for the Ushahidi Platform, which is a new component we built to make it easier to communicate with the Ushahidi Platform v5+ APIs from PHP codebases.

With the upcoming translations features that allow users to translate Posts (responses), Surveys, and Categories, and which are integrated with the new USSD functionality, end users will be able to respond to surveys in any language you have made available and get your survey fields with the translations you added for them. This enables organizations using a Ushahidi deployment to reach a larger audience with less work. In the past, we had to use workarounds like creating multiple surveys to cover multiple languages, which meant it was harder to aggregate data and keep the survey structure consistent across languages (it was a manual process). With the new translations functionality you can simply add translations to each Survey field and have the user see it.

One of the hardest parts to get right when it comes to text-only interfaces such as USSD is the location functionality that users need to use to submit reports. Ideally, an end user should be able to enter a location quickly and accurately through the text fields presented in the USSD functionality. The approach we are taking with this is the following:

  • The USSD application presents a location field that guides the user by giving an example of the expected input.

  • Once the user enters a valid location, the application will confirm the country and other details as needed to get the right pin on the map. This is done to increase the accuracy of the response, since some street names may be the same in different countries. We use a 3rd party API to get the potential countries and details of their query.

  • When the user is happy with the result, they can submit and it shows up in the location field once they finish the survey.

We have also included an easy to use category, select, checkbox, and radio button fields to ensure you can clearly communicate and get the responses you need from users.

There are just some features included in this new version, see the video below for a demo of the functionality described above.


Where are we going?

  • We are working on making USSD productization happen. While USSD integrations include several steps outside of our control (ie: acquiring an account with a provider, paying for it, and getting a shortcode), we are focused on making the UX extremely simple on our end and finding ways to hint towards the next steps both internally and externally so that folks who are new to USSD can also evaluate the possibility of integrating this technology.
  • We are working on improving the location search code. While we have already covered the basics, we want it to be more powerful and to enable different 3rd party providers to be used when searching for a user's location. This is a separate component that will eventually serve not just USSD but some parts of the Web client such as the search for a location through text in ways that are more intuitive and accurate than the current direct queries we use.
  • We want to add more providers since we currently only support Africa's Talking. To do that, we are reaching out to our users and trying to understand where they operate in, what kind of needs they have in terms of USSD connectivity, and what their preferences are.

How to get involved.

  • The repository for the USSD engine is here. You can create bug reports, ask questions, and suggest improvements. You can also help us by reviewing and submitting pull requests. If you are planning to work on an issue, make sure you confirm first that it'll be welcome. This saves you time, and it saves us from rejecting a PR that doesn't align with the vision for the USSD engine.
  • USSD services providers: if you provide USSD services, and would like to integrate yours with our system, please get in touch. We'd love to collaborate with you to ensure more people get access to USSD integrations. We are always looking for ways to do this sustainably. One of the key challenges we face is that the cost for getting test environments with USSD setup is pretty high even with the support of our funders, and we'd absolutely be willing to work with you if you can help us get set up in your platform.

Happy holidays!

Photo by Karina Carvalho on Unsplash

Last but not least, happy holidays to all our growing Ushahidi community and contributors, we wish you a prosperous 2021.

Let us come together and do more! 🤗. Keep safe, wear your masks, wash your hands, and as always big love bombs ❤️💣 from the Ushahidi family💐