Phone as Gateway: How to Document Runbooks

The difference between a fifteen-minute outage and a three-hour outage is often documentation — not architecture. Teams running an android phone as sms gateway accumulate tribal knowledge about OEM autostart menus, which shelf phone is OTP-critical, and how to drain queues without spamming expired codes. Runbooks capture that knowledge in searchable, step-verified form so on-call engineers who joined last month execute the same recovery as your founder at 02:00. This guide explains how to document runbooks: structure, gateway-specific scenarios, DLR paths, multi-device failover, and honest context about modern docs tooling — without pretending documentation transports SMS.

Series hub: Android phone as SMS 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. Priced by devices and SMS send volume. You use your own phone and operator SMS credit.

On-call at 03:00 should not grep Slack for Xiaomi autostart paths. That is what runbooks are for.

Why runbooks matter

Incidents compress decision quality. Under stress, humans revert to random actions: re-pair QR when Wi-Fi is down, rotate API keys when airtime is zero, flush queues that deliver expired OTP. Runbooks reduce branching errors by pre-deciding order — network before phone, canary before queue drain, failover before factory reset. They also shorten onboarding for support staff who handle "SMS not received" tickets without SSH access to your Laravel workers.

Measured recovery time objectives mean nothing without procedures timed in drills. A runbook nobody opened during the last drill is shelf fiction. Treat runbook authorship as part of incident closure — same priority as code fix when root cause was operational.

Android phone sms gateway operations blend physical world (power, SIM trays, lock screens) and cloud dashboards. Generic IT runbooks miss radio path verification; generic SMS aggregator runbooks miss OEM battery killers. Your runbooks sit in the middle — specific enough to execute, stable enough to review quarterly.

Founders often resist runbooks until the first vacation outage proves the gateway only works when one person remembers Xiaomi autostart paths. Writing runbooks is cheaper than losing OTP revenue for a morning — and cheaper than hiring duplicate senior engineers whose sole job is tribal memory. Start with three scenarios that hurt last quarter; expand the library as incidents teach you new failure modes.

Glossary

Runbook

Step-by-step operational procedure with verification criteria — executable by someone not present at last incident.

Canary SMS

Small test send proving end-to-end delivery after change or recovery; runbooks end with canary pass/fail gates.

RTO

Recovery Time Objective — target minutes from detection to restored send; runbooks should cite measured RTO from drills.

Last-seen

Dashboard timestamp of device control-plane contact; runbooks define stale threshold triggering escalation.

Failover

Traffic shift to secondary gateway device when primary exceeds last-seen threshold — runbook lists exact dashboard clicks or API calls.

DLR

Delivery report confirming carrier handling; runbooks for webhook pipelines include test hooks separate from send path.

Decision tree

Branching if/then section reducing guesswork — online vs offline, send fail vs webhook fail.

Tribal knowledge

Undocumented expertise held by one engineer — runbooks exist to replace it before vacation.

Who reads runbooks

Primary reader: on-call engineer during Sev-2. Secondary: support tier one filtering user reports before escalation. Tertiary: future you six months later who forgot Xiaomi autostart path. Write for primary — numbered steps, no assumed context — but include a one-line symptom summary at top so support links the right doc.

Runbooks are not marketing. Avoid aspirational language; use imperative verbs (Verify, Open, Send, Stop). Each step should answer "what do I click or type next" and "what should I see if healthy."

Runbook structure

Consistent templates beat creative prose. Use the same section order across all gateway runbooks so muscle memory transfers between scenarios.

Gateway-specific sections

Every hardware runbook includes asset tag, shelf location, power path (UPS yes/no), network path (Wi-Fi SSID or mobile data SIM), gateway APK version installed from download the Android gateway app, dashboard device name, and device ID used in API calls. Omitting asset tag guarantees wrong phone unplugged during incident.

Permission and battery exemption steps belong inline — not "see setup guide" without link anchor — because Android updates revert them silently. Post-update runbook appendix lists OEM-specific re-check paths.

Document which SIM slot is active for OTP vs bulk if dual-SIM — slot confusion looks like random deliverability failure in tickets. Include photo of SIM tray label in wiki appendix for night shift. Note prepaid balance check URL or USSD code per operator in RB-AIRTIME-SIM so on-call does not web-search mid-incident.

Queue drain runbooks specify max sends per minute after outage, expired OTP discard policy, and stakeholder comms if backlog clears over multiple hours. Bulk and OTP queues may need different drain policies — one runbook per policy avoids wrong flush behavior.

