Buni.aiDocs
USSD
USSD

USSD overview

Build menu-driven services people dial from any phone, such as *789#, with no data connection or app.

A USSD project answers a short code. Someone dials a code such as *789# on any mobile phone, their handset shows your first menu, they reply with a number, and your flow decides what to show next. It works on feature phones, needs no data connection, and nothing has to be installed.

You build it on the same canvas as every other project type. The screens are Menu nodes; the logic between them is the usual Router, API, Data Store and Function nodes.

The New project dialog with Channel set to USSD and the USSD provider field showing
USSD is the only channel that asks for a provider when you create the project.

When to use USSD

Reach them byWhen
USSDThey may have a feature phone and no data. Balance checks, airtime and bundle purchases, registrations, surveys, simple payments.
ChatbotThey are on WhatsApp, web chat, Telegram, Messenger, Instagram or Slack. See Chatbot.
Voice (IVR)They are calling you. See Voice (IVR).

See Choose a project type for a longer comparison.

How a dial reaches your flow

You do not connect to the mobile network yourself. A USSD aggregator (or the carrier directly) owns the short code and forwards each step of the session to your project over HTTPS.

  1. The customer dials your short code.
  2. The network passes the session to your aggregator.
  3. The aggregator sends a request to your project's Callback URL, with the session ID, the caller's phone number and what they typed.
  4. Your flow runs until it reaches a screen, and returns that screen's text.
  5. The aggregator shows the text on the handset, and the next reply starts again at step 3.

You get the Callback URL when you publish, and paste it into your aggregator's dashboard. Going live walks through it, and the Routes page lists which short code points at which project.

Sessions

Each dial is one session. The aggregator gives it an ID, and Buni.ai keeps the session's state (the variables your flow has set) under that ID between replies, so later screens can use what earlier ones collected.

  • Every new session starts at the project's Main menu. A flow has exactly one.
  • A screen either keeps the session open and waits for a reply, or ends it. A Last menu always ends it, and so does any screen with nothing connected after it.
  • The network, not Buni.ai, decides how long an idle session may stay open. Keep journeys short: a caller who takes too long is cut off and has to dial again.

Menus and sessions covers menu types, navigation and how session endings are sent to the aggregator.

Screen length

A USSD screen holds very little text. The Menu node counts the whole screen (the message, every option and every navigation line) against a limit of 160 characters, and shows the count as you type. Going over it is reported as an error on the node.

Plain text only

Emoji and most symbols do not display reliably on handsets. The canvas warns about "Invalid Special Characters" when a menu contains them. Letters, digits and common punctuation are safe.

Nodes you can use

Conversation

MenuDisplays a list of options on a USSD screen and waits for the user to choose one.MessagingSends an SMS through Twilio, Africa’s Talking or Infobip.

AI

AI AgentAn LLM agent that understands intent, answers from your knowledge base and calls APIs, integrations and data stores.

Logic

RouterSends the flow down one of several paths based on conditions you define.Set FieldsSets or transforms state variables by assigning expressions to named fields.FilterContinues only when a condition is true, and stops the run quietly otherwise.FunctionRuns your own JavaScript and passes its return value to the next node.WaitPauses the workflow for a fixed duration before continuing.ApprovalPauses the workflow until a person approves or rejects it.Date & TimeGets the current time, formats and parses dates, adds or subtracts durations and computes differences.ErrorShows the user a message when their input is invalid, then lets them try again.

Data

Data StoreCreates, reads, updates and deletes records in one of your data stores.Remove DuplicatesRemoves duplicate items from a list in state, optionally comparing one field.ContactCreates or updates contacts, adds them to groups and sets custom properties from flow state.ResolveMarks the conversation’s underlying report as resolved, for loop-closure reporting.

Integrations

APICalls any HTTP endpoint and passes the response to the next node.IntegrationRuns an action in a connected service such as Salesforce, HubSpot, Google Sheets or Slack, without AI.Collect PaymentRequests a payment by mobile money prompt or card checkout link, on USSD, chat or a call.Respond WebhookReturns a custom HTTP status, headers and body to whoever called your webhook or trigger.

Next steps

Quickstart

Build and test an airtime top-up menu.

Menus and sessions

Menu types, options, navigation and dynamic lists.

Going live

Publish, connect your aggregator and record the short code.

Menu node reference

Every field on the Menu node.

Last reviewed 24 September 2026

Advanced chatbot features

Serve several languages, use AI and your knowledge base, keep contacts, show a privacy notice, and call a chatbot from your own systems.

USSD quickstart

Build an airtime top-up menu with Menu and Router nodes, then dial it in the simulator.

On this page

When to use USSDHow a dial reaches your flowSessionsScreen lengthNodes you can useNext steps