Frequently Asked Questions
Integrate WhatsApp into your RedwoodJS application using the Plivo communications platform. This involves setting up a RedwoodJS project, installing the Plivo SDK, configuring your Plivo account, and implementing the necessary backend and frontend logic to send and receive WhatsApp messages.
Plivo is a cloud communications platform that provides the necessary APIs for sending and receiving WhatsApp messages. It acts as a bridge between your RedwoodJS application and the WhatsApp Business API.
RedwoodJS is chosen for its full-stack capabilities, serverless-friendly nature, and excellent developer experience. It provides conventions, integrated tooling for GraphQL, Prisma, and Jest, making development smoother.
ngrok is essential during local development to create a publicly accessible URL for your RedwoodJS API server, which Plivo's webhook uses to send incoming WhatsApp messages. For production, replace the ngrok URL with your application's stable public URL.
Yes, sending WhatsApp message templates is a key part of this integration. Templates are required for initiating conversations or sending messages outside the 24-hour customer service window and must be pre-approved by Meta.
You send WhatsApp messages by calling the Plivo API from your RedwoodJS backend service. The provided code example demonstrates using the sendWhatsAppText function for standard text messages and sendWhatsAppTemplate for templated messages. Both functions use the Plivo Node.js SDK to interact with the API.
The webhook acts as a receiver for incoming WhatsApp messages. Plivo sends a POST request to your designated RedwoodJS API endpoint (the webhook) whenever a new message arrives. The webhook processes the incoming message data and can trigger further actions like saving to a database.
Configure your Plivo WhatsApp number's messaging settings to point to your RedwoodJS API endpoint. Use ngrok for local development and your application's public URL for production. Ensure the HTTP Method is set to POST.
Prerequisites include Node.js v18 or later, Yarn v1.x, a Plivo account, a Meta Business Manager account, a phone number for WhatsApp registration, and a basic understanding of RedwoodJS, GraphQL, and Node.js.
Validating Plivo webhook signatures is critical for security. Use the X-Plivo-Signature-V3 and X-Plivo-Signature-V3-Nonce headers, the request URL, and the request body along with your Plivo Auth Token to verify that incoming requests originate from Plivo. Refer to the Plivo documentation for the most up-to-date validation method.
Prisma is used as the Object-Relational Mapper (ORM) in RedwoodJS, enabling convenient interaction with your database. It simplifies database operations, such as creating, reading, updating, and deleting records.
Store your Plivo AUTH_ID, AUTH_TOKEN, and PLIVO_WHATSAPP_NUMBER as environment variables in a .env file in the root of your project. This file should be added to your .gitignore to prevent committing sensitive information.
Create WhatsApp message templates in your Meta Business Manager under WhatsApp Manager -> Message Templates. You'll need to categorize them and submit them for approval by Meta before you can use them in your application.
WhatsApp message templates are crucial for initiating conversations with users or sending messages outside the 24-hour customer service window. Using pre-approved templates ensures compliance with WhatsApp Business API guidelines.
Integrate Plivo's WhatsApp Business API into your RedwoodJS application with this comprehensive tutorial. Learn how to send WhatsApp messages (including approved template messages), receive inbound messages via webhooks, and build a complete messaging system using GraphQL, Prisma, and Node.js 20. This integration enables businesses to leverage WhatsApp's 2+ billion users for customer communication, notifications, support, and engagement.
What You'll Build:
Time Estimate: 2–3 hours Skill Level: Intermediate (requires Node.js, GraphQL, and API experience)
Technologies Used:
System Architecture:
Flow:
Prerequisites:
ngrokor similar tunneling service for local webhook development. This is needed to expose your local RedwoodJS API server (running on port 8911 typically) to the public internet, allowing Plivo's webhook service to reach it. For production deployments, replace thengrokURL with your application's stable public URL.Cost Considerations:
Plivo charges per message sent/received. WhatsApp Business API pricing varies by country and message type (template vs. session messages). Review Plivo's WhatsApp Pricing and Meta's WhatsApp Business Pricing before deploying to production.
1. Set Up Your RedwoodJS Project
Create a new RedwoodJS project and install the required dependencies.
Create RedwoodJS App: Open your terminal and run:
Follow the prompts (choose TypeScript or JavaScript). This guide uses TypeScript syntax where applicable, but concepts are the same for JavaScript. TypeScript is recommended for improved type safety and IDE support.
Install Plivo SDK: Navigate to the API workspace and add the Plivo Node.js SDK:
Current SDK version: 4.x (verify compatibility with your Node.js version). Check Plivo Node.js SDK Releases for updates.
Configure Environment Variables: Store your Plivo authentication credentials (
AUTH_IDandAUTH_TOKEN) and registered WhatsApp number securely in environment variables.Create a
.envfile in your project root:Add the following variables to
.env. Find yourAUTH_IDandAUTH_TOKENon the Plivo Console dashboard (https://console.plivo.com/dashboard/).Important: Add
.envto your.gitignorefile to prevent committing secrets. RedwoodJS's default.gitignoreusually includes this.Validate Environment Variables: Add startup validation in
api/src/lib/env.ts:Purpose of Variables:
PLIVO_AUTH_ID/PLIVO_AUTH_TOKEN: Used to authenticate requests to the Plivo API. Treat these like passwords.PLIVO_WHATSAPP_NUMBER: The source phone number registered with Plivo/WhatsApp for sending messages. Must be in E.164 format.RedwoodJS Project Structure: Familiarize yourself with the key directories:
api/: Backend code (GraphQL API, services, functions, database).api/src/functions/: Serverless functions (like our webhook).api/src/services/: Business logic, interacts with database and external APIs (like Plivo).api/src/graphql/: GraphQL schema definitions.api/src/lib/: Shared library code (database client, logger).api/db/: Database schema (schema.prisma) and migrations.web/: Frontend code (React components, pages, layouts).2. Connect Your WhatsApp Business Account to Plivo
Connect your WhatsApp Business Account (WABA) to Plivo before writing code. This section covers the official WhatsApp Business API setup process through Plivo's Meta Solution Provider integration.
Plivo Account & Credits: Ensure your Plivo account is created and funded. New accounts receive $10 in trial credits for testing. Review Plivo Pricing for production costs.
Connect WABA to Plivo: Follow Plivo's onboarding guide: Plivo's WhatsApp API: Onboarding Made Simple
WhatsApp Accounts > Partners. Plivo should be listed.Common Troubleshooting:
Create WhatsApp Message Templates (Crucial for Initiating Conversations): WhatsApp requires businesses to use pre-approved message templates to initiate conversations with users or send messages outside the 24-hour customer service window.
{{1}},{{2}}) for dynamic content and media headers.Sync Templates from WhatsAppto make them available via the Plivo API. Note the exactnameandlanguagecode (e.g.,order_confirmation,en_US) of your approved templates.Template Best Practices:
Example Template Structures:
Configure Plivo Webhook for Incoming Messages: To receive messages in RedwoodJS, Plivo needs an endpoint to send data to.
ngrok.ngrok:ngrok http 8911(RedwoodJS API typically runs on 8911).ngrok(e.g.,https://<random_string>.ngrok.io).https://<random_string>.ngrok.io/api/whatsappWebhook.POST.Security Considerations:
Alternative Tunneling Options:
3. Implement WhatsApp Message Sending and Receiving
Create a RedwoodJS service to handle sending messages and a function to handle incoming webhooks.
A. Sending WhatsApp Messages
Generate Service: Create a service to encapsulate Plivo interactions.
This creates
api/src/services/whatsapp/whatsapp.tsand associated test/scenario files.Implement Sending Logic: Open
api/src/services/whatsapp/whatsapp.tsand add the following:B. Receiving WhatsApp Messages (Webhook)
Generate Function: Create a RedwoodJS function to handle incoming POST requests from Plivo.
This creates
api/src/functions/whatsappWebhook.ts.Implement Webhook Logic: Open
api/src/functions/whatsappWebhook.tsand add the following:Explanation:
AUTH_TOKEN. The code uses theX-Plivo-Signature-V3andX-Plivo-Signature-V3-Nonceheaders along with the request URL and body. Usescrypto.timingSafeEqualfor secure comparison.application/x-www-form-urlencoded. The code parses this string into a JavaScript object.MediaUrl0andMediaContentType0parameters. Add media download/storage logic as needed.From,To,Text,MessageUUID). Add your application-specific logic (saving to DB, triggering replies, etc.).200 OKstatus to Plivo to acknowledge receipt.4. Building the API Layer (GraphQL)
Expose the sending functionality through RedwoodJS's GraphQL API for easy frontend integration.
Define GraphQL Schema: Open
api/src/graphql/whatsapp.sdl.ts(create if it doesn't exist) and define mutations for sending messages:@requireAuth: Ensures only authenticated users can call these mutations. Set up RedwoodJS auth if you haven't (RedwoodJS Auth Docs).Implement Resolvers: RedwoodJS maps GraphQL types/mutations to service functions. Add the resolver logic within
api/src/services/whatsapp/whatsapp.ts:Testing with GraphQL Playground:
Run your RedwoodJS dev server:
yarn rw devAccess the GraphQL Playground (usually
http://localhost:8911/graphql).You'll need to handle authentication (e.g., pass an auth token in headers).
Example
curl(replace placeholders and add auth header):Send Text:
Send Template (Example: order confirmation – structure depends on your template):
5. Database Schema (Prisma)
Define the database model to store WhatsApp messages for tracking and analytics.
Update Prisma Schema: Open
api/db/schema.prismaand add the WhatsAppMessage model:Run Migrations: Create and apply the database migration:
6. Deployment
Deploy your RedwoodJS WhatsApp integration to production with these platform-specific guides.
Deployment Checklist:
Environment Variables: Set production values for
PLIVO_AUTH_ID,PLIVO_AUTH_TOKEN,PLIVO_WHATSAPP_NUMBER, andDATABASE_URLin your deployment platform.Update Webhook URL: Replace ngrok URL in Plivo Console with your production domain (e.g.,
https://your-app.com/api/whatsappWebhook).Database Migration: Run Prisma migrations in production:
Deploy Options:
Monitoring & Observability:
Testing Strategy:
Example test for sendWhatsAppText:
Frequently Asked Questions
What Node.js version do I need for Plivo WhatsApp integration with RedwoodJS?
You need Node.js 20.x (LTS Active until October 2026, Maintenance until April 2027). RedwoodJS requires Node.js =20.x. Node.js 21+ may cause compatibility issues with some deployment targets like AWS Lambdas. Node.js 22.x is also supported but verify compatibility with your specific deployment environment before using it.
Do I need a WhatsApp Business Account (WABA) to use Plivo's WhatsApp API?
Yes. You must have an active WhatsApp Business Account (WABA) mapped to Plivo. You'll need a Meta Business Manager account with admin access to create and configure the WABA. Plivo is a registered Meta Solution Provider, making the integration process streamlined through their embedded signup flow.
Can I send free-form messages to any WhatsApp user?
No. WhatsApp requires businesses to use pre-approved message templates to initiate conversations or send messages outside the 24-hour customer service window. Once a user messages you first, you have a 24-hour window to send free-form text messages. After this window closes, you must use approved templates. The 24-hour window resets each time the user sends you a new message.
How do I create and approve WhatsApp message templates?
Create templates in your Meta Business Manager → WhatsApp Manager → Message Templates. Choose appropriate categories (Marketing, Utility, Authentication) and include placeholders for dynamic content. Submit templates for approval (takes up to 24 hours). Once approved in Meta, sync them to Plivo Console → Messaging → WhatsApp Templates → Sync Templates from WhatsApp.
How does RedwoodJS handle incoming WhatsApp messages from Plivo?
Plivo triggers a webhook POST request to your RedwoodJS API function endpoint when messages arrive. Create a serverless function at
api/src/functions/whatsappWebhook.tsthat validates Plivo's signature (V3), processes the message data, saves it to your Prisma database, and triggers any additional business logic you define.What database options work with this RedwoodJS WhatsApp integration?
You can use any database supported by Prisma ORM (v6.16.3 current), including PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB, and CockroachDB. RedwoodJS uses Prisma by default for database access, providing type-safe queries and automatic migrations.
How do I test webhooks locally during development?
Use
ngrokor similar tunneling service to expose your local RedwoodJS API server (port 8911) to the public internet. Runngrok http 8911, copy the HTTPS forwarding URL, and configure it in Plivo Console → Messaging → WhatsApp Numbers → Message URL ashttps://<random_string>.ngrok.io/api/whatsappWebhook.How do I secure my Plivo WhatsApp webhook in RedwoodJS?
Implement Plivo signature validation (V3) in your webhook function. Plivo sends a signature in the
X-Plivo-Signature-V3header. Compute an HMAC-SHA256 hash of the webhook URL concatenated with the nonce and request body using yourAUTH_TOKENas the key. Compare this computed signature with the received signature usingcrypto.timingSafeEqualto verify authenticity before processing messages.How do I handle message delivery status tracking?
Configure a status callback URL in Plivo Console or when sending messages. Create a separate webhook function to handle delivery status updates. Plivo sends status events (sent, delivered, failed, read) to this endpoint. Update your database records based on these status callbacks.
How do I scale my WhatsApp integration for high message volumes?
Implement these production optimizations:
How do I ensure GDPR compliance for message storage?
Implement these privacy best practices:
Common error codes and troubleshooting
PLIVO_AUTH_IDandPLIVO_AUTH_TOKENAUTH_TOKENand URL construction