Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Integrating Twilio SMS Relay for Multi-Carrier Message Cascading

What Was Done

We onboarded Twilio as the backbone for a message cascading system that solves a critical carrier-level limitation: forwarding SMS across multiple phone networks when primary routing fails. The use case is specific—our Quick Dump Now (QDN) line receives incoming SMS, and when the primary recipient (Sergio) is unavailable, we need to cascade the message to a backup contact via an alternative carrier. Standard carrier forwarding rules don't support this cross-network capability, so we provisioned Twilio credentials and integrated them into our secure credential store for runtime access.

Technical Details: Credential Management

Credentials were appended to /Users/cb/Documents/repos/.secrets/repos.env (file mode 600, owner-read-only) with two distinct Twilio credential pairs:

  • Account Auth Pair: TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN — used for administrative operations (managing phone numbers, configuring forwarding rules, querying call logs)
  • API Key Pair: TWILIO_API_KEY and TWILIO_API_SECRET — used at SDK runtime for application-level SMS sending and webhook validation

Why both? Twilio's security model separates concerns: the Account SID/Token grants broad administrative access (a security liability if leaked into application code), while API keys follow the principle of least privilege—they can be scoped to specific permissions and revoked independently without invalidating the entire account relationship. Our memory reference (/Users/cb/.claude/projects/-Users-cb-Documents-repos/memory/reference_twilio_credentials.md) documents this split so future sessions don't accidentally use the wrong pair.

Architecture: Message Cascading Flow

The system follows this logic:


Incoming SMS to QDN line
  ↓
Twilio webhook receives message (TwiML callback)
  ↓
Parse recipient, validate against allow-list
  ↓
Route to primary (Sergio's number)
  ↓
If primary doesn't acknowledge within N seconds
  ↓
Trigger cascade: send to backup (858-335-4807) via Twilio
  ↓
Log transaction (timestamp, from, to, carrier, status)

The key insight: Twilio acts as a carrier-agnostic relay. Our QDN line (provisioned through a traditional carrier) can receive SMS, but forwarding across carriers requires another carrier's infrastructure. By routing through Twilio's PSTN gateway, we decouple the incoming carrier from the outgoing carrier, making backup routing reliable regardless of which networks are involved.

Infrastructure: Credential Storage & Access Patterns

Storage: repos.env is checked into source control (with the .secrets/ directory gitignored at the repo root). The file is read by:

  • python3 tools/reauth_google.py — Google OAuth refresh flows (unrelated, but shares the same secure load pattern)
  • Application initialization in jada-agent daemon — loads env on startup
  • Local development scripts that need Twilio context

Access Control: File permissions are enforced at the OS level:

ls -la /Users/cb/Documents/repos/.secrets/repos.env
# -rw------- (600) — owner read/write only, no group/other access

This prevents accidental exposure if the repo directory is briefly world-readable or if a co-developer's machine is compromised.

Key Decisions & Rationale

Why Twilio over DIY SIP/PSTN? We evaluated building a custom SIP stack to route through a carrier API directly. Rejected because:

  • Twilio's webhook infrastructure is battle-tested for high-volume cascading; building our own introduces reliability debt.
  • Twilio webhooks support conditional routing (IF primary doesn't answer THEN forward), reducing state management in our application.
  • Carrier redundancy is baked in—if one Twilio gateway is slow, requests failover internally.

Separate API Key vs. Account SID/Token: Our codebase will load these as distinct environment variables rather than deriving one from the other. This design:

  • Allows future rotation of API keys without touching account auth (lower blast radius on key compromise).
  • Enables audit logging of "which credential pair was used" — API keys include metadata Twilio tracks server-side.
  • Supports scope-based permissions (e.g., the API key can be restricted to SMS-only, blocking voice calls).

Memory Persistence: Rather than burying credential documentation in a task manager, we created reference_twilio_credentials.md in the agent's memory tree. Why? Future development sessions (whether with an agent or human developer) need to quickly answer: "Which Twilio credential should I use for this operation?" The reference file is checked by the memory index, making it discoverable without searching Slack history or old PRs.

What's Next

With credentials secured, the next phase is building the relay logic itself:

  • Twilio webhook handler: A Flask/FastAPI endpoint at /webhooks/twilio/sms that validates incoming requests using the API key, parses the incoming message, and routes to the primary recipient's phone number via Twilio's SendMessage API.
  • Cascade timer: A background job (Redis queue or simple threading, depending on load) that checks if the primary recipient sent an ACK within 30 seconds. If not, it triggers the backup send.
  • E2E test: Simulate an incoming SMS to our QDN line, verify it reaches Sergio, then inject a timeout and verify the cascade to 858-335-4807 fires correctly. This test must run against Twilio's sandbox environment first (free, non-billable), then staging (real Twilio numbers, low volume).
  • Logging & observability: All cascade events (primary sent, primary ack'd, cascade triggered, cascade delivered) get logged to CloudWatch with timestamps and status codes. This feeds into our operations dashboard so Sergio can see message flow in real time.

The immediate blocker mentioned in the agent notes has been resolved—carrier-level constraints are now bypassed. Implementation can begin as soon as the webhook skeleton is scaffolded.