🤖 RetellAI WhatsApp Bridge

Connect your RetellAI conversational AI agents to WhatsApp via Twilio

A production-ready Node.js server that bridges Twilio WhatsApp messaging with RetellAI's chat API, enabling you to deploy sophisticated conversational AI agents on WhatsApp with persistent conversation history.

📋 Table of Contents

What This Does
Key Features
Architecture
Tech Stack
Prerequisites
Project Structure
Installation
Configuration
Running Locally
Using the Development Chat Widget
Agent Mapping
Deployment to Render
API Documentation
Security
Troubleshooting
Cost Considerations
Customization

🎯 What This Does

This server acts as a bridge between WhatsApp users and RetellAI conversational agents:

User sends WhatsApp message → Twilio receives it
Twilio webhook → Sends message to this server
Server looks up conversation → Finds or creates RetellAI chat session
RetellAI processes message → Generates intelligent response
Server sends response → Back to WhatsApp user via Twilio

Conversations persist across messages using MongoDB, maintaining context throughout the interaction.

✨ Key Features

✅ WhatsApp Integration - Full bidirectional messaging via Twilio
✅ Persistent Conversations - MongoDB tracks sessions per WhatsApp number
✅ Multi-Agent Support - Route different Twilio numbers to different RetellAI agents
✅ Development Chat Widget - Built-in web interface for testing
✅ Production Security - Environment-aware authentication and access control
✅ Session Management - Automatic conversation tracking and history
✅ Webhook Validation - Twilio signature verification for security
✅ Error Handling - Comprehensive error handling and logging
✅ Deployment Ready - Configured for Render deployment

🏗️ Architecture

High-Level Flow

WhatsApp User
    ↓
Twilio (receives message)
    ↓
POST /twilio/whatsapp (webhook)
    ↓
MongoDB (lookup session by phone number)
    ↓
RetellAI Chat API (send message, get response)
    ↓
MongoDB (update session)
    ↓
Twilio API (send response)
    ↓
WhatsApp User (receives AI response)

Components

Express Server - Handles HTTP requests and webhooks
MongoDB - Stores conversation sessions (phone number → chat_id mapping)
RetellAI Service - Wrapper for RetellAI chat API
Twilio Service - Handles WhatsApp message sending
Agent Mapping - Routes Twilio numbers to specific agents
Middleware - Authentication and validation layers

🛠️ Tech Stack

Node.js - Runtime environment
Express.js - Web framework
MongoDB - Database for session persistence
Mongoose - MongoDB ODM
RetellAI SDK - Official RetellAI Node.js SDK
Twilio SDK - Official Twilio Node.js SDK
dotenv - Environment variable management

📦 Prerequisites

Before you start, you'll need:

Accounts & Services

Node.js - Version 16+ (Download)
RetellAI Account - Sign up
Twilio Account - Sign up
MongoDB Atlas - Sign up (Free tier available)
Render Account - Sign up (For deployment, free tier available)

Technical Knowledge

Basic command line usage
Understanding of environment variables
Familiarity with REST APIs (helpful but not required)

📁 Project Structure

retell-whatsapp-bridge/
├── config/
│   ├── agentMapping.js      # Maps Twilio numbers to RetellAI agents
│   └── database.js          # MongoDB connection setup
├── middleware/
│   ├── apiKeyAuth.js        # API key authentication (always enforced)
│   ├── productionApiAuth.js # API key auth (production only)
│   └── twilioValidation.js  # Validates Twilio webhook signatures
├── models/
│   └── Session.js           # MongoDB schema for conversation sessions
├── routes/
│   ├── chat.js              # Chat widget API endpoints
│   └── whatsapp.js          # Twilio webhook handlers
├── services/
│   └── retellService.js     # RetellAI API wrapper
├── public/
│   ├── index.html           # Chat widget interface
│   ├── chat.js              # Chat widget frontend logic
│   └── styles.css           # Chat widget styling
├── .env                     # Environment variables (create this)
├── .env.example             # Environment variable template
├── .gitignore               # Git ignore rules
├── package.json             # Dependencies and scripts
├── server.js                # Main application entry point
└── README.md                # This file

