USSD Simulation

Dial and step through a menu from the API, no handset or carrier integration required.

The simulate endpoint drives a live USSD session against your configured codes and menus. It is the fastest way to verify a menu tree or a callback handler before you register the URLs with a carrier.

Simulate a session

POST/api/v1/ussd/simulate

Parameters

service_codereq

string

USSD code to dial (e.g. *657#)

session_idreq

string

Arbitrary session identifier (e.g. 'test-001')

ussd_string

string

Subscriber input. Empty or omitted for the first dial.

network

string

Simulated network (default: safaricom)

First dial, omit ussd_string to receive the root screen. Reuse the same session_id across the whole session:

curl -X POST "https://timisha-solutions-api.salamu.co.ke/api/v1/ussd/simulate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "service_code": "*657#",
  "session_id": "test-001"
}'

Step forward by sending the accumulated input as ussd_string, here the subscriber selects option 1:

curl -X POST "https://timisha-solutions-api.salamu.co.ke/api/v1/ussd/simulate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "service_code": "*657#",
  "session_id": "test-001",
  "ussd_string": "*657*1#"
}'

The response returns the screen text and whether the session has ended. end_session: false means the platform expects further input.

200: OK

{
  "success": true,
  "data": {
    "response": "CON Acme Services\n1. Check balance\n2. Buy data\n0. Exit",
    "end_session": false
  }
}

CON vs END

The response text mirrors what a carrier receives, CON continues the session and prompts for more input, END terminates it. See USSD webhooks for the live carrier contract.