USSD

USSD provides interactive, menu-driven conversations on feature phones and smartphones without internet. Powered by Africa's Talking.

How It Works

USSD sessions are stateful, menu-based interactions. The customer dials a short code (e.g., *384*123#), and Tavio responds with a menu. Each selection navigates deeper into the conversation tree.

Session-based: Each dial creates a session that persists until the user ends it or it times out
Menu navigation: Responses prefixed with CON continue the session; END terminates it
182 character limit per screen (carrier enforced)

Webhook URL

USSD Webhook

text

https://bankmind.aihookd.site/api/channels/ussd

Set this as your USSD callback URL in the Africa's Talking dashboard under your USSD service code.

Required Credentials

api_key	Africa's Talking API key
username	AT username (use "sandbox" for testing)
service_code	Your registered USSD code (e.g., 384123#)

Session Management

Africa's Talking sends a sessionId with each request. Tavio uses this to maintain conversation context across menu selections.

Inbound USSD request

json

{
  "sessionId": "ATUid_abc123",
  "phoneNumber": "+254712345678",
  "serviceCode": "*384*123#",
  "text": ""
}

The text field contains the user's input history separated by *. An empty string means the session just started.

Response Format

USSD responses are plain text prefixed with CON or END:

Menu response (continues session)

text

CON Welcome to BankMind
1. Check Balance
2. Mini Statement
3. Send Money
0. Exit

End response (terminates session)

text

END Your balance is KES 15,420.00
Thank you for banking with us.

Menu Tree Navigation

Tavio's USSD adapter supports dynamic menu trees. The AI engine generates menu options based on the customer's context and selection history, allowing natural conversation flow within the constraints of USSD's text-based interface.

AI responses are capped at 130 tokens to stay within the 182-character screen limit after menu formatting.

How It Works

USSD sessions are stateful, menu-based interactions. The customer dials a short code (e.g., *384*123#), and Tavio responds with a menu. Each selection navigates deeper into the conversation tree.

Session-based: Each dial creates a session that persists until the user ends it or it times out

Menu navigation: Responses prefixed with CON continue the session; END terminates it

182 character limit per screen (carrier enforced)

Session Management

Africa's Talking sends a sessionId with each request. Tavio uses this to maintain conversation context across menu selections.

Inbound USSD request

json

{
  "sessionId": "ATUid_abc123",
  "phoneNumber": "+254712345678",
  "serviceCode": "*384*123#",
  "text": ""
}

The text field contains the user's input history separated by *. An empty string means the session just started.

Menu Tree Navigation

AI responses are capped at 130 tokens to stay within the 182-character screen limit after menu formatting.