DLR and webhook runbooks

Delivery reports close the loop for OTP and transactional stacks. When users say "not received" but dashboard shows sent, split runbooks: send path vs webhook path. DLR runbooks document receiver URL, TLS certificate expiry, signature verification, idempotency handling, and test curl using env secrets on bastion — never paste secrets into runbook body; reference secret name.

Live field names and payload examples live in DLR documentation. Runbook links there instead of duplicating JSON that drifts when API evolves. Verification step: canary send → expect webhook within N seconds → log entry with message ID.

Common DLR runbook branches: TLS cert expired (renew and reload nginx), wrong webhook URL in dashboard after deploy, firewall blocking inbound POST, signature mismatch after secret rotation, consumer app down so messages pile in broker — each branch gets explicit steps and rollback. Distinguish delayed DLR from missing DLR — user experience differs; support scripts should match runbook vocabulary.

When webhook pipeline recovers, backlog replay runbook defines order and deduplication — replay storm can duplicate user-visible status updates if idempotency keys ignored. Coordinate with backend team before mass replay; gateway runbook ends at confirmed webhook delivery for canary, backend runbook owns consumer catch-up.

Multi-device procedures

Single-device runbooks fail fleets. Document routing rules: primary device ID, secondary IDs, failover last-seen threshold, whether queue drains on primary before shift, dual-SIM slot per handset. Failover runbook includes stakeholder comms template ("OTP may delay 2–3 min during shift").

Feature reference: multi-device and dual-SIM. Monthly drill step: reboot primary during window, execute failover runbook, measure minutes to canary on secondary — record in runbook version history.

RB-FAILOVER should list dashboard navigation or API calls to confirm routing weights — ambiguous "enable secondary" steps fail at 3am. Include device IDs in runbook metadata block copied from dashboard to avoid typo routing traffic to decommissioned row. After failover, primary recovery runbook defines when to shift back — flapping primary online/offline should not yo-yo routing without hysteresis threshold documented.

Dual-SIM on single phone differs from two phones — runbooks must title clearly RB-DUALSIM-SLOT vs RB-MULTIDEVICE-FAILOVER. Mixing them sends on-call to wrong menu paths. Silver and Gold plans with ten or more devices need RB-ROUTING-UPDATE when adding device twelve — not cloning offline runbook twelve times without index maintenance.

APK reinstall steps

Reinstall runbooks trigger when APK corrupt, wrong sideload, or documented upgrade — not as first response to network blip. Steps: download current APK from official download the Android gateway app, verify checksum if published, uninstall old only when doc requires, install, open, verify autostart, re-pair only if auth errors persist, update device ID in env if re-pair created new row. Never install from messenger attachments or random forums.

Docs tooling context

Teams experimenting with AI-assisted ops may expose runbooks through Model Context Protocol servers so agents retrieve procedures during chat — useful for suggesting the right doc, not for executing shelf work remotely. MCP standardizes how tools fetch context; it does not replace physical unlock of a gateway phone or carrier top-up. Read the spec for integration ideas: Model Context Protocol. SMS transport still flows Android → carrier → recipient; runbooks tell humans what to do on that path.

Templates and examples

Start from scenario table below; expand each row into full template with your asset specifics.

Example verification block (paste into each runbook): "Send canary to +XX internal number via dashboard. Expect delivery within 60s. Confirm DLR webhook received at receiver /health/log. If fail, stop — do not drain production queue."

RB-QUEUE-DRAIN template fields: starting queue depth, max send rate per minute, expired OTP cutoff age, dead-letter destination, stakeholder notify if depth still above X after 60 minutes. RB-APK-REINSTALL template fields: current broken version, target version from Downloads, checksum verified yes/no, re-pair required decision tree after install. Templates reduce blank-page paralysis when authoring first runbook — customize every placeholder before marking v1.0 ready.

Store templates in git docs/runbooks/_templates/ with PR review — same quality bar as code. Wiki transclusion or copy-paste from template repo; avoid orphan Google Doc templates nobody can find at 3am. Link template index from on-call landing page next to pager duty schedule.

Keeping runbooks current

Stale runbooks harm more than none — they train wrong muscle memory. Update within 48 hours after any incident where engineer said "doc was wrong." Quarterly review calendar invite with checklist: APK version, OEM menu paths, device IDs, webhook URLs, failover thresholds, on-call names. Version number in metadata; changelog line per edit.

