Getting Started with the Africa's Talking USSD API: 2026 Guide

The Africa's Talking USSD API is one of the most popular ways to build mobile services for feature-phone and smartphone users across Africa. From SACCO loan applications to school fee balances and agritech ordering platforms, USSD is still the most universal channel on the continent. This 2026 guide walks you through the Africa's Talking USSD API end to end, the session lifecycle, shortcode types, billing and revenue share, going live with Safaricom and Airtel, and how HelloDuty acts as a managed alternative for teams that want USSD without writing a single line of code.

What is the Africa's Talking USSD API?

Africa's Talking is a pan-African CPaaS that offers USSD, SMS, voice and airtime APIs. Its USSD API lets you provision shared or dedicated shortcodes on Safaricom, Airtel, Telkom Kenya, MTN Uganda, Airtel Uganda, Vodacom Tanzania, Airtel Tanzania, MTN Rwanda, Ethio Telecom and several others. You expose a public callback URL, and Africa's Talking forwards each USSD session step to your endpoint as an HTTP POST.

If you are new to the protocol itself, start with our primers on Unstructured Supplementary Service Data (USSD) and the comprehensive guide to building USSD applications.

The USSD session lifecycle in 4 steps

A USSD session through Africa's Talking always follows the same four-step lifecycle. Think of it as a long-running HTTP conversation:

1. User dials the shortcode: the subscriber dials something like *483*100# on their handset.
2. Mobile operator opens a session: the MNO holds a transient session in its USSD gateway and forwards the request to Africa's Talking.
3. Africa's Talking calls your webhook: AT sends a POST request to your callback URL with parameters such as sessionId, phoneNumber, networkCode, serviceCode and text.
4. Your service responds with menu text: you reply with either a CON response (continue the session) or an END response (terminate the session) followed by the menu text the user should see.

The text field is the most important. On the first request it is empty. On subsequent requests it contains every user input separated by an asterisk, so by inspecting the latest token you know what menu the user is on. The session ends after about 180 seconds of inactivity or when you send END.

Step-by-step: create your first USSD app on Africa's Talking

Here is the non-code walkthrough of how to provision and ship your first USSD service. Each step is a single action in the Africa's Talking and HelloDuty dashboards.

1. Create an Africa's Talking account and verify your email address on account.africastalking.com.
2. Open the Sandbox app: every account ships with a sandbox application you can use for unlimited free testing.
3. Create a USSD channel under the Sandbox USSD menu: pick a channel number (for example 700), give it a descriptive name, and paste your callback URL.
4. Point the callback URL at a server you control: this can be a Node, Python, Go or PHP service hosted on Render, Heroku, AWS Lambda, Cloud Run or your own VM. It must respond within 10 seconds.
5. Use the Sandbox simulator to dial the channel from a fake phone number and walk your menus.
6. Move to production once your flow is stable: apply for a shared or dedicated shortcode through the Africa's Talking dashboard and pay the relevant fees.
7. Submit for MNO approval: Safaricom, Airtel and Telkom each review the menu tree and use case before going live.
8. Go live and monitor: watch session counts, success rates and revenue (for end-user billed codes) from the dashboard.

How to design your callback handler (without code blocks)

You do not need to copy any code from this article. Mentally, the handler is a switch statement on the latest text token:

• If text is empty, return CON plus the main menu.
• If text equals 1, return CON plus the submenu for option 1.
• If text equals 1*1, return END plus the final result for the leaf node.
• If text matches an unknown path, return END plus a friendly error.

In practice you will want to refactor this into a data-driven menu tree: a tree of nodes with handlers, validation and state stored against the sessionId. That keeps your code maintainable as menus grow past 3 or 4 levels.

Shared vs dedicated USSD shortcodes

Africa's Talking offers two shortcode flavours and they behave very differently in production.

Shared USSD codes

• You get a channel on a parent code, for example *483*X# in Kenya.
• Cheap to set up and quick to go live, often within 24 to 72 hours of approval.
• Great for MVPs, internal tools, low-volume B2B services and pilots.
• Limitation: the parent code is not yours, marketing it as a brand asset is harder.

Dedicated USSD codes