Key Files Explained

server.js - Main application entry point, sets up Express and routes
config/agentMapping.js - Define which Twilio numbers use which RetellAI agents
config/database.js - MongoDB connection with error handling
models/Session.js - Database schema for tracking conversations
routes/whatsapp.js - Handles incoming WhatsApp messages from Twilio
routes/chat.js - API endpoints for the development chat widget
services/retellService.js - Wrapper for RetellAI SDK calls
middleware/productionApiAuth.js - Protects routes in production only
middleware/twilioValidation.js - Verifies webhooks are from Twilio

🚀 Installation

Step 1: Clone the Repository

git clone <your-repo-url>
cd retell-whatsapp-bridge

Step 2: Install Dependencies

npm install

This installs:

express - Web framework
mongoose - MongoDB ODM
retell-sdk - RetellAI official SDK
twilio - Twilio SDK
dotenv - Environment variables
nodemon - Development auto-reload (dev dependency)

Step 3: Create Environment File

# Copy the example file
cp .env.example .env

# Or on Windows
copy .env.example .env

Now edit .env with your actual credentials (see Configuration section below).

⚙️ Configuration

1. RetellAI Setup

Create Your Agent

Go to RetellAI Dashboard
Sign in or create an account
Click "Create New Agent"
Choose "Chat Agent" (not voice agent)
Configure your agent:
- Set the agent name
- Configure conversation flow or prompts
- Choose your LLM settings
- Test in the playground
Save the agent

Get Your Credentials

Go to Settings → API Keys
Copy your API Key (starts with key_...)
Go back to Agents → Click your agent
Copy the Agent ID (starts with agent_...)

Save these for your .env file!

2. MongoDB Setup

Create a Free Cluster

Go to MongoDB Atlas
Sign up for a free account
Click "Build a Database"
Choose "Free" tier (M0 Sandbox)
Select your cloud provider and region (choose closest to you)
Click "Create Cluster"

Configure Database Access

Click "Database Access" in the left sidebar
Click "Add New Database User"
Choose "Password" authentication
Create a username and strong password (save these!)
Set privileges to "Read and write to any database"
Click "Add User"

Configure Network Access

Click "Network Access" in the left sidebar
Click "Add IP Address"
Click "Allow Access from Anywhere" (or add specific IPs)
Click "Confirm"

⚠️ Note: "Allow from anywhere" is fine for development. For production, restrict to your Render IP.

Get Connection String