Service pricing is based on device count and total SMS sent through the gateway. When plan upgrades add devices, update fleet runbooks and routing sections same day — not when first multi-device incident strikes.

Runbook review meeting agenda: read one runbook aloud, execute tabletop without looking at phone, note every ambiguous step, assign owner and due date. Thirty minutes quarterly prevents three-hour outage from one wrong menu path. Track review completion in same tracker as security patch cadence. Link review tickets to wiki page version bump so auditors see process not just static text.

When gateway releases major dashboard UI change, screenshot runbook within one week or mark steps with "UI changed — verify paths" banner until updated. Broken screenshots in runbooks mislead worse than no screenshots — delete obsolete images aggressively. APK release notes from download the Android gateway app should trigger runbook review ticket automatically if you subscribe to release RSS or email list.

Onboarding with runbooks

New engineer week one: execute three runbooks in staging — simulated offline device, webhook failure, queue drain — with mentor sign-off. Support staff: read-only walkthrough of detection sections and when to escalate. Runbooks become training artifacts; gaps found in onboarding feed doc updates.

Record onboarding completion dates in HR or ops tracker — uncertified on-call should not execute RB-FAILOVER alone. Shadow real incident with senior before solo pager shift. Use hub android phone as sms gateway as conceptual reading before hands-on drill; runbooks as drill scripts.

Quarterly refresh training when APK version from download the Android gateway app changes major version — menu paths and permission prompts may shift. Ten-minute lunch-and-learn walking through one updated runbook beats email wall of text nobody reads.

Incident runbook linkage

Incident ticket template fields: runbook name + version used, steps completed, verification pass/fail, measured RTO, doc gap filed yes/no. Postmortem without runbook update repeats next month. Severities affecting OTP login require runbook drill within 30 days if RTO exceeded target.

sms gateway using android phone incidents often cluster: power, permissions, airtime, webhook TLS expiry. Tag tickets with category to prioritize which runbook needs rewrite most urgently.

Sample runbook excerpt

Below is abbreviated RB-DEVICE-OFFLINE v1.2 structure — replace placeholders with your assets.

RB-DEVICE-OFFLINE v1.2 | Owner: ops@company | RTO target: 10 min

Prerequisites: dashboard login, shelf key, Wi-Fi password, canary +1-555-0100

1. Confirm router LAN LED stable (wait 3 min after power if needed)
2. Power on phone ASSET-OTP-01; enter SIM PIN if prompted
3. Verify Wi-Fi connected OR mobile data icon with balance
4. Open recents — Gateway app running within 2 min; if not:
 Samsung: Settings > Apps > Gateway > Battery > Unrestricted
5. Dashboard: device OTP-01 last-seen under 3 min
6. Send canary to +1-555-0100; expect DLR webhook within 60s
7. If fail at step 4-6, do NOT re-pair — escalate RB-SEND-FAIL branch
8. Resume queue drain at rate limit 30/min after canary pass

Rollback: if step 6 fails twice, route traffic to OTP-02 per RB-FAILOVER

Full wiki page expands OEM paths, photos, and links to SMS delivery reports (DLR) verification using env var names only — never paste live secrets into runbook body.

Cross-linking runbooks

Each runbook footer lists related IDs: RB-DEVICE-OFFLINE links RB-FAILOVER, RB-AIRTIME-SIM, RB-QUEUE-DRAIN. Avoid circular prose duplication — one canonical OEM autostart section linked from five runbooks updates once. Hub blog android phone as sms gateway explains concepts; runbooks execute under pressure. When blog updates menu paths, runbook owner receives ticket from docs changelog — assign owner in wiki metadata.

DLR-specific failures always link DLR documentation for payload fields rather than copying JSON. Multi-device procedures link multi-device dual-SIM. Reinstall steps cite download the Android gateway app version pinned in metadata block.

Fleet runbook index

Maintain index table: runbook ID, scenario, last drill date, measured RTO, devices covered. Quarterly review sorts by oldest drill first — stale procedures drill next. Fleet growth from one to ten devices requires RB-ROUTING-UPDATE not ten copies of offline runbook with different asset tags only. Central index lives on wiki landing page searchable by symptom keyword: offline, DLR, airtime, queue, APK, failover.

Service pricing is based on device count and total SMS sent through the gateway. Runbook index should note plan tier device caps so on-call knows whether failover device exists on free tier single device or Gold fleet — wrong assumption wastes minutes paging for secondary phone that was never provisioned.

