feat: implement WhatsApp AI agent communication layer with Twilio web…

[Uyoxy]

Description

This PR implements the WhatsApp AI agent communication layer, enabling users to manage their finances directly through WhatsApp using Twilio webhooks and NLP intent parsing.

The system receives WhatsApp messages from Twilio, detects user intent, executes the appropriate action, and returns a formatted response using TwiML.

Key Features
WhatsApp Webhook Receiver

Created src/routes/whatsapp.ts

Handles incoming Twilio webhook messages

Validates Twilio request signatures for security

Parses message intent using NLP

Executes the appropriate handler

Returns formatted WhatsApp replies via TwiML

Endpoints implemented:

GET /api/whatsapp/webhook → webhook health check

POST /api/whatsapp/webhook → receive WhatsApp messages

Intent Handler

Created src/whatsapp/handler.ts

Handles the following user intents:

Balance → fetch and return portfolio balance

Deposit → validate deposit amount and return wallet instructions

Withdraw → check available balance and process withdrawal request

Earnings → return yield performance summary

Help / Unknown → return supported commands list

User Management

Created src/whatsapp/userManager.ts

Responsibilities:

Identify users by phone number

Automatically create new users

Generate custodial Stellar wallet addresses

Store wallet data securely

Storage approach:

Public key stored normally

Secret key encrypted (KMS stub added for production implementation)

OTP Verification Flow

Implemented onboarding security:

New user sends message

System generates OTP

User verifies OTP

Account becomes active

Stored fields:

OTP code

OTP expiration timestamp

Security

Twilio webhook signature validation implemented

Blocks unauthorized webhook requests

Private keys not stored in plaintext

KMS integration stub added for production encryption

Testing

Integration tests added using mock Twilio payloads covering:

Valid webhook message handling

Invalid signature rejection

Balance queries

Deposit flow

Withdrawal flow

Documentation

Added:

WHATSAPP_SETUP.md

Includes:

Twilio WhatsApp sandbox setup

Webhook configuration

Local development setup

Ngrok testing instructions

Example local testing:

ngrok http 3001

Webhook URL format:

https://your-ngrok-url.ngrok.io/api/whatsapp/webhook
Dependencies Added
npm install twilio
npm install -D @types/twilio
Integration Flow

User sends WhatsApp message
↓
Twilio webhook triggers backend
↓
NLP parser detects intent
↓
Handler executes action
↓
Response formatted with TwiML
↓
Twilio sends reply to user

Acceptance Criteria

WhatsApp messages route correctly to intent handlers

Balance, deposit, earnings, and withdrawal responses formatted properly

New users automatically receive wallet addresses

Twilio signature validation works in production

Integration tests cover all handlers
closes #7

[robertocarlous]

can you check the ci some checks are failing @Uyoxy