• A 3 to 6 digit shortcode reserved entirely for your brand, for example *123#.
• Higher monthly fee and an upfront deposit.
• Requires Communications Authority of Kenya (CAK) allocation and full MNO integration, typically 2 to 4 weeks.
• Mandatory once you want a memorable, brandable code in a consumer market.

For background reading, see the Africa's Talking help centre article on dedicated USSD code pricing and our deeper Kenya breakdown on top USSD providers in Kenya.

Africa's Talking USSD pricing in 2026

Pricing varies by country and shortcode type, but the rough public guide for Kenya is:

• Shared USSD code: from around KES 3,000 per month with a KES 5,000 setup fee.
• Dedicated USSD shortcode: from around KES 10,000 per month plus the CAK allocation fee.
• Session billing: typically billed to the service provider per USSD session, with rates that vary by MNO. Some use cases qualify for end-user billing where the subscriber pays the MNO directly.
• Deposit: a security deposit (around KES 10,000) is normally required to cover session costs.

Always check the live Africa's Talking pricing page, since MNO rates change.

Going live with Safaricom and Airtel

Once your sandbox app works end to end, the path to production has three checkpoints:

1. Top up your Africa's Talking wallet with the setup fee, first month fee and security deposit.
2. Submit a USSD application form: include the menu tree, screenshots, the legal name of the service provider and a data protection statement.
3. Wait for MNO approval: Safaricom is the longest reviewer, typically 2 to 4 weeks for dedicated codes. Airtel is faster. Once each MNO whitelists your code, your callback starts receiving live traffic.

Operationally, you also need to monitor session success rates per MNO, because Safaricom and Airtel have different timeouts and message length limits.

HelloDuty: a managed alternative for non-developers

The Africa's Talking USSD API is excellent for development teams. If you do not have engineers, or you want USSD plus voice plus WhatsApp on one dashboard, HelloDuty acts as a managed layer. With HelloDuty you:

• Provision Africa's Talking USSD channels from a single dashboard without writing webhook code.
• Build menus visually with a drag-and-drop flow builder.
• Plug menus into your CRM, M-Pesa Daraja, Google Sheets or a database without integration code.
• Run USSD, SMS, voice and WhatsApp Business under one billing relationship.

See our guide on choosing the right USSD platform for your business for a side-by-side comparison.

USSD use cases that work in Africa

• Mobile money menus: bill payment, person-to-person transfers, savings groups.
• SACCO and microfinance: balance enquiries, loan applications, repayments.
• Agritech: input ordering, market prices, weather and extension services.
• Health: appointment booking, NCD surveys, mental health hotlines.
• Education: school fee balances, exam results, e-learning subscriptions.
• Betting and gaming: account top-up, withdrawals, bet placement.
• Civic engagement: voter education, citizen reporting, government feedback.

Frequently asked questions

Is the Africa's Talking USSD Sandbox really free?

Yes. The Sandbox is free for development and testing. You only start paying once you provision a real shortcode and move to live MNO networks.

How long is a USSD session before it times out?

USSD sessions on Africa's Talking time out after roughly 180 seconds of inactivity, though the exact value can vary slightly by MNO. Each callback must respond within around 10 seconds.

Can I use the same callback for multiple countries?

Yes. Your callback receives the networkCode and serviceCode, so you can route logic by country or operator inside the same service.

What is the difference between CON and END in a USSD response?

CON tells the network to keep the session open and show the menu text. END terminates the session and shows the final message to the user.

Do I need a developer to launch a USSD service in Kenya?

Not if you use a managed platform like HelloDuty, which provides a visual flow builder, prebuilt integrations and managed shortcode provisioning. For deep custom logic, a developer using the Africa's Talking USSD API directly remains the most flexible option.

Launch your USSD service with HelloDuty

Whether you want to script every interaction yourself on the Africa's Talking USSD API or skip the engineering work entirely, HelloDuty has you covered. We provision shortcodes, host menu logic, integrate with M-Pesa, CRMs and databases, and support live operations across Kenya, Uganda, Tanzania and the wider African market. Get started with HelloDuty USSD and have your first menu live this week.