WhatsApp: Corporate Number Architecture & Evolution API

Odys leverages WhatsApp as a core communication channel between professionals and clients, automating key interactions such as booking confirmations, reminders, and payment receipts. This integration ensures timely, reliable messaging while maintaining brand consistency through templated, context-aware messages. The system is built around a centralized corporate WhatsApp number managed via Evolution API, enabling scalable, server-driven messaging across all users.

Overview

The WhatsApp integration in Odys is powered by Evolution API, a self-hosted solution that interfaces with WhatsApp Web via a persistent session. The architecture uses a single corporate number (managed through the evolution-api Docker service) to send and receive messages on behalf of all professionals. Incoming messages are routed via a webhook at /api/whatsapp/webhook, while outgoing messages are sent through 19 predefined templates that cover booking, payment, and engagement workflows.

All message logic resides in src/lib/whatsapp.ts, which exports type-safe functions for each template. These functions accept structured input (e.g., professionalName, clientName, date) and return formatted WhatsApp text with consistent branding, including a visual header and footer. The system also supports context tracking via Redis: when a transactional message is sent, the setOutboundContext function associates the recipient’s phone number with the relevant professionalId and appointmentId, enabling automatic routing of replies.

The integration is rate-limited to 10 messages per minute (whatsapp key in rateLimits) to comply with platform constraints. Two cron jobs support the flow: /api/cron/reminders (daily at 8 AM) triggers 24-hour reminders, and /api/cron/whatsapp-watchdog (9 AM daily) ensures the Evolution API instance is alive.

Design decisions

The use of Evolution API instead of official WhatsApp Business API allows Odys to avoid per-message fees and maintain full control over the messaging pipeline. By hosting the instance locally (via Docker), the team ensures predictable behavior and easier debugging during development.

Message templates are pure functions that return strings, making them easy to test, compose, and reuse. The transactionalHeader utility enforces visual consistency across notifications, distinguishing automated messages from conversational AI replies in the same chat thread.

Context tracking via Redis (setOutboundContext) solves the challenge of reply routing: when a client responds to a reminder, the system must know which professional and appointment the message refers to. By binding this context at send time, Odys avoids complex lookup logic in the webhook handler.

Potential improvements

1. Template localization — Currently, all templates are hardcoded in Portuguese. Adding i18n support (e.g., via a locale parameter in template functions) would enable multilingual messaging, especially important for non-Brazilian professionals. See src/lib/whatsapp.ts, msgBookingConfirmed.

2. Template validation against WhatsApp policies — WhatsApp rejects messages with disallowed content (e.g., excessive emojis, misleading buttons). Introducing a validation layer before sendWhatsApp could prevent failed deliveries. See src/lib/whatsapp.ts, sendWhatsApp.

3. Use of interactive messages (buttons/quick replies) — Evolution API supports interactive messages, but Odys currently uses plain text. Adding quick replies for actions like “Confirm Booking” or “Reschedule” could improve engagement. See src/lib/whatsapp.ts, msgBookingRequest.

References

• src/lib/whatsapp.ts — All message templates and send logic
• docker-compose.evolution.yml — Evolution API container configuration
• /api/cron/reminders — Cron route for daily reminder dispatch
• /api/whatsapp/webhook — Entry point for incoming WhatsApp messages