MCP honest boundaries

Model Context Protocol servers can expose runbook markdown to AI assistants helping on-call search — see MCP specification for tooling architecture. Agents suggest steps; humans unlock phones, press power buttons, top up prepaid SIM at shop kiosk. Do not claim MCP integration replaces runbooks — it indexes them. SMS transport never flows through MCP; conflating docs tooling with message path confuses buyers and engineers alike.

If you build MCP resource for runbooks, version resource URI when runbook semver changes — agents retrieving stale v1.1 during v1.3 incident propagate wrong menu paths. Human verification gate remains mandatory before declaring recovery complete.

Runbook program conclusion

Documenting runbooks for android phone as sms gateway operations is how small teams scale reliability without hiring twenty-four-seven NOC. Structure, verification gates, decision trees, laminated cards, and drill cadence turn hub knowledge into executable steps. Link live product docs for DLR, downloads, and multi-device features instead of duplicating volatile JSON. Priced by devices and SMS send volume. You use your own phone and operator SMS credit. Include operator airtime branches beside platform quota in send-failure trees. MCP and wikis help find docs faster — the modem still needs a human on the shelf when lights blink.

Laminated shelf cards

Wiki depth does not help when router and phone reboot simultaneously and LTE iPad has no VPN. One-page laminated cards next to hardware cover: asset tag, boot order, autostart menu path for that OEM, canary number, escalation phone. Link QR to full wiki for detail — card is execution only. Update card version sticker when menu paths change; outdated card worse than none if engineer trusts wrong path blindly.

Cards for multi-device shelf: primary vs secondary label matching dashboard names; failover threshold minutes written large; reminder that re-pair is last resort. Photo of correct recents-lock gesture on back of card helps new hire more than paragraph describing "lock app in recents."

Support tier runbooks

Tier-one support cannot re-pair devices or edit routing — their runbook is triage: collect message ID, timestamp, user phone, last dashboard status screenshot, confirm single user vs widespread. Branch: widespread → page on-call with device offline runbook; single user → deliverability or user device issue path. Pre-written customer reply snippets reduce improvisation that promises SLA you cannot meet.

Escalation criteria must be explicit: if last-seen stale more than X minutes for OTP product, page immediately; if bulk campaign delayed but OTP healthy, different queue. Support runbooks link to technical runbooks — never duplicate OEM steps in two places without sync ownership.

Versioning and changelog

Semantic version on each runbook: 1.4.0 → menu path fix after Samsung update. Changelog block at top: date, author, what changed, why. Search wiki by scenario title plus version when incident report says "followed runbook v1.2" — know exactly which steps executed. Git-tracked markdown in docs/runbooks/ enables PR review like code; wiki-only shops still need version footer.

Postmortem template

Blameless postmortem ties to runbook gaps: timeline, impact, root cause, what runbook was used, where it failed, doc PR link, drill scheduled date. Template fields: Detection time, mitigation time, RTO measured vs target, user-facing comms sent yes/no, operator airtime vs platform quota confusion contributed yes/no. Close loop only when runbook merged — not when code hotfix deploys.

Recurring root causes without runbook updates indicate process failure. Three SIM airtime outages from missing top-up step in tree means branch addition, not another verbal reminder in standup.

Decision tree example

ASCII decision tree for send failures (expand in wiki with links):

Send failure reported
├─ Dashboard device offline? → Run RB-DEVICE-OFFLINE
├─ Dashboard online?
│  ├─ Stock SMS from phone fails? → RB-AIRTIME-SIM
│  ├─ Stock SMS OK, API fails? → RB-PERMISSIONS-API
│  └─ API OK, no user delivery?
│     ├─ DLR webhook missing? → RB-DLR-WEBHOOK (see /dlr)
│     └─ DLR OK, user claims none? → RB-USER-DELIVERABILITY
└─ Multi-device? → Check routing → RB-FAILOVER

Each leaf maps to one runbook ID. Engineers during incident say which leaf — standup and postmortem share vocabulary. Update tree when new failure mode appears; do not orphan runbooks without tree entry or they rot unused.

Multi-device section references multi-device dual-SIM for routing configuration runbook prerequisites. APK reinstall leaf always cites download the Android gateway app URL — never third-party mirrors in runbook body.

Common mistakes

