USSD Gateway: Run USSD Codes from an API
A USSD gateway lets you trigger session-based operator codes on your own Android phone and read the response back through an API — useful for balance checks, plan status, and prepaid self-service before a campaign runs out of credit.
Jump to
→ *121#
← 1 Balance 2 Validity 3 Bundles
→ 1
← Balance BDT 482.00. Valid until 12 Oct.
session closed · no DLR
What to expect technically
If you model USSD like SMS, the integration will surprise you. These are the constraints that hold across operators even when the text strings differ.
| Detail | What to expect |
|---|---|
| Session model | Session-based with a short lifetimeUnlike SMS, there is no store-and-forward queue. The session opens, exchanges text, and closes. |
| Response format | Plain text returned by the operatorLayout, wording, and language are entirely operator-defined and can change without notice. |
| Menu interaction | Some codes return a numbered menu that needs a follow-up replyTreat multi-step USSD as a short conversation, not a single request. |
| SIM requirements | Active SIM with radio signal on the chosen deviceNo signal, airplane mode, or a locked SIM will fail the session before any text arrives. |
| Concurrency | One USSD session at a time per SIMQueue balance checks; do not fire parallel sessions against the same subscription. |
| Delivery reports | None — USSD has no DLR conceptYou get a session response or a timeout. There is no carrier delivery receipt like SMS. |
Plan your client around timeouts and opaque text. The gateway can open the session and return whatever the network sent; it cannot normalise operator menus into a stable schema. That is why caching and soft failure matter more than perfect parsers.
Running a USSD request end to end
Six steps from confirming the code on the keypad to storing a result your campaign logic can trust.
- 01
Confirm the code with your operator
Look up the exact USSD string for the action you need — balance, validity, bundle status, or a self-service menu. Codes differ by operator and country. Test the same string on the handset keypad once before automating it. - 02
Pick the device and SIM
Choose which Android phone and which subscription should run the session. On a dual SIM handset, that means naming the right subscription so the balance you read belongs to the SIM that will send campaign traffic. - 03
Submit the USSD request
Send the code through the panel or the API. The gateway opens a session on the device and waits for the operator network to return text. - 04
Read the session response
Capture the plain-text reply. For a simple balance check this is often a single string with remaining credit and validity. Do not assume fixed field positions — operators rearrange wording regularly. - 05
Send a menu selection if needed
If the operator returns a numbered menu, submit the next digit or short reply in the same session. Keep timeouts short; abandoned menus close on the network side. - 06
Record the parsed result
Store the raw response plus any fields you extract. Cache the result and timestamp so campaign logic can check credit without opening a new session on every send.
Calling USSD from the product surface
USSD is POST /api/v1/ussd with JSON { request, deviceId }. The device must be owned by the account (not merely shared). Confirm fields in the API reference. Poll GET /ussd/{id} or subscribe to ussd.response.
| Detail | What to expect |
|---|---|
| Device | Named Android + SIMPin dual-SIM sessions to the subscription that holds campaign credit. |
| Code | Operator string such as *123#Confirm on the keypad first. |
| Follow-up | Menu digit in the same sessionIdle menus close on the network side. |
| Parse | Defensive regex + raw logWording and language change without notice. |
curl -X POST "https://app.sms-gateway.app/api/v1/ussd" \
-H "Authorization: Bearer $SMS_GATEWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"request":"*123#","deviceId":123}'
# Response is Pending — the handset dials later. Poll GET https://app.sms-gateway.app/api/v1/ussd/{id}
# or subscribe to webhook event ussd.response.A practical pattern: cron a balance check every few hours per SIM, extract an amount with a loose pattern, write it to your own store, and refuse to start a large send when the cached balance is below a threshold you choose. If parsing fails, alert ops and fall back to a manual keypad check rather than inventing a number.
What teams actually use a USSD gateway for
The failure mode that hurts most is quiet and physical: a prepaid SIM runs out of credit halfway through a campaign. Messages stop leaving the handset, delivery reports start looking like a carrier problem, and someone discovers the empty balance only after customers complain. A scheduled USSD balance check on each campaign SIM catches that before the queue starts.
The same pattern covers validity dates, confirming a data or SMS bundle is still active, reading plan status after a top-up, and triggering a simple operator self-service action that has no web portal. Teams that run spreadsheet bulk SMS across several SIMs usually wire balance polling into the same ops checklist that watches device health on a multi-device dual SIM fleet.
Treat USSD as instrumentation for your send paths, not as a feature you expose live to end users. Poll on a schedule, cache the last known balance and validity, and let campaign logic read the cache.
Can software trigger *123# style codes?
Yes. The USSD gateway runs the code on a connected Android SIM and returns the operator text through the API, so balance and plan checks can sit in a scheduled job instead of a manual keypad session.
Should USSD block a customer login?
No. USSD depends on radio conditions and operator menus that can change. Poll on a schedule, cache the last good reading, and keep customer-facing paths on SMS or your own data store.
How do I parse a balance string safely?
Use a defensive regex for amounts and dates, keep the raw response, and fail soft when the pattern does not match. Operator copy is localised and rearranges without notice.
Does every SIM support the same codes?
No. Codes and response text differ by operator and country. Confirm each string on the handset for that subscription before you automate a fleet.
What USSD is and what a USSD gateway does here
USSD (Unstructured Supplementary Service Data) is a session-based, real-time channel carried by the mobile operator. You know it as short codes like *123# that open a temporary dialogue with the network: balance, validity, bundle purchase, or a self-service menu. There is no store-and-forward. The session lives while the radio exchange is open, then it ends. That is the opposite of SMS, which is queued, delivered later, and can carry a delivery report.
A USSD gateway in this product means the Android SMS gateway triggers that code on a phone you control and returns the operator's text response through the API. You bring the handset, the SIM, and the operator credit. The service fee is based on device count and SMS send volume — not on selling carrier balance. For the network-side behaviour of USSD and related telephony APIs on Android, see Google's TelephonyManager reference.
- 01
A USSD gateway opens a real-time operator session on your Android SIM and returns the plain-text response through the API.
- 02
USSD is session-based with no store-and-forward and no delivery report; timeouts and empty replies are normal failure modes.
- 03
Teams use it to check prepaid balance, validity, and bundle status across a SIM fleet before SMS campaigns start.
- 04
Operator codes and response layouts differ by network and can change without notice — parse defensively and cache results.
- 05
You supply the phone, SIM, and operator credit; service pricing follows device count and total SMS sent.
Limits, failure modes, and operator dependence
USSD reliability is mostly radio and operator behaviour. Design for the cases that show up in production logs.
Timeouts happen when the radio is weak, the network is busy, or the session sits too long on a menu. No-signal and airplane mode fail before any text arrives. A PIN-locked or inactive SIM will not open a session. One session at a time per SIM means parallel balance jobs against the same subscription will collide — serialise them.
There is also no delivery report concept. An empty body is not the same as SMS failure codes you may know from DLR handling. Log the timeout, retry once after a handset sanity check, then escalate. For plan questions, see pricing (device count and SMS volume) or contact support; responses typically arrive within 24-48 hours.
Regional notes where USSD self-service is common
Prepaid markets lean on USSD for day-to-day account management. Codes and languages are local — start from these pages, then confirm on the SIM.
Bangladesh
Prepaid self-service is heavily USSD-driven. Balance and validity strings are often Bangla or mixed Bangla/English, so parsers must tolerate localised wording.
Nigeria
Operators publish different short codes for balance, data bundles, and airtime. Codes that work on one network will fail or open an unrelated menu on another.
India
USSD remains a common prepaid status channel. Dual SIM phones are widespread — always pin the session to the subscription that holds the campaign credit.
Pakistan
Self-service menus and balance checks are operator-specific. Response text may switch language without warning after a network update, so keep raw logs.
More markets sit on the regional SMS gateway hub. Whatever the country, verify each operator code on the physical handset before you trust an automated balance job with campaign traffic.
Related features on the same fleet
These run on the same phones, the same account, and the same REST SMS API— no extra product silos.
Two-Way SMS: Replies on Your Own Number
Keep the conversation on the number you sent from and route replies into your systems.View feature →Bulk SMS from Excel & CSV
Upload a spreadsheet, map your columns, and personalise every message from your own data.View feature →MMS Gateway: Send Picture Messages
Attach an image to a message where your carrier and handset support MMS, straight from the API.View feature →Common questions about USSD requests
Straight answers for teams evaluating this feature for production OTP, bulk, or two-way traffic.
Run ussd requests on your own SIM
Install the Android app, pair a device with operator SMS credit, and test this feature in the panel or over the API. Paid plans are metered by devices and SMS send volume.