Key Takeaways
- USSD on an Android gateway is a session with the operator (*123# class), not a second SMS API.
- Codes, menus, and whether balance checks work are SIM- and operator-specific. There is no universal *# catalog we ship.
- Keep USSD off the OTP radio when you can. A stuck menu session is a different failure than a missing login code.
- The handset must be on the mobile network. Wi-Fi-only pairing will not complete a USSD session.
- Priced by devices and SMS send volume. You use your own phone and operator SMS credit. USSD does not include operator airtime; some codes still cost.
What USSD is on this path
Product: USSD gateway. Unstructured Supplementary Service Data is a session with the HLR/SMSC world of the operator — balance, bundles, some prepaid menus. It is not SMS, not MMS, not a loophole around consent for bulk. Hub: how an Android SMS gateway works.
If your “USSD integration” is scraping a menu to spam 10,000 numbers, you do not have a gateway use case. You have an abuse case we will not help with.
USSD vs SMS vs STK
| Channel | For | Not for |
|---|---|---|
| SMS | OTP, alerts, consented promo | Interactive operator menus |
| USSD | Balance, some account menus | Login codes, marketing blasts |
| SIM toolkit | Operator applets on the SIM | Our control plane |
Balance and menus are operator-owned
Jazz, Telkomsel, AT&T, and Grameenphone do not share a code list. Use the sleeve, the operator site, or a staff canary. GSM Association context: GSMA. We do not publish a global *# encyclopedia.
Set up USSD requests
- Read the USSD feature page. Confirm the product surface. Do not copy a random GitHub USSD snippet against our API.
- Use a phone on mobile data / GSM. USSD rides the operator session. Wi-Fi-only is the wrong network.
- Grant whatever the app prompts. Phone/call-related permissions differ by Android version. Permission-denied USSD looks like a hang.
- Canary the real balance code. The code printed on the SIM sleeve for that operator. Parse the text; do not assume a number format.
- Timeout and lockout policy. Operators rate-limit USSD. Do not poll *123# every ten seconds from a worker.
- Keep it off the auth SIM if you poll. Balance automation competing with OTP is a self-inflicted outage.
Pairing: device setup. Permission issues: permission denied. API: SMS API documentation.
USSD is not an OTP channel
Users expect a text. Retriever APIs expect a text. OTP verification stays SMS. Isolate radios: multi-device.
Session timeouts and OEM
Overlay screens eat the USSD dialog. Accessibility services and second-skin launchers break sessions. Canary on the production OEM, not a Pixel in HQ.
Cost shape
Service pricing is based on device count and total SMS sent through the gateway. You need a working Android phone with a SIM and SMS credit from your mobile operator. Operator message costs are yours—we do not sell carrier SMS balance. Some USSD codes are billed by the operator. Free is 300 SMS lifetime for SMS canaries — do not assume USSD is unmetered on the carrier. Paid from $19/month. Device and SMS volume pricing.
Next steps
GSM-connected phone, real operator code, polite timeout, USSD off the OTP SIM. Then read the feature page for the product surface.
Related product pages
Jump to the live product docs for this topic—not another long-form article.
- USSD balance and menu automationOperator USSD codes
- SMS API documentationLive endpoint reference
- device and SMS volume pricingPlans and allowances
- device setup guidePair and go live
