Key Takeaways
- Two-way inbox API usage is how you read inbound SMS that landed on your Android SIM — not a rented two-way long code.
- Live list/filter fields live in Developer Center; this page is failure modes.
- Webhooks beat polling for STOP and OTP replies. Polling misses while the device is Dozing.
- Honor STOP on promo. OTP replies are a different lane.
- Inbox does not work if the gateway app cannot receive SMS (permissions, dual-SIM default).
- You bring the phone and operator credit. We meter devices and send volume — inbound is not a third SKU.
Inbox is inbound on a SIM you hold
Android SMS gateway two-way inbox API usage is pulling (or receiving) messages that hit the SIM in a paired phone: STOP, YES, OTP paste-backs, support texts. It is not a hosted inbox on a rented number. The MSISDN on the envelope is the one in the tray.
Product: two-way SMS. Auto-reply / STOP: auto-reply. Live fields: Developer Center— this spoke does not mirror query params.
“If the device cannot receive, your inbox API is a pretty empty array.”
API shapes (conceptual)
| Need | Typical shape | Watch for |
|---|---|---|
| List recent inbound | Authenticated GET, cursor/page | Do not poll every 200ms |
| Push on arrival | Webhook POST | HMAC + HTTPS |
| Mark handled | Idempotent ack | Duplicate STOP processing |
| Filter by SIM | Device / slot id | Dual-SIM default SMS app |
| OTP reply | Same as inbound SMS | Do not log full bodies in Slack |
Poll vs webhook
Polling while the phone sleeps returns stale. Prefer webhooks. Webhook guide, webhook best practices.
STOP and YES/NO
Promo inbox must suppress that MSISDN. Reservation YES/NO is not an opt-out. Acceptable use. External: CTIA messaging principles.
The phone must stay awake
Notification access, default SMS role, dual-SIM “send from SIM 2 / receive on SIM 1” confusion. Device offline KB.
Cost
You still buy operator credit. Some packs bill MO separately — that is the carrier, not a gateway inbound SKU. Platform fee is devices + SMS sent. Pricing.
Checklist
- Receive permission + default SMS path verified on the slot you think you own.
- Webhook HMAC before polling in production.
- STOP handler idempotent.
- OTP bodies not in shared chat.
- Canary inbound from a staff phone.
Next steps
Two-way SMS, setup, Developer Center.
Related product pages
Jump to the live product docs for this topic—not another long-form article.
- two-way SMS inboxReplies on your SIM
- SMS auto-reply and STOP keywordsOpt-out and keywords
- SMS API documentationLive endpoint reference
- device and SMS volume pricingPlans and allowances
