Overview
The WhatsApp Bot integration enables automated customer service, order taking, reservation management, and bulk messaging through WhatsApp. Built on BuilderBot Cloud API, it provides real-time communication with customers and logs all interactions to Google Sheets.Features
- QR Code Authentication: Scan QR code to connect WhatsApp account
- Automated Status Tracking: Real-time bot connection monitoring
- Message Handling: Incoming and outgoing message support
- Order Creation: Create orders directly through WhatsApp conversations
- Reservation Management: Handle table reservations via WhatsApp
- Bulk Messaging: Send messages to individual customers or groups
- Chat History: Complete conversation logs synced to Google Sheets
- Metrics Tracking: Customer engagement and conversion analytics
Setup and Configuration
Configure BuilderBot API Keys
Add your BuilderBot credentials to the environment configuration:These values should be stored in environment variables for production.
Set up Google Sheets Webhook
Deploy the WhatsApp Assistant script from
AppsSript/whatsappAsistant.js as a web app:- Open Google Apps Script editor
- Navigate to Deploy > New Deployment
- Set type to Web App
- Execute as: Me
- Who has access: Anyone
- Copy the deployment URL
- Configure this URL as your BuilderBot webhook endpoint
The webhook logs all events to the
WhastappAssistant_logs sheet and tracks message history in WhatsappsHistory.Configure Google Sheet Structure
Ensure your Google Sheet (ID:
1wBGA_7out-9eSonGZAM-cPt9VOPa5OxQCA3Low_fVUI) has these sheets:- WhastappAssistant: Bot status management
- WhastappAssistant_logs: Event logs
- WhatsappsHistory: Message history
Bot Status Management
Connection States
The bot can be in one of three states:QR Code Scanning
When the bot is inREADY_TO_SCAN state, retrieve and display the QR code:
services/whatsappBotService.ts:32
Persisting Connection State
The bot connection state is persisted in local storage:services/whatsappBotService.ts:120
Sending Messages
Send to Individual Customer
services/whatsappBotService.ts:133
Send to WhatsApp Group
services/whatsappBotService.ts:184
Webhook Event Handling
The Google Apps Script webhook processes these BuilderBot events:Status Events
Message Events
AppsSript/whatsappAsistant.js:214
message.incoming: Customer sent a messagemessage.outgoing: Bot sent a messagemessage.calling: Incoming call notification
Manual Status Verification
You can manually check bot status from Apps Script:AppsSript/whatsappAsistant.js:34
Disconnecting the Bot
services/whatsappBotService.ts:89
Metrics and Analytics
Track bot performance with the metrics service:services/whatsappBotMetricsService.ts:61
Chat Session Structure
Order and Reservation Creation
Orders and reservations created via WhatsApp are marked withcreatedBy: 'whatsapp_assistant':
services/whatsappBotMetricsService.ts:76
Status Logging
All status changes are logged for auditing:services/whatsappBotService.ts:234
Status logs are stored in both Firestore and Google Sheets for redundancy and easy access.
API Endpoints
The integration uses these BuilderBot Cloud API endpoints:| Endpoint | Method | Purpose |
|---|---|---|
/api/v1/manager/deploys | POST | Initiate bot deployment |
/api/v1/manager/deploys/{projectId}/qr | GET | Retrieve QR code |
/api/v1/manager/deploys/{projectId} | GET | Check bot status |
/api/v1/manager/deploys/{projectId} | DELETE | Disconnect bot |
/api/v2/{projectId}/messages | POST | Send messages |
x-api-builderbot header with your API key.
Troubleshooting
QR Code Not Loading
- Verify the bot is in
READY_TO_SCANstate - Check that
builderBotApiKeyis correct - Ensure the project is properly deployed on BuilderBot Cloud
Messages Not Sending
- Confirm bot status is
ACTIVE - Verify
builderBotV2ApiKey(different from v1 key) - Check phone number format (no spaces, include country code)
- Review error messages in the response object
Webhook Not Receiving Events
- Verify Google Apps Script web app is deployed with “Anyone” access
- Check that the webhook URL is correctly configured in BuilderBot
- Review Apps Script logs for errors
- Ensure
SHEET_IDmatches your Google Sheet
Bot Status Shows Disconnected
- The bot disconnects after 24 hours of inactivity
- Scan the QR code again to reconnect
- Check if WhatsApp account was logged out on mobile device
Best Practices
- Monitor Connection Status: Poll
getWhatsAppStatus()periodically to detect disconnections - Handle Errors Gracefully: Always check message send results and retry if needed
- Rate Limiting: Avoid sending too many messages in quick succession
- Message Length: Keep messages under 4096 characters
- Media URLs: Ensure media URLs are publicly accessible and use HTTPS
- Backup Credentials: Store API keys securely in environment variables
- Log Analysis: Regularly review
WhastappAssistant_logsfor issues