• Vague steps. "Fix network" vs "Ping 8.8.8.8 from phone browser; if fail toggle Wi-Fi off/on."
• No verification gate. Procedure ends at dashboard green without canary SMS.
• Re-pair as step one. Duplicates devices; exhaust network and permission paths first.
• Secrets in runbook body. Reference env var names only.
• One mega runbook. Split by scenario for searchability.
• Never drilled. Fiction until timed exercise proves RTO.
• Missing rollback. Engineer afraid to act during incident.
• Ignoring operator airtime branch. Wastes hours rotating API keys while SIM empty.

Next steps

Pick top three incidents from last quarter — write runbooks this week using template above. Hub: Android phone as SMS gateway. Link live DLR fields in DLR docs, fleet behavior in multi-device dual-SIM, APK steps in download the Android gateway app. Schedule first drill before next vacation — tribal knowledge fails when the expert is offline and the runbook is blank.

Good runbooks respect Priced by devices and SMS send volume. You use your own phone and operator SMS credit. — operator top-up and platform quota appear where send failures branch. Document for humans on the shelf; index for agents if MCP helps your team find the right page faster. The modem still needs a human to verify autostart when the lights blink.

Assign runbook owner role in team RACI — not everyone edits, one person merges doc PRs and schedules drills. Owner reviews hub blog updates monthly for drift against runbook OEM paths. When 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. confuses on-call during airtime incidents, add clarifying sentence to RB-AIRTIME-SIM footer — free tier 300 SMS lifetime is platform quota, not operator balance. Paid from $19/month adds allowance but still not carrier credit. Precision in runbooks prevents hour-long detours.

Runbook maturity model: Level 1 tribal knowledge; Level 2 wiki exists; Level 3 drilled quarterly; Level 4 postmortem always updates doc; Level 5 support tier executes triage runbooks without engineering for known branches. Most teams stall at Level 2 — push to Level 3 this month with one timed RB-DEVICE-OFFLINE drill. Measure minutes; compare to OTP SLA; file gaps same day.

Runbook anti-patterns to delete on sight: copy-pasted aggregator cloud runbooks with zero OEM steps; runbooks that start with re-pair QR; runbooks without owner field; runbooks last reviewed before last Android major upgrade on shelf phone. Audit wiki quarterly for these anti-patterns and archive obsolete docs with redirect banner to replacement ID — stale search results waste incident minutes. Connect runbook program to business continuity: if OTP revenue depends on one shelf phone, runbooks are as critical as database backups — drill both on same calendar quarter.

Export runbook PDF to shelf binder only after wiki version matches — dated PDFs drift. Prefer QR on laminated card linking to live wiki URL with version query param. When SMS delivery reports (DLR) or multi-device docs update, runbook owner receives automated changelog if wiki supports subscribe — otherwise calendar reminder. Document runbooks are living ops code — version, review, drill, improve — until android phone as sms gateway fleet runs without heroics on vacation weeks.

Celebrate runbook improvements in team retros — visible wins encourage contribution. When engineer fixes outage and updates RB-DEVICE-OFFLINE same day, mention in retro. Culture of documentation reduces repeat incidents more than blame. Link new runbooks from hub android phone as sms gateway internal wiki mirror if you maintain one — single discoverability path for humans and future MCP indexing layers.

Runbook quality metric: percentage of last five incidents where executed runbook matched actual root cause path without ad-hoc steps invented mid-incident. Target above eighty percent; below sixty means doc program needs investment before next fleet expansion. Priced by devices and SMS send volume. You use your own phone and operator SMS credit. Runbooks should mention both platform quota and operator airtime in RB-AIRTIME-SIM — confusion there drives false escalations to API team while SIM sits empty.

Start writing RB-DEVICE-OFFLINE tonight — one page, your asset tag, your canary number, your OEM menu path. Perfection later; executable steps now. Link download the Android gateway app, SMS delivery reports (DLR), and multi-device from footer. Drill it once; measure RTO; improve. That loop is how runbook programs compound reliability for android phone as sms gateway operations without enterprise NOC headcount. Document first; drill second; vacation third. Empty runbook shelf equals single-person bus factor — write before you need it at 3am on a Sunday. The hub series explains why; your runbooks explain how for your shelf, your SIMs, your on-call names. Glossary terms above align support and engineering vocabulary during incidents — use them in tickets consistently. Review this article quarterly alongside your runbook index; archive superseded pages rather than leaving contradictory OEM paths searchable in wiki search results during incidents. Good runbooks are never finished — only current. Keep drilling always.