Relevant source files

The following files were used as context for generating this wiki page: - [be/whatsapp-bot/init-whatsapp.ts](https://github.com/YosefHayim/ai-google-calendar-assistant/blob/main/be/whatsapp-bot/init-whatsapp.ts) - [be/whatsapp-bot/handlers/message-handler.ts](https://github.com/YosefHayim/ai-google-calendar-assistant/blob/main/be/whatsapp-bot/handlers/message-handler.ts) - [be/whatsapp-bot/services/send-message.ts](https://github.com/YosefHayim/ai-google-calendar-assistant/blob/main/be/whatsapp-bot/services/send-message.ts) - [be/whatsapp-bot/services/user-linking.ts](https://github.com/YosefHayim/ai-google-calendar-assistant/blob/main/be/whatsapp-bot/services/user-linking.ts) - [be/whatsapp-bot/utils/conversation-history.ts](https://github.com/YosefHayim/ai-google-calendar-assistant/blob/main/be/whatsapp-bot/utils/conversation-history.ts) - [be/whatsapp-bot/utils/prompts.ts](https://github.com/YosefHayim/ai-google-calendar-assistant/blob/main/be/whatsapp-bot/utils/prompts.ts) - [be/whatsapp-bot/utils/format-response.ts](https://github.com/YosefHayim/ai-google-calendar-assistant/blob/main/be/whatsapp-bot/utils/format-response.ts) - [be/controllers/whatsapp-controller.ts](https://github.com/YosefHayim/ai-google-calendar-assistant/blob/main/be/controllers/whatsapp-controller.ts) - [be/routes/whatsapp-route.ts](https://github.com/YosefHayim/ai-google-calendar-assistant/blob/main/be/routes/whatsapp-route.ts) - [be/whatsapp-bot/types/index.ts](https://github.com/YosefHayim/ai-google-calendar-assistant/blob/main/be/whatsapp-bot/types/index.ts)

# WhatsApp Bot Integration The WhatsApp Bot Integration provides a conversational interface for users to manage their Google Calendar directly through WhatsApp. This module leverages the WhatsApp Cloud API (Meta) to handle real-time messaging, supporting text and voice interactions. It serves as one of the primary interaction modalities alongside Web Chat and Telegram, sharing a unified context and AI agent logic to ensure a consistent assistant experience across platforms. Sources: [AGENTS.md:9-12](), [be/whatsapp-bot/handlers/message-handler.ts:1-5]() ## System Architecture The integration follows a webhook-based architecture where Meta's servers push events to a specialized endpoint on the backend. The system is divided into route handlers, controllers for webhook processing, services for outbound messaging, and utility modules for conversation state management. ### Data Flow Overview When a user sends a message, it is received by the `whatsapp-controller.ts`, validated, and passed to the `message-handler.ts`. The handler coordinates with the AI orchestrator and various services to generate and send a response. ```mermaid flowchart TD Meta[Meta WhatsApp API] -- Webhook POST --> Routes[WhatsApp Routes] Routes --> Controller[WhatsApp Controller] Controller --> Handler[Message Handler] Handler --> UserLinking[User Linking Service] Handler --> ConvHistory[Conversation History] Handler --> AIAgent[AI Orchestrator Agent] AIAgent --> SendMsg[Send Message Service] SendMsg -- API Request --> Meta ``` The flow ensures that every incoming message is validated, linked to a specific user account, and processed within the context of the user's previous interactions. Sources: [be/controllers/whatsapp-controller.ts:41-80](), [be/whatsapp-bot/handlers/message-handler.ts:258-300]() ## Core Components ### 1. Webhook and Configuration The system uses a verification handshake to establish communication with Meta. Configuration is managed via environment variables including `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_ACCESS_TOKEN`, and `WHATSAPP_VERIFY_TOKEN`. | Parameter | Source File | Description | | :--- | :--- | :--- | | `verifyWebhook` | `whatsapp-controller.ts` | Handles the GET request from Meta to verify the webhook URL. | | `handleWebhook` | `whatsapp-controller.ts` | Processes POST requests containing messages and status updates. | | `isWhatsAppConfigured` | `init-whatsapp.ts` | Validates that all required environment variables are present. | Sources: [be/controllers/whatsapp-controller.ts:19-38](), [be/whatsapp-bot/init-whatsapp.ts:13-21]() ### 2. Message Processing The `message-handler.ts` is the central hub for routing different types of content (text, audio, interactive). It includes a deduplication mechanism using a TTL-based Map to prevent processing the same message ID multiple times. ```mermaid sequenceDiagram participant User participant Handler as Message Handler participant AI as AI Agent participant Meta as WhatsApp API User->>Meta: Sends Text/Voice Meta->>Handler: Webhook Event Handler->>Handler: processIncomingMessage() Handler->>Handler: isDuplicateMessage() Handler->>AI: generateResponse(context) AI-->>Handler: Final Output Handler->>Meta: sendTextMessage() / sendAudioMessage() Meta-->>User: Delivery ``` Sources: [be/whatsapp-bot/handlers/message-handler.ts:46-75](), [be/whatsapp-bot/handlers/message-handler.ts:258-305]() ### 3. User Onboarding and Linking A critical part of the integration is linking the WhatsApp phone number to a system `user_id`. If a user is not linked, they are put through an onboarding flow. * **Welcome:** Introduction to the bot with interactive buttons. * **Email Input:** User provides their email for account lookup/creation. * **OTP Verification:** Secure verification via Supabase Auth OTP. * **Google Auth:** If the account has no calendar linked, the user is directed to a Google OAuth URL. Sources: [be/whatsapp-bot/services/user-linking.ts:124-143](), [be/whatsapp-bot/services/user-linking.ts:245-285]() ## Conversation Management ### State and Persistence Conversation history is stored in Supabase under `conversations` and `conversation_messages` tables. To maintain AI efficiency, the system implements automatic summarization when the context exceeds 1,500 characters or 6 messages. | Feature | Limit / Value | Source File | | :--- | :--- | :--- | | `MAX_CONTEXT_LENGTH` | 1,500 chars | `conversation-history.ts` | | `MAX_MESSAGES_BEFORE_SUMMARIZE` | 6 messages | `conversation-history.ts` | | `MAX_SUMMARY_LENGTH` | 1,000 chars | `conversation-history.ts` | Sources: [be/whatsapp-bot/utils/conversation-history.ts:14-17](), [be/whatsapp-bot/utils/conversation-history.ts:219-245]() ### Prompt Engineering The system builds dynamic prompts that include platform-specific instructions (e.g., "Keep responses concise and mobile-friendly") and the user's persona or personality notes. ```typescript // Example of prompt construction for WhatsApp export const buildAgentPromptWithContext = ( email: string | undefined, message: string, conversationContext?: string, options?: BuildPromptOptions ): string => { // ... adds platform instructions, timestamp, user context, and history parts.push(`\nWhatsApp - Keep responses concise and mobile-friendly.\n`) // ... } ``` Sources: [be/whatsapp-bot/utils/prompts.ts:44-60]() ## Messaging Services Outbound messaging is handled by the `send-message.ts` service, which abstracts the Meta API calls for various message types. ### Supported Message Types * **Text Messages:** Standard text responses with optional preview URLs. * **Media Messages:** Support for Audio (voice notes), Images, and Documents. * **Interactive Messages:** Buttons (Quick Replies) and List Messages for structured user input. * **Template Messages:** Required for initiating conversations outside the 24-hour window. Sources: [be/whatsapp-bot/services/send-message.ts:98-120](), [be/whatsapp-bot/services/send-message.ts:182-205](), [be/whatsapp-bot/services/send-message.ts:297-310]() ### Response Formatting Because the AI agent often generates HTML (optimized for Telegram), a formatting utility converts standard tags into WhatsApp's markdown-like syntax. | HTML Tag | WhatsApp Format | | :--- | :--- | | `` / `` | `*text*` (Bold) | | `` / `` | `_text_` (Italic) | | `
` / `` | ` ```text``` ` (Monospace) | | `` | `text (url)` | Sources: [be/whatsapp-bot/utils/format-response.ts:23-44]() ## Security and Verification The integration implements strict security measures to ensure the integrity of the webhook events: 1. **Hub Verification:** Verification of the `hub.verify_token` during initial setup. 2. **Signature Verification:** Use of `WHATSAPP_APP_SECRET` to verify `X-Hub-Signature-256` headers on incoming POST requests, ensuring messages originate from Meta. 3. **Authentication Middleware:** Protected endpoints like `/api/whatsapp/status` use `supabaseAuth()` to restrict access to authenticated administrators. Sources: [be/controllers/whatsapp-controller.ts:20-35](), [be/routes/whatsapp-route.ts:31-41]() ## Conclusion The WhatsApp Bot Integration is a robust, production-ready module that extends the AI Calendar Assistant's reach. By combining structured state management, AI-driven summarization, and a comprehensive onboarding flow, it provides a seamless user experience while maintaining high standards for security and architectural cleanliness.