Go back to "Database"
Click "Connect" on your cluster
Choose "Connect your application"
Copy the connection string (looks like: mongodb+srv://username:password@cluster...)
Replace <password> with your actual database password
Replace <dbname> with your database name (e.g., retell_whatsapp)

Save this for your .env file!

3. Twilio Setup

Create Twilio Account

Go to Twilio
Sign up for an account (free trial available)
Verify your email and phone number

Get Your Credentials

Go to Twilio Console
Copy your Account SID and Auth Token from the dashboard

Save these for your .env file!

WhatsApp Setup - Option A: Sandbox (Testing)

Perfect for development and testing:

In Twilio Console, go to Messaging → Try it out → Send a WhatsApp message
Follow instructions to connect your phone to the sandbox
Your sandbox number will be shown (e.g., whatsapp:+14155238886)
This is your TWILIO_WHATSAPP_NUMBER

⚠️ Sandbox Limitations:

Only works with numbers you've manually connected
Shows "sandbox" in messages
Not for production use

WhatsApp Setup - Option B: Production Number

For real production use:

Go to Messaging → WhatsApp → Senders
Click "New Sender"
Follow the approval process (requires business verification)
Once approved, you'll get your WhatsApp-enabled Twilio number

💡 Tip: Start with sandbox for testing, upgrade to production number when ready.

4. Environment Variables

Create a .env file in the root directory with these values:

# Server Configuration
PORT=5000
NODE_ENV=development

# RetellAI Configuration
RETELL_API_KEY=key_your_retell_api_key_here
RETELL_AGENT_ID=agent_your_agent_id_here

# MongoDB Configuration
MONGODB_URI=mongodb+srv://username:[email protected]/
MONGODB_DATABASE_NAME=retell_whatsapp

# Twilio Configuration
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_WHATSAPP_NUMBER=whatsapp:+14155238886

# API Security
API_KEY=your-secret-api-key-here-generate-a-strong-one

Variable Explanations

Variable	Description	Where to Get It	Required
`PORT`	Server port	Can be any available port (default: 5000)	Yes
`NODE_ENV`	Environment mode	`development` or `production`	Yes
`RETELL_API_KEY`	RetellAI API key	RetellAI Dashboard → Settings → API Keys	Yes
`RETELL_AGENT_ID`	Your chat agent ID	RetellAI Dashboard → Agents → Your Agent	Yes
`MONGODB_URI`	MongoDB connection string	MongoDB Atlas → Connect → Connection String	Yes
`MONGODB_DATABASE_NAME`	Database name	Choose any name (e.g., `retell_whatsapp`)	Yes
`TWILIO_ACCOUNT_SID`	Twilio account identifier	Twilio Console Dashboard	Yes
`TWILIO_AUTH_TOKEN`	Twilio authentication token	Twilio Console Dashboard	Yes
`TWILIO_WHATSAPP_NUMBER`	Your Twilio WhatsApp number	Twilio Messaging → WhatsApp (include `whatsapp:` prefix)	Yes
`API_KEY`	Security key for production API access	Generate a strong random string	Yes

Generating a Strong API Key

Use one of these methods:

Option 1: Online Generator

Visit: https://randomkeygen.com/
Use a "Fort Knox Password"

Option 2: Node.js

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Option 3: Manual

Create a long random string (30+ characters)
Mix letters, numbers, and symbols

🏃 Running Locally

Development Mode

npm run dev

This starts the server with auto-reload using nodemon. You should see:

✅ MongoDB connected successfully
📊 Database: retell_whatsapp
📁 Static files enabled (development mode)
✅ Server running on http://localhost:5000
📊 Environment: development
🏥 Health check: http://localhost:5000/health

Testing the Chat Widget

Open your browser to http://localhost:5000/
You should see the chat interface
Click "Start Chat" to create a session
Type a message and press Send
You should get a response from your RetellAI agent

Debug Info:

Click "Debug Info" dropdown to see the chat_id
Check your terminal for server logs
Check MongoDB Atlas → Collections to see the session stored

Testing WhatsApp (Sandbox)

Make sure your server is running locally
Use a tool like ngrok to expose your local server:
```
ngrok http 5000
```
Copy the https:// URL from ngrok (e.g., https://abc123.ngrok.io)
Go to Twilio Console → Messaging → WhatsApp Sandbox Settings
Set webhook URL to: https://abc123.ngrok.io/twilio/whatsapp
Send a WhatsApp message to your sandbox number
Check your terminal logs to see the message processing

🧪 Using the Development Chat Widget

The chat widget provides a web-based interface for testing your RetellAI agent without needing WhatsApp or Twilio setup.

Accessing the Widget

Development Mode Only:

Ensure NODE_ENV=development in your .env
Start the server: npm run dev
Open browser to: http://localhost:5000/

You should see:

Chat interface with header "🤖 RetellAI Chat Test"
"Phase 3 Development Interface" subtitle
Empty chat area with system message
Disabled input box and Send button
Green "Start Chat" button
Disabled gray "End Chat" button
"Not Connected" status indicator

Starting a Conversation

Click "Start Chat"
- Creates new RetellAI chat session
- Returns a unique chat_id
- Enables message input and Send button
- Status changes to "Connected" (green)
Check Debug Info (optional)
- Click "Debug Info" dropdown
- See your chat_id (useful for troubleshooting)
- See current status

Sending Messages

Type your message in the input box
Press Enter or click Send
Your message appears (blue, right-aligned)
Agent response appears (white, left-aligned)
Input is temporarily disabled while processing

What Happens Behind the Scenes:

Your message → POST /api/chat/message → RetellAI API → Response displayed

Ending a Session

Click "End Chat" when done
Session marked as "ended" in database
Input box disabled
Status changes to "Not Connected" (red)
System message: "Chat ended. Click Start Chat to begin..."

Note: You can start a new chat immediately after ending one.

Chat Widget Features

Element	Purpose	Behavior
Start Chat	Initialize new session	Disabled once connected
End Chat	Close current session	Only enabled when connected
Message Input	Type your message	Disabled until connected
Send Button	Submit message	Disabled while processing
Status Indicator	Connection state	Green = connected, Red = disconnected
Debug Info	View technical details	Shows chat_id and status

Understanding the Interface

User Messages (Blue):

Your messages to the agent
Right-aligned
Blue background

Agent Messages (White):

Responses from RetellAI
Left-aligned
White background with border

System Messages (Yellow):

Status updates
Errors or warnings
Center-aligned

Widget vs WhatsApp Differences

Feature	Chat Widget	WhatsApp
Session Tracking	Temporary (web_timestamp)	Persistent (phone number)
Conversation History	Lost on page refresh	Persists across sessions
Authentication	None (dev only)	Twilio validation
Multi-User	One at a time per browser	Unlimited concurrent
Purpose	Testing & development	Production use
Agent Selection	Uses `RETELL_AGENT_ID`	Uses agent mapping

Common Widget Scenarios

Testing Agent Responses

1. Start Chat
2. Send: "Hello, can you help me?"
3. Verify response makes sense
4. Continue conversation to test flow
5. End Chat when done

Testing Conversation Context

1. Start Chat
2. Send: "My name is John"
3. Send: "What's my name?"
4. Agent should remember "John"
5. Verify context is maintained

Testing Error Handling

1. Start Chat
2. Stop your server (Ctrl+C)
3. Try sending message
4. Should see error message
5. Restart server and try again

Debugging Session Issues

1. Start Chat
2. Open Debug Info dropdown
3. Copy the chat_id
4. Check MongoDB Atlas for this chat_id
5. Verify session is stored correctly

Troubleshooting the Widget

Widget Not Loading:

Check NODE_ENV=development in .env
Verify public/ folder has index.html, chat.js, styles.css
Check browser console for errors (F12 → Console)
Clear browser cache

"Start Chat" Does Nothing:

Check server logs for errors
Verify RETELL_API_KEY and RETELL_AGENT_ID in .env
Test health endpoint: http://localhost:5000/health
Check browser console for JavaScript errors

Agent Not Responding:

Verify RetellAI agent is active in dashboard
Check server logs for RetellAI errors
Test agent in RetellAI playground
Verify API key has permissions

Messages Not Appearing:

Check browser console for errors
Verify server returned successful response
Check server logs for processing errors
Try refreshing the page and starting new session

Widget Limitations

⚠️ The chat widget:

Does NOT work in production (NODE_ENV=production)
Does NOT persist sessions across page refreshes
Does NOT support rich media (images, files)
Does NOT show typing indicators
Does NOT support multiple tabs (each creates new session)
Is ONLY for development testing

When to Use the Widget

✅ Use the chat widget for:

Initial agent testing
Verifying RetellAI integration works
Testing conversation flows
Debugging agent responses
Quick development iterations
Demonstrating to stakeholders

❌ Don't use the widget for:

Production conversations
Performance testing
Multi-user testing
Long-term conversation history
Real user interactions

Testing Workflow Recommendation

Start with Chat Widget - Test basic agent functionality
Use Twilio Sandbox - Test WhatsApp integration
Deploy to Render - Test production environment
Get Production Number - Launch for real users

🗺️ Agent Mapping Configuration

The config/agentMapping.js file lets you route different Twilio numbers to different RetellAI agents.

Default Configuration

const agentMapping = {
  "+447723451913": "agent_9f143ae97176def0b8e57ed6a0",
};

Adding Multiple Agents

const agentMapping = {
  "+447723451913": "agent_9f143ae97176def0b8e57ed6a0",  // Support line
  "+447723451914": "agent_abc123def456789012345678",    // Sales line
  "+447723451915": "agent_xyz789ghi012345678901234",    // Billing line
};

How It Works

WhatsApp message comes to one of your Twilio numbers
Server extracts the receiving number (which Twilio number received it)
Looks up that number in agentMapping
Uses the corresponding agent_id for the conversation
If no mapping found, falls back to process.env.RETELL_AGENT_ID

Use Cases

Department routing - Different numbers for support, sales, billing
Language support - Spanish line, English line
A/B testing - Test different agent configurations
Multi-brand - Different agents for different brands

Viewing Current Mappings

curl http://localhost:5000/twilio/mappings?api_key=your-api-key-here

Returns:

{
  "success": true,
  "mappings": {
    "+447723451913": "agent_9f143ae97176def0b8e57ed6a0"
  },
  "count": 1,
  "defaultAgent": "agent_fallback_id"
}

🌐 Deployment to Render

Step 1: Prepare Your Code

Make sure your code is in a Git repository (GitHub, GitLab, etc.)
Ensure .env is in .gitignore (never commit secrets!)
Push your code to the repository

Step 2: Create Render Service

Go to Render Dashboard
Click "New +" → "Web Service"
Connect your Git repository
Configure the service:
- Name: retell-whatsapp-bridge (or your choice)
- Environment: Node
- Build Command: npm install
- Start Command: npm start
- Plan: Free (or paid for better performance)

Step 3: Set Environment Variables

In Render dashboard, go to Environment and add all your .env variables:

⚠️ CRITICAL: Set these correctly:

NODE_ENV=production
PORT=5000
API_KEY=<your-strong-secret-key>
RETELL_API_KEY=<your-retell-key>
RETELL_AGENT_ID=<your-agent-id>
MONGODB_URI=<your-mongodb-connection-string>
MONGODB_DATABASE_NAME=retell_whatsapp
TWILIO_ACCOUNT_SID=<your-twilio-sid>
TWILIO_AUTH_TOKEN=<your-twilio-token>
TWILIO_WHATSAPP_NUMBER=whatsapp:+1234567890

Step 4: Deploy

Click "Create Web Service"
Render will build and deploy automatically
Wait for deployment to complete
You'll get a URL like: https://your-app.onrender.com

Step 5: Configure Twilio Webhook

Go to Twilio Console
Navigate to your WhatsApp sender/sandbox settings
Set the webhook URL to: https://your-app.onrender.com/twilio/whatsapp
Set HTTP method to POST
Save

Step 6: Test Production

Send a WhatsApp message to your Twilio number. You should get a response!

Check Render Logs:

Go to your Render service
Click "Logs" tab
Watch for incoming requests and responses

📚 API Documentation

Chat Widget Endpoints

POST `/api/chat/start`

Creates a new chat session with RetellAI.

Authentication:

Development: None
Production: Requires X-API-Key header

Response:

{
  "success": true,
  "chat_id": "16b980523634a6dc504898cda492e939",
  "session_id": "507f1f77bcf86cd799439011",
  "message": "Chat session created and saved to database"
}

POST `/api/chat/message`

Sends a message to the agent and returns the response.

Authentication:

Development: None
Production: Requires X-API-Key header

Request Body:

{
  "chat_id": "16b980523634a6dc504898cda492e939",
  "message": "Hello, how can you help me?"
}

Response:

{
  "success": true,
  "response": "Hello! I'm here to help. What can I do for you today?",
  "message_count": 1,
  "full_response": { }
}

POST `/api/chat/end`

Ends an active chat session.

Authentication:

Development: None
Production: Requires X-API-Key header

Request Body:

{
  "chat_id": "16b980523634a6dc504898cda492e939"
}

Response:

{
  "success": true,
  "message": "Chat session ended"
}

GET `/api/chat/sessions`

Debug endpoint to view active sessions.

Authentication: Always requires X-API-Key header (even in development)

Response:

{
  "total_sessions": 45,
  "active_sessions": 12,
  "recent_active": [
    {
      "whatsapp_number": "+447723451913",
      "chat_id": "16b980523634a6dc504898cda492e939",
      "status": "active",
      "message_count": 5,
      "last_message_at": "2025-01-15T10:30:00.000Z"
    }
  ]
}

WhatsApp Endpoints

POST `/twilio/whatsapp`

Receives incoming WhatsApp messages from Twilio webhook.

Authentication: Twilio signature validation (automatic)

This endpoint is called by Twilio, not by you directly.

GET `/twilio/mappings`

View current agent mappings.

Authentication: Always requires X-API-Key header

Response:

{
  "success": true,
  "mappings": {
    "+447723451913": "agent_9f143ae97176def0b8e57ed6a0"
  },
  "count": 1,
  "defaultAgent": "agent_fallback_id"
}

Health Check

GET `/health`

Returns server health status.

Authentication: None

Response:

{
  "status": "ok",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "environment": "production",
  "port": "5000"
}

🔒 Security

Development vs Production Modes

This server has different security levels based on NODE_ENV:

Development Mode (`NODE_ENV=development`)

✅ Chat widget accessible at /
✅ Static files (HTML, JS, CSS) served
✅ Chat API endpoints work without authentication
✅ Twilio signature validation skipped
🎯 Purpose: Easy local testing

Production Mode (`NODE_ENV=production`)

❌ Chat widget hidden (shows status page)
❌ Static files not served
✅ Chat API endpoints require X-API-Key header
✅ Twilio signature validation enforced
🔒 Purpose: Secure production deployment

Security Features

API Key Protection
- All chat endpoints require X-API-Key in production
- Prevents unauthorized API usage
- Protects your RetellAI credits
Twilio Signature Validation
- Verifies webhooks actually come from Twilio
- Prevents spoofed webhook attacks
- Automatically enforced in production
MongoDB Access Control
- Connection string includes authentication
- Database credentials required
- Network access controls in Atlas
Environment Variable Protection
- Secrets never committed to Git
- .gitignore includes .env
- Render encrypts environment variables

Best Practices

Never commit .env files
Use strong API keys (30+ random characters)
Restrict MongoDB network access in production
Rotate API keys periodically
Monitor Render logs for suspicious activity
Keep dependencies updated (npm audit)

🔧 Troubleshooting

Common Issues

"Cannot connect to MongoDB"

Symptoms:

❌ MongoDB connection error: MongoServerError: bad auth

Solutions:

Check MONGODB_URI is correct
Ensure password doesn't have special characters (or URL-encode them)
Verify database user has correct permissions
Check MongoDB Atlas network access allows your IP
Test connection string in MongoDB Compass

"Agent ID not configured"

Symptoms:

{
  "error": "Agent ID not configured"
}

Solutions:

Check .env has RETELL_AGENT_ID
Verify the agent ID is correct (starts with agent_)
Ensure .env file is in the root directory
Restart the server after changing .env

"Twilio webhook not working"

Symptoms:

Send WhatsApp message, no response
Twilio console shows webhook errors

Solutions:

Check webhook URL is correct in Twilio console
Ensure URL includes /twilio/whatsapp path
Verify server is publicly accessible (use ngrok for local testing)
Check server logs for errors
Verify TWILIO_AUTH_TOKEN is correct
In development, signature validation is skipped (check NODE_ENV)

"Chat widget not loading"

Symptoms:

Blank page at http://localhost:5000/
404 errors in browser console

Solutions:

Check NODE_ENV=development in .env
Verify public/ folder exists with HTML, JS, CSS files
Restart server after changing NODE_ENV
Check browser console for JavaScript errors
Clear browser cache

"Port already in use"

Symptoms:

Error: listen EADDRINUSE: address already in use :::5000

Solutions:

Change PORT in .env to different number (e.g., 5001)

Kill process using port 5000:

# On Mac/Linux
lsof -ti:5000 | xargs kill -9

# On Windows
netstat -ano | findstr :5000
taskkill /PID <PID> /F

"API key required in production"

Symptoms:

{
  "error": "Unauthorized",
  "message": "API key required in production..."
}

Solutions:

This is expected in production mode - it's working correctly!

Add X-API-Key header to your requests:

curl -H "X-API-Key: your-api-key" http://your-url/api/chat/start

If testing locally, set NODE_ENV=development in .env

Session not persisting

Symptoms:

Each WhatsApp message creates new conversation
Agent doesn't remember previous messages

Solutions:

Check MongoDB connection is successful in logs
Verify Session collection exists in MongoDB Atlas
Check WhatsApp number format matches (E.164: +1234567890)
Look for errors in server logs during message processing
Verify MONGODB_DATABASE_NAME matches your database

RetellAI errors

Symptoms:

❌ Error creating chat: Failed to create chat session

Solutions:

Verify RETELL_API_KEY is correct
Check RETELL_AGENT_ID exists in your RetellAI dashboard
Ensure agent is a "chat agent" not "voice agent"
Check RetellAI account has available credits
Test API key directly in RetellAI API playground

Getting Help

If you're still stuck:

Check the logs - Most errors are logged to console
Search issues - Check GitHub issues for similar problems
Test components - Test MongoDB, RetellAI, Twilio separately
Ask the community - Post in discussions with logs and error messages

💰 Cost Considerations

Free Tiers

Render Free Tier: 750 hours/month (1 service always on)
MongoDB Atlas Free Tier: 512MB storage (plenty for thousands of sessions)
Twilio Trial: $15 credit (good for testing)
RetellAI: Pricing varies, check their website

Estimated Monthly Costs (Production)

Low Volume (< 1,000 messages/month):

Render: Free tier sufficient
MongoDB: Free tier sufficient
Twilio: ~$0.005 per message = ~$5
RetellAI: Varies by plan and usage

Medium Volume (1,000-10,000 messages/month):

Render: $7/month (paid tier for better performance)
MongoDB: Free tier sufficient
Twilio: ~$50-100/month
RetellAI: Check their pricing calculator

High Volume (10,000+ messages/month):

Consider dedicated hosting
MongoDB Atlas paid tier for better performance
Twilio volume discounts may apply
RetellAI enterprise plans available

Cost Optimization Tips

Use free tiers for development and testing
Monitor usage regularly in each platform's dashboard
Set spending alerts in Twilio and RetellAI
Clean up old sessions periodically in MongoDB
Optimize agent responses to reduce token usage
Cache common responses where appropriate

🎨 Customization

Modifying the Chat Widget

Edit public/index.html, public/chat.js, and public/styles.css to customize:

UI design and colors
Chat behavior
Welcome messages
Input validation
Error handling

Changing Agent Behavior

Go to RetellAI Dashboard
Edit your agent's:
- Conversation flow
- Prompts and instructions
- Response style
- Tool integrations
Changes apply immediately (no code changes needed)

Adding Custom Middleware

Create new files in middleware/ folder:

// middleware/rateLimiter.js
function rateLimiter(req, res, next) {
  // Your rate limiting logic
  next();
}
module.exports = rateLimiter;

Add to server.js:

const rateLimiter = require('./middleware/rateLimiter');
app.use(rateLimiter);

Database Schema Changes

Edit models/Session.js to add new fields:

const sessionSchema = new mongoose.Schema({
  whatsapp_number: String,
  chat_id: String,
  agent_id: String,
  
  // Add custom fields
  user_name: String,
  user_language: String,
  tags: [String],
  
  status: String,
  created_at: Date,
  last_message_at: Date,
  message_count: Number
});

Adding More Routes

Create new files in routes/ folder:

// routes/analytics.js
const express = require('express');
const router = express.Router();

router.get('/stats', async (req, res) => {
  // Your analytics logic
});

module.exports = router;

Add to server.js:

const analyticsRoutes = require('./routes/analytics');
app.use('/api/analytics', analyticsRoutes);

🚧 Limitations & Known Issues

Current Limitations

No rich media support - Text messages only (no images, videos, files)
No conversation timeout - Sessions remain active indefinitely
No admin dashboard - Must use MongoDB Atlas to view sessions
No message queue - Processes messages synchronously
Single database - Not multi-tenant

Future Enhancements

Ideas for future versions:

Admin dashboard for session management
Rich media support (images, documents)
Conversation analytics and insights
Multi-language support
Message queuing for high volume
Automated session cleanup
User profile management
Integration with CRM systems
Webhook events for external systems
A/B testing framework

Feel free to fork and add these features!

🤝 Contributing

Contributions are welcome! Here's how:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Test thoroughly
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

Use ES6+ features
Use async/await over callbacks
Add comments for complex logic
Handle all errors appropriately
Keep functions focused and small
Use descriptive variable names

🙏 Acknowledgments

RetellAI - For their amazing conversational AI platform
Twilio - For WhatsApp Business API access
MongoDB - For flexible document database
The community - For feedback and contributions

🎯 Community & Support

🏫 Skool Community: Join our AI Freedom Finders community for support, discussions, and updates: https://www.skool.com/ai-freedom-finders
📱 TikTok: Follow for AI tutorials, tips, and behind-the-scenes content: https://www.tiktok.com/@ai_entrepreneur_educator
🌐 Website: https://bramforth.ai
GitHub Issues: Report bugs and request features
Discussions: Ask questions and share your implementations

Built with ❤️ for the community

Happy building! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
config		config
middleware		middleware
models		models
public		public
routes		routes
services		services
.env.example.txt		.env.example.txt
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
server.js		server.js

License

bramforth-ai/retellai-whatsapp-bridge-tiktok

Folders and files

Latest commit

History

Repository files navigation

🤖 RetellAI WhatsApp Bridge

📋 Table of Contents

🎯 What This Does

✨ Key Features

🏗️ Architecture

High-Level Flow

Components

🛠️ Tech Stack

📦 Prerequisites

Accounts & Services

Technical Knowledge

📁 Project Structure

Key Files Explained

🚀 Installation

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Create Environment File

⚙️ Configuration

1. RetellAI Setup

Create Your Agent

Get Your Credentials

2. MongoDB Setup

Create a Free Cluster

Configure Database Access

Configure Network Access

Get Connection String

3. Twilio Setup

Create Twilio Account

Get Your Credentials

WhatsApp Setup - Option A: Sandbox (Testing)

WhatsApp Setup - Option B: Production Number

4. Environment Variables

Variable Explanations

Generating a Strong API Key

🏃 Running Locally

Development Mode

Testing the Chat Widget

Testing WhatsApp (Sandbox)

🧪 Using the Development Chat Widget

Accessing the Widget

Starting a Conversation

Sending Messages

Ending a Session

Chat Widget Features

Understanding the Interface

Widget vs WhatsApp Differences

Common Widget Scenarios

Testing Agent Responses

Testing Conversation Context

Testing Error Handling

Debugging Session Issues

Troubleshooting the Widget

Widget Limitations

When to Use the Widget

Testing Workflow Recommendation

🗺️ Agent Mapping Configuration

Default Configuration

Adding Multiple Agents

How It Works

Use Cases

Viewing Current Mappings

🌐 Deployment to Render

Step 1: Prepare Your Code

Step 2: Create Render Service

Step 3: Set Environment Variables

Step 4: Deploy

Step 5: Configure Twilio Webhook

Step 6: Test Production

📚 API Documentation

Chat Widget Endpoints

POST /api/chat/start

POST /api/chat/message

POST /api/chat/end

GET /api/chat/sessions

POST `/api/chat/start`

POST `/api/chat/message`

POST `/api/chat/end`

GET `/api/chat/sessions`

POST `/twilio/whatsapp`

GET `/twilio/mappings`

GET `/health`

Development Mode (`NODE_ENV=development`)

Production Mode (`NODE_ENV=production`)

Packages