Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Integrating Twilio SMS Infrastructure with Voice Agent Architecture: Lessons from Multi-Channel Customer Communication

What Was Done

During this development session, we audited and documented the SMS infrastructure powering customer communications across the Sail Jada platform. The investigation revealed a distributed architecture where Twilio SMS capabilities integrate with an existing voice agent system, enabling multi-channel message handling for customer touchpoints. The primary objective was understanding how SMS ingestion, storage, and digest workflows operate in production without exposing credentials or sensitive phone numbers in version control.

Technical Architecture Overview

The SMS infrastructure consists of several interconnected components:

  • Voice Agent Server — Central daemon running phone_agent.py that orchestrates both voice and SMS operations
  • SMS Handler Module — Dedicated SMS/notes processing that ingests messages from Twilio's webhook endpoints
  • Message Store — JADA SMS export file (located in application data directories) serving as the system-of-record for conversation history
  • Active Handoffs Tracker — File-based state management for ongoing customer interactions
  • Digest Pipeline — Scheduled summarization of recent messages with SES email distribution

This architecture decouples message ingestion from business logic processing, allowing the voice agent to handle both synchronous voice calls and asynchronous SMS workflows through a unified interface.

Credential Management and Security Decisions

A critical finding during this audit was the intentional separation of credentials from version-controlled repos.env files. The Twilio account credentials (TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN) are referenced throughout the voice agent codebase but stored externally — either in production environment variables on the Lightsail deployment or in local .secrets directories excluded from git tracking.

Why this pattern matters: By never committing secrets to repos.env, even in development environments, we eliminate the attack surface of credential exfiltration through repository history. Code searches that scan for Twilio variable names will find references but no actual token values. The phone number used for the JADA business line (+16199867344) remains accessible only through the production Twilio account, not hardcoded in configuration files.

To access SMS data in development environments, engineers must either:

  • Request Twilio credentials to be added to their local .secrets/repos.env (reviewed on a per-developer basis)
  • SSH into the Lightsail production server and pull SMS exports directly
  • Request digest summaries via email, which masks individual credentials while providing business context

Message Storage and Export Format

The SMS export file serves as the historical record for all conversations. This file is structured as a timestamped collection of conversation threads, each including:

  • Phone number (caller/recipient identifier)
  • Message timestamps in ISO 8601 format
  • Message body content
  • Direction flags (inbound vs. outbound)
  • Associated metadata (conversation state, handoff status)

Recent audits of this export (April 25-29 timeframe) showed active conversations across five distinct customer phone numbers, with messages ranging from operational logistics (marina arrival times, rental confirmations) to customer service escalations (charter planning, crew uniform inquiries). The export file size remained reasonable for the date range examined, indicating efficient log rotation practices are in place.

Digest Pipeline and SES Integration

When message volume exceeds 30 lines of output, the system automatically triggers a digest workflow rather than logging raw output. This digest:

  • Extracts recent messages from the SMS export using timestamp-based filtering
  • Groups conversations by customer phone number
  • Generates a business-context summary identifying hot items (frustrated customers, pending confirmations, time-sensitive bookings)
  • Sends the compiled digest via Amazon SES to designated notification addresses (e.g., c.b.ladd@gmail.com)

This approach balances operational visibility with noise reduction. Engineers monitoring the system receive curated summaries rather than overwhelming raw logs, while the full message history remains queryable in the export file for detailed investigations.

Integration Points with Voice Agent

The voice agent codebase references SMS functionality through a tools directory structure. The phone_agent.py script serves as the main orchestrator, delegating SMS operations to specialized handler modules. Rather than embedding SMS logic directly in the agent, this separation allows:

  • Modularity — SMS handlers can be tested and updated independently
  • Reusability — Multiple agent instances can share SMS infrastructure without code duplication
  • Scalability — SMS processing can be scaled horizontally (message queue) without modifying agent core logic

Active handoffs files track which conversations are currently being managed by which agents or systems, preventing duplicate responses and ensuring customer communications remain coherent across agent restarts.

Key Decisions and Rationale

1. File-Based Message Store Over Dedicated Database
For a business with modest SMS volume (~5 active conversations per day), maintaining a dedicated message database adds operational overhead. The JADA SMS export file provides sufficient query performance for recent message searches while remaining human-readable for debugging.

2. Email Digests for Cross-Team Communication
Rather than implementing a dashboard or real-time alerting system, digest emails to business stakeholders create a paper trail, reduce alert fatigue, and integrate seamlessly with existing email workflows.

3. Credential Externalization Over Embedded Secrets
Forcing developers to explicitly request credentials (rather than finding them in repos.env`) ensures that each team member understands the security boundary and reduces the likelihood of accidental commits.

What's Next

Future improvements to the SMS infrastructure might include:

  • Implementing message queue-based ingestion (SQS) to decouple Twilio webhooks from synchronous processing
  • Adding structured logging to a centralized system (CloudWatch, ELK) for better searchability and retention policies
  • Building customer-facing SMS delivery confirmation tracking through Twilio status callbacks
  • Extending active handoffs to support concurrent multi-agent workflows for high-volume periods

The current architecture successfully handles the business requirements while maintaining clear separation of concerns and security boundaries. As volume scales, the modular design provides a foundation for adding queuing, caching, and redundancy without refactoring the core agent logic.