Frequently Asked Questions
Integrate the Plivo Node.js SDK and use the provided methods within the Plivo service to send various WhatsApp messages. You'll need a Plivo account, WhatsApp-enabled number, and approved templates for business-initiated conversations. The code examples demonstrate sending templated, text, media, and interactive messages via function calls handling the Plivo API interaction details.
The Plivo Node.js SDK simplifies interaction with the Plivo communications API. It provides convenient functions for sending messages, making API calls, and managing other communication tasks within your NestJS application, abstracting away low-level details.
WhatsApp enforces pre-approved message templates for business-initiated conversations to prevent spam and unwanted messages. Businesses must submit templates for review and approval by WhatsApp before sending initial outbound messages to customers. Text, media, and interactive messages are allowed only in the 24-hour response window following a customer-initiated message.
WhatsApp template messages are required for any business-initiated conversations outside the 24-hour customer service window. They are essential for sending notifications, alerts, or initiating contact where the user hasn't messaged your business first.
Set up a webhook endpoint in your NestJS application to receive incoming WhatsApp messages. Configure Plivo to send webhook notifications to this endpoint. Then implement request handling logic to process incoming message data.
Obtain Plivo credentials (Auth ID and Auth Token) from the Plivo console, install the Plivo Node.js SDK (npm install plivo), initialize a Plivo client, and use the client's methods to send and receive WhatsApp messages via the API.
The example project creates a modular structure with a dedicated plivo module containing a service for Plivo interactions and a whatsapp module with a controller for handling endpoints. This design promotes code organization and separation of concerns.
Use NestJS's ConfigModule along with the dotenv package to load environment variables. Store sensitive credentials like your Plivo Auth ID, Auth Token, and WhatsApp Sender Number in a .env file, ensuring this file is not committed to version control.
Validate the Plivo webhook signature to ensure requests are genuinely from Plivo. Use plivo.validateV3Signature to validate against the signature and nonce provided in the X-Plivo-Signature-V3 and X-Plivo-Signature-V3-Nonce headers of the webhook requests.
Yes, the Plivo API supports sending various WhatsApp message types, including templated messages, free-form text and media messages (images, videos, documents), and interactive messages with buttons, lists, and call-to-actions. The provided tutorial shows how to send different message types using functions like sendWhatsAppTemplate, sendWhatsAppText, sendWhatsAppMedia, and sendWhatsAppInteractive.
Implement proper error handling using try-catch blocks around Plivo API calls. Handle Plivo-specific errors, such as invalid numbers or unapproved templates. Consider creating custom exception filters in NestJS to handle and format error responses consistently.
Use the sendWhatsAppText function after initializing the Plivo client. Ensure free-form messages are sent only as replies within a 24-hour window initiated by the user. Provide the destination number and message text as parameters.
The key components are the user/client application, the NestJS backend application, the Plivo API, and the WhatsApp network. Data flows from the user to your backend, then to Plivo, and finally to WhatsApp. Webhooks from Plivo notify your backend about message status updates and incoming messages.
Use a tool like ngrok to create a secure tunnel that exposes your local development server to the internet. This allows Plivo webhooks to reach your application during testing. Configure the BASE_URL in your .env file to match the ngrok URL.
Learn how to integrate Plivo WhatsApp API with NestJS to build a production-ready messaging backend. This comprehensive tutorial covers everything from sending WhatsApp Business messages to handling incoming webhooks with signature validation.
You'll build a fully functional NestJS WhatsApp integration that:
This guide assumes you're familiar with Node.js and basic NestJS concepts.
How to Integrate Plivo WhatsApp with NestJS: Project Overview
Goal: Build a reliable NestJS backend service that sends and receives WhatsApp messages via the Plivo API. This integration works seamlessly with customer support platforms, notification systems, chatbots, and other business applications requiring WhatsApp Business API functionality.
Problem Solved: Manage WhatsApp communications programmatically in a structured, scalable, and maintainable way. The service abstracts Plivo API complexities within a dedicated NestJS module.
Technologies Used:
System Architecture:
Prerequisites:
npm install -g @nestjs/cli1. Setting Up Your NestJS Project for Plivo WhatsApp
Initialize your NestJS project and install the Plivo SDK and required dependencies to enable WhatsApp messaging functionality.
Step 1: Create a New NestJS Project
Open your terminal and run:
This creates a standard NestJS project structure.
Step 2: Install Dependencies
Install the Plivo Node.js SDK and NestJS configuration module:
plivo: Official Plivo SDK for Node.js@nestjs/config: Environment variables and configuration managementdotenv: Loads environment variables from.envintoprocess.envStep 3: Configure Environment Variables
Create a
.envfile in the project root directory:Important:
YOUR_PLIVO_AUTH_IDandYOUR_PLIVO_AUTH_TOKENwith your actual Plivo console credentials+14155551234with your WhatsApp-enabled Plivo number in E.164 format.envto version control. Add.envto your.gitignorefileStep 4: Setup Configuration Module
Modify
src/app.module.tsto load and manage environment variables using@nestjs/config:ConfigModule.forRoot({ isGlobal: true_ envFilePath: '.env' }): Loads the.envfile and makes configuration accessible throughout the application viaConfigService.Project Structure (Initial):
Your project structure should now look something like this:
2. Creating the Plivo WhatsApp Service in NestJS
Create a dedicated NestJS module and service to encapsulate all Plivo WhatsApp API interactions. This modular approach promotes code reusability and follows NestJS best practices for dependency injection.
Step 1: Generate the Plivo Module and Service
Use the NestJS CLI to generate the module and service files:
This creates
src/plivo/plivo.module.tsandsrc/plivo/plivo.service.ts.Step 2: Implement the Plivo Service
Open
src/plivo/plivo.service.tsand implement the Plivo client initialization:ConfigServiceto access environment variablesOnModuleInitinitializes the Plivo client when the module loadsPLIVO_AUTH_ID,PLIVO_AUTH_TOKEN, andPLIVO_WHATSAPP_SENDER_NUMBERfrom configurationgetPlivoClient()andgetSenderNumber()provide access to the initialized client and sender number with availability checksStep 3: Configure the Plivo Module
Open
src/plivo/plivo.module.tsand ensure the service is provided and exported:Remember we already imported
PlivoModuleintoAppModulein the previous section.3. Sending WhatsApp Messages with Plivo in NestJS
Implement a controller and service methods to send various types of WhatsApp Business messages including templates, text, media, and interactive messages through the Plivo API.
Step 1: Generate the WhatsApp Module and Controller
This creates
src/whatsapp/whatsapp.module.tsandsrc/whatsapp/whatsapp.controller.ts.Step 2: Configure the WhatsApp Module
Open
src/whatsapp/whatsapp.module.tsand import thePlivoModule:Remember we already imported
WhatsappModuleintoAppModule.Step 3: Install Validation Dependencies
Use DTOs (Data Transfer Objects) with decorators to validate incoming request bodies.
Step 4: Enable Global Validation Pipe and Raw Body Support
Enable automatic validation for all incoming requests and configure raw body access for webhook signature validation in
src/main.ts:rawBody: truewhen creating the application. This is required for Plivo webhook signature validation usingplivo.validateV3Signature(). See NestJS raw body documentation for detailsValidationPipeautomatically validates incoming data against DTOsapp.enableCors()PORTor defaults to 3000Step 5: Create DTOs for Sending Messages
Create a directory
src/whatsapp/dtoand add the following DTO files:Step 6: Add Sending Methods to PlivoService
Now, add the methods to
src/plivo/plivo.service.tsto handle the actual API calls using the Plivo client.client.messages.create()methodtry...catchStep 7: Implement Controller Endpoints
Open
src/whatsapp/whatsapp.controller.tsand define the API endpoints that will use thePlivoService.WhatsApp Business Message Templates: A Complete Guide
WhatsApp Business API requires pre-approved message templates for business-initiated conversations outside the 24-hour customer service window. Understanding these templates is essential for proper implementation and cost optimization.
Meta categorizes templates into three types, each with different pricing and use cases:
Template Categories (Meta documentation):
Utility Templates: Used for specific transaction or account updates (order confirmations, shipping notifications, appointment reminders, account alerts). These messages provide important information users have opted to receive.
Authentication Templates: Used for one-time passwords (OTP) and two-factor authentication. These must include security disclaimers and are typically the lowest cost option.
Marketing Templates: Used for promotional content, offers, announcements, newsletters, and other marketing communications. These have higher pricing and stricter approval requirements.
Template Creation: Create templates via WhatsApp Manager or the Plivo console. Meta must approve templates before use – this typically takes a few hours but can take up to 24 hours.
Important Notes:
parametersarrayWhatsApp Pricing Model (Updated July 2025)
As of July 1, 2025, WhatsApp transitioned from conversation-based pricing to a per-message pricing model. This significantly changed how businesses are charged for WhatsApp communications.
Key Pricing Changes:
Per-Message Billing: Each template message delivered is charged based on:
24-Hour Customer Service Window: When a customer messages your business, a 24-hour window opens. During this period:
72-Hour Free Entry Point: Messages from Click-to-WhatsApp Ads or Facebook Page buttons open a 72-hour free window for all message types (you must respond within 24 hours for the window to activate).
No More Free Tier: The previous 1,000 free conversations per month no longer exists.
Pricing Examples (USD, effective October 2025):
Source: Gallabox Per-Message Pricing Documentation
Cost Optimization Best Practices:
Plivo WhatsApp NestJS Integration: Frequently Asked Questions
How do I send WhatsApp messages with Plivo in NestJS?
To send WhatsApp messages with Plivo in NestJS: Install the Plivo Node.js SDK (
npm install plivo), create a PlivoService that initializes the client with your Auth ID and Token, then useclient.messages.create()withtype: 'whatsapp'parameter. Inject the PlivoService into your controller using NestJS dependency injection and call your service methods from API endpoints.What is the WhatsApp 24-hour conversation window and how does it work?
The WhatsApp 24-hour conversation window is a policy that allows businesses to send free-form messages (text, media, interactive) only within 24 hours after a user initiates contact or replies. Outside this window, you must use pre-approved message templates to start new conversations. As of July 2025, utility templates are free within this window, while marketing and authentication templates are always charged.
How do I validate Plivo webhook signatures in NestJS for WhatsApp messages?
To validate Plivo webhook signatures in NestJS, call Plivo's
validateV3Signature()function with the raw request body, nonce fromX-Plivo-Signature-V3-Nonceheader, signature fromX-Plivo-Signature-V3header, full webhook URL, and your Auth Token. You must preserve the raw body by settingrawBody: trueinNestFactory.create()options inmain.ts. This HMAC-SHA256 validation ensures webhooks are authentic and from Plivo. See the NestJS raw body documentation for implementation details.What types of WhatsApp messages can I send with Plivo API?
Plivo WhatsApp API supports multiple message types including: templated messages for business-initiated conversations, plain text messages, media messages (images, videos, documents, audio files), interactive messages with quick reply buttons, selection lists, and call-to-action URLs, plus location messages. All message types work through the WhatsApp Business API and require proper authentication.
Do I need a WhatsApp Business Account to use Plivo WhatsApp API?
Yes, you need a WhatsApp Business Account (WABA) to use Plivo WhatsApp API. First, purchase a Plivo phone number, then enable it for WhatsApp messaging in the Plivo console under Messaging → WhatsApp → Senders. Link this number to your WhatsApp Business Account following Plivo's onboarding process. You must also create and get Meta approval for message templates before sending business-initiated messages outside the 24-hour window.
How do I handle incoming WhatsApp messages in NestJS with Plivo?
To handle incoming WhatsApp messages in NestJS: Create a webhook endpoint (e.g.,
/whatsapp/webhook/incoming) decorated with@Post()that accepts POST requests from Plivo. Validate the webhook signature usingplivo.validateV3Signature()with the raw request body, parse the payload to extract message content and type (text, media, interactive reply, location), then implement your business logic to process and respond to messages. Always return HTTP 200 OK quickly to prevent webhook retries.What's the difference between template and free-form WhatsApp messages?
Template messages use pre-approved formats with placeholders and initiate conversations outside the 24-hour window. Free-form messages allow custom text, media, and interactive elements but can only be sent as replies within active conversation windows.
How much does it cost to send WhatsApp messages through Plivo?
As of July 1, 2025, WhatsApp charges per message delivered rather than per conversation. Messages within the 24-hour customer service window are free (including utility templates). Template pricing varies by country and category (utility, authentication, marketing), ranging from $0.0016 to $0.1570+ per message. See the pricing section for detailed rates.
What are the character limits for WhatsApp messages?
According to Plivo's documentation:
Related Resources