Key Takeaways
- USSD request limits on an Android SMS gateway are handset session, operator menu, and owned-device rules — not extra SMS credits we sell.
- POST /ussd returns Pending; the phone dials later. Poll GET /ussd/{id} or ussd.response webhook.
- deviceId must be owned by the account, not merely shared.
- Do not invent session-tree fields. OpenAPI wins.
- 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.
Android SMS gateway USSD request limits bite teams who treat *123# like a fast GET. The phone has to dial. The operator has to answer. The device must be yours. This is not a rewrite of the USSD feature page.
Service pricing is based on device count and total SMS sent through the gateway. Pillar: USSD gateway. Contract: API docs.
If you fire USSD in a tight loop, you are not checking balance. You are training the operator to hate that SIM.
USSD is not an SMS send
Different API, different radio. Balance checks, prepaid packs, and some bank menus live here. OTP still belongs on SMS. 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.
Limit table
| Limit | Symptom | What to do |
|---|---|---|
| Shared deviceId | Rejected / no dial | Own the handset on the account |
| Pending ignored | “API returned nothing” | Poll GET /ussd/id or ussd.response |
| Phone asleep | Queue never dials | OEM exemption, spare device |
| Menu storm | Operator throttle | Backoff; named owner for balance jobs |
| Invented session API | Client 4xx | Only documented fields |
POST /ussd and Pending
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.Owned deviceId
Pairing lives in setup. A borrowed phone that is only “shared” in the UI is not enough for this call.
Menus, sessions, operators
Trees differ by country and prepaid brand. Do not hard-code a Grameenphone menu as a global constant. Webhook event ussd.response is listed with other events in OpenAPI. Webhooks.
Checklist
- Owned deviceId in the body.
- Pending handling written.
- No tight USSD loop on the OTP SIM.
- OEM exemptions on.
- Fields confirmed in docs the day you ship.
Next steps
Pair via downloads, run one *# canary you actually use with that operator, then subscribe to the response event.
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
- Android SMS gateway product guideDefinition, product, and how to buy
