WhatsApp Integration

Connect Arivu to WhatsApp through Twilio webhooks with text, voice, image, approvals, and feedback keywords.

What the backend needs

The WhatsApp adapter in integrations/whatsapp_adapter.py runs as a FastAPI webhook server backed by Twilio.

Required values:

• TWILIO_ACCOUNT_SID or account_sid
• TWILIO_AUTH_TOKEN or auth_token
• TWILIO_WHATSAPP_FROM or from_number
• Optional admin_numbers for approval control
• A public webhook URL if you are using Twilio outside local development

What WhatsApp users can do

Text Queries

Send a message and Arivu will run the query pipeline.

Voice Messages

Send a voice note and Arivu will transcribe it before querying.

Image Messages

Send an image or screenshot and Arivu will OCR the text.

Keyword Actions

Reply with APPROVE, REJECT, GOOD, or BAD for approvals and feedback.

Setup steps

1. Create a Twilio account

   Enable the WhatsApp sandbox or connect a production WhatsApp sender in Twilio.

2. Configure credentials

   Set TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and your WhatsApp sender number.

3. Expose a webhook endpoint

   Point Twilio to POST /webhook on the FastAPI server started by Arivu.

4. Add admin numbers

   Pass E.164 phone numbers in admin_numbers so approval messages go to the right people.

5. Start the server

   Call adapter.start(host="0.0.0.0", port=8080) or mount the FastAPI app behind your own server.

Example

from arivu.integrations.whatsapp_adapter import WhatsAppIntegration

adapter = WhatsAppIntegration(
        db=db,
        account_sid="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        auth_token="your-twilio-auth-token",
        from_number="whatsapp:[phone]",
        admin_numbers=["[phone]"],
)

adapter.start(host="0.0.0.0", port=8080)

Backend behavior

• Session IDs are mapped as whatsapp:{E164_number}.
• APPROVE / REJECT replies resolve pending SQL approvals.
• GOOD / BAD replies store RLHF feedback.
• Voice and image attachments are optional extensions; if dependencies are missing, install the extra packages from the adapter docstring.
• Twilio signature validation is enabled by default and can be skipped locally with TWILIO_SKIP_VALIDATION=1.

WhatsApp is webhook-based. You need a reachable URL for Twilio to call in production.