Relevant source files

The following files were used as context for generating this wiki page: - [convex/http.ts](https://github.com/soderalohastrom/go-happy-cab-demo/blob/main/convex/http.ts) - [docs-archive/TWILIO_WEBHOOK_SETUP.md](https://github.com/soderalohastrom/go-happy-cab-demo/blob/main/docs-archive/TWILIO_WEBHOOK_SETUP.md) - [docs-archive/SMS-docs/PRD_SMS_CONVERSATIONS.md](https://github.com/soderalohastrom/go-happy-cab-demo/blob/main/docs-archive/SMS-docs/PRD_SMS_CONVERSATIONS.md) - [convex/AGENTS.md](https://github.com/soderalohastrom/go-happy-cab-demo/blob/main/convex/AGENTS.md) - [docs-archive/SMS-docs/AGENT1_PROMPT_BACKEND_CONVERSATIONS.md](https://github.com/soderalohastrom/go-happy-cab-demo/blob/main/docs-archive/SMS-docs/AGENT1_PROMPT_BACKEND_CONVERSATIONS.md) - [docs-archive/TWILIO_INTEGRATION_PLAN_12_5.md](https://github.com/soderalohastrom/go-happy-cab-demo/blob/main/docs-archive/TWILIO_INTEGRATION_PLAN_12_5.md)

# Twilio Webhooks & Event Handlers The Twilio Webhooks and Event Handlers system provides the critical link between the Go Happy Cab Convex backend and the Twilio messaging infrastructure. It enables real-time tracking of SMS delivery statuses and the ingestion of inbound messages from parents and drivers. By exposing specific HTTP endpoints, the system ensures that the dispatch application remains synchronized with carrier-level events, providing dispatchers with immediate visibility into communication flows. The system handles three primary categories of events: delivery status updates (sent, delivered, failed), inbound 1:1 SMS messages (replies), and group conversation events via the Twilio Conversations API. It also implements automated keyword handling for regulatory compliance, such as opt-out requests using standard CTIA keywords. Sources: [convex/http.ts:1-12](), [docs-archive/TWILIO_WEBHOOK_SETUP.md:1-10]() ## Architecture and Data Flow The architecture relies on Convex HTTP actions to route incoming POST requests from Twilio to the appropriate backend mutations. When a webhook is triggered, the system parses form-encoded or JSON data, identifies the relevant message or conversation record in the database, and updates its state or creates new inbound records. ### Webhook Event Lifecycle The following diagram illustrates how an outbound message triggers a status callback, and how an inbound message is processed through the system. ```mermaid flowchart TD subgraph Twilio_Cloud T_OUT[Outbound SMS] T_IN[Inbound SMS] T_CONV[Group Event] end subgraph Convex_Backend H_STATUS[POST /twilio/status] H_INBOUND[POST /twilio/inbound] H_CONVERSATIONS[POST /twilio/conversations] M_UPDATE[Update SMS Status] M_CREATE[Create Inbound SMS] M_GROUP[Handle Group Msg] DB[(smsMessages Table)] end T_OUT -- Status Callback --> H_STATUS T_IN -- Webhook --> H_INBOUND T_CONV -- Webhook --> H_CONVERSATIONS H_STATUS --> M_UPDATE H_INBOUND -- Normalize/Keyword --> M_CREATE H_CONVERSATIONS --> M_GROUP M_UPDATE --> DB M_CREATE --> DB M_GROUP --> DB ``` Sources: [convex/AGENTS.md:92-108](), [convex/http.ts:15-18]() ## Endpoint Specifications The system exposes three main endpoints through the `http.ts` router. Each endpoint is designed to respond with a 200 OK status to Twilio to prevent unnecessary retries, even if internal processing encounters a non-critical error. | Endpoint | Method | Data Format | Purpose | | :--- | :--- | :--- | :--- | | `/twilio/status` | POST | Form-Encoded | Tracks delivery lifecycle (queued, sent, delivered, failed). | | `/twilio/inbound` | POST | Form-Encoded | Processes 1:1 replies and CTIA keywords (STOP/START/HELP). | | `/twilio/conversations` | POST | JSON/Form | Manages group threading events from Twilio Conversations API. | Sources: [docs-archive/TWILIO_WEBHOOK_SETUP.md:12-20](), [convex/http.ts:182-192]() ### Delivery Status Tracking (`/twilio/status`) This handler receives updates for all SMS sent via the Messaging Service. It maps Twilio's internal statuses (accepted, queued, sending, sent, delivered, undelivered, failed) to the application's local message status enum. * **Key Logic:** It identifies the existing record using `api.smsMessages.getByTwilioSid` and executes an `updateStatus` mutation to record the final state and any error codes provided by the carrier. * **Parameters:** `MessageSid`, `MessageStatus`, `ErrorCode`, and `ErrorMessage`. Sources: [convex/http.ts:73-155](), [docs-archive/TWILIO_WEBHOOK_SETUP.md:79-85]() ## Inbound SMS and Keyword Handling The `/twilio/inbound` endpoint handles direct replies. Before creating a 1:1 message record, the system uses a 5-minute time-window heuristic to check if the sender is part of a recent group conversation. This prevents "silent message drop" bugs where a message intended for a group might accidentally trigger a separate 1:1 thread. ### Compliance Keywords The system automatically responds to specific keywords to comply with CTIA and TCPA regulations. | Keyword Category | Keywords | System Action | Auto-Reply Message | | :--- | :--- | :--- | :--- | | **STOP** | STOP, CANCEL, UNSUBSCRIBE, QUIT, END | Adds phone to `optouts` table. | "You have been unsubscribed..." | | **START** | START, SUBSCRIBE, YES, UNSTOP | Removes phone from `optouts` table. | "You have been resubscribed..." | | **HELP** | HELP, INFO | Returns support contact details. | "Go Happy Cab: For support, call..." | Sources: [convex/http.ts:21-28](), [convex/http.ts:311-340]() ### Inbound Processing Flow ```mermaid sequenceDiagram participant T as Twilio participant H as http.ts (Inbound) participant C as Conversations Query participant M as smsMessages Mutation participant DB as Database T->>H: POST /twilio/inbound (From, Body) H->>C: isRecentGroupMessage(phone) alt Is Recent Group Message C-->>H: true H-->>T: 200 OK (Empty TwiML) else Is 1:1 Message C-->>H: false H->>M: createInbound(from, body) M->>DB: Insert into smsMessages (direction: "inbound") H->>H: detectKeyword(body) H-->>T: 200 OK (Keyword Response TwiML) end ``` Sources: [convex/http.ts:258-300](), [docs-archive/SMS-docs/AGENT1_PROMPT_BACKEND_CONVERSATIONS.md:180-200]() ## Group Conversation Events (`/twilio/conversations`) For multi-party communication, the application uses the Twilio Conversations API. Webhooks sent to this endpoint are typically formatted as JSON. The system specifically listens for the `onMessageAdded` event. * **Filter Logic:** To avoid infinite loops, the system checks the `Author` field of the event. If the author is not "Dispatcher" and looks like a phone number (starting with "+"), it is treated as a participant reply and saved to the `groupMessages` table. * **Data Structure:** The payload contains `ConversationSid`, `MessageSid`, `Body`, and `Author`. Sources: [convex/http.ts:182-243](), [convex/AGENTS.md:109-115]() ## Implementation Details ### TwiML Generation The system uses a helper function to wrap auto-replies in TwiML (Twilio Markup Language) XML. This allows the backend to command Twilio to send a response SMS immediately in the same request-response cycle. ```typescript function generateTwiML(message?: string): string { if (!message) { return ''; } return `${escapeXml(message)}`; } ``` Sources: [convex/http.ts:36-44]() ### Data Normalization All phone numbers received via webhooks are treated as E.164 strings. Mutations like `createInbound` ensure that messages are indexed by `recipientPhone`, enabling the threaded "LIVE" conversation views in the Dispatch App. Sources: [docs-archive/SMS-docs/AGENT1_PROMPT_BACKEND_CONVERSATIONS.md:100-115](), [convex/AGENTS.md:118-124]() ## Summary The Twilio Webhooks and Event Handlers serve as the automated intelligence layer of the Go Happy Cab messaging system. By effectively routing delivery status updates and inbound messages—while strictly adhering to keyword compliance—the system enables a reliable, real-time communication platform for dispatchers to manage special needs transportation safely.