Skip to main content

WhatsApp Channels Support

Overview​

This document describes the addition of WhatsApp message (wmsg) and WhatsApp voice (wvoice) channels to Aventora-Assistant, following the same implementation pattern as SMS and phone channels.

Changes Summary​

New Channels​

  • wmsg: WhatsApp text messages via Twilio WhatsApp API
  • wvoice: WhatsApp voice calls via Twilio WhatsApp API

Domain Metadata Migration​

Twilio credentials have been moved from environment variables to domain metadata (technical_json) with separate configuration items for each channel:

  • twilio_sms_account_sid, twilio_sms_auth_token, twilio_sms_number (for SMS)
  • twilio_phone_account_sid, twilio_phone_auth_token, twilio_phone_number (for phone)
  • twilio_whatsapp_account_sid, twilio_whatsapp_auth_token, twilio_whatsapp_number (for WhatsApp)

The system falls back to shared twilio_account_sid and twilio_auth_token if channel-specific credentials are not found.

Technical Implementation​

New Services​

  1. WhatsApp Message Service (services/whatsapp_message_service.py)

    • Similar structure to SMS service
    • Uses domain metadata for Twilio credentials
    • Supports conversation sessions (reuses sms_sessions table)
    • Integrates with billing service (3 credits per message, same as SMS)

  2. WhatsApp Voice Service (services/whatsapp_voice_service.py)

    • Similar to phone calling but for WhatsApp voice
    • Uses Twilio WhatsApp voice calling API
    • Follows pattern from domain-chatbot WhatsApp implementation

Domain Resolver Updates​

Added methods to services/domain_resolver.py:

  • get_domain_metadata(): Fetches domain metadata including technical_json from domain-chatbot API
  • get_twilio_config(): Extracts channel-specific Twilio credentials from domain metadata

API Updates​

Channel Validation

  • Updated valid_channels to include ["phone", "sms", "wmsg", "wvoice"]
  • All endpoints now accept the new channel values

Channel Routing

  • wmsg: Routes to WhatsApp message service (similar to SMS)
  • wvoice: Routes to WhatsApp voice service (similar to phone)
  • Both channels require domain_name parameter for credential lookup

Database Changes​

Migration 1.15.0: migrate_add_whatsapp_channels.py

  • No actual schema changes required (channel column already supports VARCHAR(20))
  • Updated schema comments to document new channel values
  • Migration runs automatically on server startup

Schema Updates

  • call_logs.channel: Updated comment to include 'wmsg' and 'wvoice'
  • email_pull_configs.default_channel: Updated comment and validation

UI Updates​

Single Call Dialog (aventora-admin/components/phone/single-call-dialog.tsx)

  • Added "WhatsApp Message" and "WhatsApp Voice" radio options
  • Updated TypeScript types to include new channels

Email Pull Component (aventora-admin/components/phone/email-pull-content.tsx)

  • Added WhatsApp options to default channel dropdown

Bulk Upload (aventora-admin/components/phone/bulk-upload-content.tsx)

  • Updated documentation to mention wmsg and wvoice in channel column

Billing​

  • wmsg: Uses "wmsg" service type (3 credits per message, same as SMS)
  • wvoice: Uses call_type for billing (same as phone calls)
  • Billing service automatically handles new service types

Configuration​

Domain Metadata Structure​

Update your domain's technical_json in domain-chatbot:

{
  "twilio_sms_account_sid": "AC...",
  "twilio_sms_auth_token": "...",
  "twilio_sms_number": "+1234567890",
  "twilio_phone_account_sid": "AC...",
  "twilio_phone_auth_token": "...",
  "twilio_phone_number": "+1234567890",
  "twilio_whatsapp_account_sid": "AC...",
  "twilio_whatsapp_auth_token": "...",
  "twilio_whatsapp_number": "+1234567890"
}

Note: The twilio_whatsapp_number should be in E.164 format (e.g., +1234567890) without the whatsapp: prefix. The code automatically adds the prefix when sending messages.

Twilio Webhook Configuration​

WhatsApp requires a separate webhook URL from SMS, even though they use the same infrastructure.

WhatsApp Webhook Setup​

  1. In Twilio Console:

    • Go to Messaging → Try it out → Send a WhatsApp message
    • Or go to Phone Numbers → Select your WhatsApp-enabled number
    • Under Messaging Configuration, set the webhook URL: 
      https://your-domain.com/whatsapp/webhook
    • Method: POST
    • Save the configuration

  2. Webhook URL Format:

    • Base URL: Your Aventora-Assistant server URL (e.g., https://phone.aventora.ai)
    • Endpoint: /whatsapp/webhook
    • Full URL: https://phone.aventora.ai/whatsapp/webhook

SMS Webhook Setup (for reference)​

  • SMS webhook URL: https://your-domain.com/sms/webhook
  • This is separate from the WhatsApp webhook

Important Notes​

  • Different URLs: WhatsApp and SMS use different webhook endpoints (/whatsapp/webhook vs /sms/webhook)
  • Same Infrastructure: Both use the same sessions table and bot, but require separate Twilio webhook configurations
  • Domain Required: WhatsApp messages require domain_name in the session context to look up credentials
  • Number Format: Twilio sends WhatsApp numbers with whatsapp: prefix (e.g., whatsapp:+14167078887), which is automatically handled

Fallback Behavior​

If channel-specific credentials are not found, the system falls back to:

  • twilio_account_sid and twilio_auth_token (shared credentials)
  • Environment variables (for backward compatibility)

Usage Examples​

API Call with WhatsApp Message​

POST /start
{
  "phone_number": "+1234567890",
  "channel": "wmsg",
  "type": "informational",
  "instruction": "Send appointment reminder",
  "domain_name": "yourdomain"
}

API Call with WhatsApp Voice​

POST /start
{
  "phone_number": "+1234567890",
  "channel": "wvoice",
  "type": "appointment_booking",
  "instruction": "Help book an appointment",
  "domain_name": "yourdomain"
}

Bulk Upload CSV​

phone_number,name,email,instruction,call_type,channel
+1234567890,John Doe,john@example.com,Send reminder,informational,wmsg
+0987654321,Jane Smith,jane@example.com,Book appointment,appointment_booking,wvoice

Migration Notes​

  1. Automatic Migration: Migration 1.15.0 runs automatically on server startup
  2. No Downtime: No schema changes required, only documentation updates
  3. Backward Compatibility: Existing phone and SMS channels continue to work
  4. Environment Variables: Still supported as fallback for domains without metadata

Testing​

Test WhatsApp channels using:

  • Single call dialog in admin UI
  • Bulk upload with channel column
  • Email pull with default_channel set to wmsg or wvoice
  • Direct API calls with channel parameter

Notes​

  • WhatsApp voice calls use the same TwiML/WebSocket infrastructure as phone calls
  • WhatsApp messages reuse the sms_sessions table for conversation tracking
  • Both channels require domain_name parameter for credential lookup
  • Phone numbers for WhatsApp must be formatted as whatsapp:+1234567890 (handled automatically)