WhatsApp API Integration: Complete Developer Guide
Integrating WhatsApp Business API means connecting your backend, CRM or website to a REST API and webhook set, so your systems can send template and session messages and receive delivery, read and reply events back automatically - rather than a person managing chats manually.
This page is the implementation guide: prerequisites, authentication, sending and receiving messages, webhooks, error handling, connecting to your CRM or store, and what to check before going to production. For what WhatsApp Business API is and does at a product level, see WhatsApp Business API.
On this page:
Integration architecture, prerequisites and authentication
Sending, receiving, webhooks, media, errors and retries
CRM, website, ecommerce and chatbot integration patterns
Testing, production deployment, troubleshooting and FAQs
How Do You Integrate WhatsApp Business API?
WhatsApp API integration is the process of connecting your application - a backend, CRM or website - to WhatsApp Business API so it can send and receive messages programmatically. In practice that means: getting verified account and API credentials, having your message templates approved, writing the code that calls the API to send, and configuring a webhook so delivery and reply events flow back into your systems. The sections below walk through each part.
WhatsApp API Integration Architecture
Two flows run in opposite directions: sending a message out, and receiving events back in.
Sending a message
Frontend / CRMYour BackendWhatsApp APIWhatsApp InfrastructureCustomer
Receiving events
WhatsAppWebhookYour BackendCRM / Dashboard
What You Need Before Integration
Business Account Requirements
A verified WhatsApp Business profile connected to your Teleopedia account through the onboarding flow, before any messages can be sent.
API Credentials
A bearer token/API key generated from your dashboard under Settings → API Keys, used to authenticate every request.
Phone Number Setup
A phone number dedicated to WhatsApp Business messaging, verified during onboarding - it can't run on a personal WhatsApp account at the same time.
Message Templates
Utility, marketing and authentication templates drafted and submitted for approval before you send your first business-initiated message.
Authentication & Sending Messages
Every request is authenticated with a bearer token in the header, alongside a JSON body describing the message:
POST /whatsapp/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"to": "+919876543210",
"type": "template",
"template_name": "order_confirmation",
"params": ["Rohan", "#BL123456", "3-5 Aug"]
}The response confirms the message was accepted and returns an ID to track it:
{
"message_id": "wa_9f1c2e",
"status": "queued",
"channel": "whatsapp"
}Receiving Messages & Webhooks
Configure a webhook URL in your dashboard, and every event - delivery status, read receipts and inbound customer replies - is posted to it as it happens, instead of your application polling the API:
{
"message_id": "wa_9f1c2e",
"channel": "whatsapp",
"status": "delivered",
"timestamp": "2026-09-20T10:42:00Z"
}Delivery/Read Status & Media Messages
Every message moves through a status lifecycle your webhook can track:
Sent
Accepted by WhatsApp and handed off for delivery.
Delivered
Reached the recipient’s device.
Read
Opened by the recipient, subject to their read-receipt setting.
Failed
Could not be delivered - your webhook carries the reason.
Beyond plain text and templates, the API supports images, video, documents, location, and interactive buttons or list messages - each sent the same way, as a different type in the message payload.
Building A WhatsApp Integration Right Now?
Get sandbox access, endpoint reference and hands-on help from our team.
Error Handling, Retry Strategy & Rate Limiting
A failed webhook status generally falls into one of a few categories - an unapproved or edited template, a session message sent outside the active conversation window, an invalid or opted-out number, or unsupported media. Handle these in your application logic rather than only logging them:
Retry transient failures; don't blindly retry a rejected template or invalid number
Branch on the failure reason from the webhook event before deciding what to do next
Trigger a configured fallback to another channel where one exists, rather than a silent failure
Default rate limits depend on your plan and channel - standard plans start at a base requests-per-second throughput per channel, with higher limits available for enterprise accounts. Queue sends client-side if you expect to burst past your current limit, and contact your account team to raise it if needed.
Security
API Key Handling
Store keys securely, avoid committing them to source control, and rotate periodically.
Webhook Verification
Validate that incoming webhook payloads genuinely originate from the platform before trusting them.
Rate Limiting Your Own Endpoints
Protect your webhook endpoint from being overwhelmed during high-volume sends.
Integrating With Your Systems
The same API and webhooks power every one of these integration patterns.
CRM Integration
Connect messaging to a CRM or helpdesk your team already uses - see Integrations for supported tools.
Website Integration
Trigger a WhatsApp send from a backend event on your website - a form submission, a signup, a cart action.
Ecommerce Integration
Order, payment and shipping events on your store trigger template messages directly from your backend.
Chatbot Integration
A no-code flow builder handles FAQs, order tracking and lead capture without custom bot-hosting infrastructure.
AI Chatbot Integration
Automated replies handle routine queries and hand off to a human agent when a conversation needs one.
See Integrations for the current list of pre-built connections.
Analytics
Sent, delivered, read and failed counts per campaign or template are available from your dashboard, so you don't need to build reporting from raw webhook events alone - though your own database can still store them for deeper, custom analysis.
Testing & Production Deployment
Testing
Request sandbox access to test your integration - sending, webhooks and template rendering - against test numbers before any real customer receives a message.
Production Deployment
Before switching to your live API key, confirm every template you'll use is approved, your webhook endpoint is publicly reachable, and monitor your first real sends closely for delivery issues.
Common Integration Errors & Troubleshooting
| Symptom | Likely Cause | What To Check |
|---|---|---|
| Template message rejected or not sending | Template not yet approved, or edited after approval | Compare the submitted template exactly against what your code is sending, including variable structure |
| Authentication/401 error on every request | Invalid, expired or revoked API key | Regenerate the key from your dashboard and confirm it's in the Authorization header correctly |
| Message accepted but never delivered | Invalid or inactive number, or recipient not on WhatsApp | Verify the number format (with country code) and whether the number is WhatsApp-active |
| Webhook not receiving any events | Webhook URL not publicly reachable, or misconfigured in the dashboard | Confirm the URL is live, returns a success response, and matches what's configured in Settings |
| Session message fails outside a template | Sent outside the 24-hour customer-initiated conversation window | Use an approved template instead of a free-form session message |
| Media message fails to send | Unsupported file format, or file over the size limit for its type | Check the media type and size against supported limits before sending |
| Requests start failing under load | Sending faster than your plan's rate limit | Check your plan's requests-per-second limit and queue sends client-side if needed |
WhatsApp API Integration FAQs
How do you integrate WhatsApp Business API?
At a high level: get a verified WhatsApp Business profile and API credentials, submit message templates for approval, connect your backend to the REST API for sending, and configure a webhook to receive delivery, read and inbound-reply events - covered step by step on this page.
What do I need before I start integrating WhatsApp API?
A verified WhatsApp Business account, API credentials from your dashboard, a dedicated phone number, and at least one approved message template for your first send - see the prerequisites checklist on this page.
How is a WhatsApp API request authenticated?
Every request includes a bearer token, generated from your dashboard, in the Authorization header, alongside a JSON body describing the recipient and message.
Can I use my existing WhatsApp number for the API?
A number used for WhatsApp Business API can't simultaneously run on the personal WhatsApp app - it needs to be verified specifically for API/business use during onboarding.
How do I receive incoming WhatsApp messages in my application?
Configure a webhook URL in your dashboard - inbound customer replies arrive as events on the same webhook that reports delivery and read status, so your backend can route them into a CRM, dashboard or support queue.
How do I track delivery and read status?
Every message returns a message ID, and sent, delivered, read and failed events for that ID are sent to your configured webhook in real time, and also shown in the dashboard.
What media types can I send through the WhatsApp API?
Images, video, documents, location, and interactive buttons or list messages, alongside plain text and template messages.
Why did my WhatsApp template message get rejected?
Usually because the template isn't approved yet, or the wording/variable structure sent by your code doesn't exactly match what was submitted for approval - templates need to stay consistent after approval.
What should my retry strategy look like for failed messages?
Retry transient delivery failures, but avoid blindly retrying a rejected template or an invalid number - branch on the failure reason from the webhook event and fall back to another channel where one is configured.
Is there a rate limit on the WhatsApp API?
Yes - default rate limits depend on your plan and channel, with standard plans starting at a base requests-per-second throughput. Contact your account team to raise limits for higher-volume sending.
How do I integrate WhatsApp API with my CRM?
Through platform integrations - see Integrations for CRM and helpdesk tools that connect directly, or use the REST API and webhooks to build a custom connection.
Can I trigger WhatsApp messages from my ecommerce store?
Yes - order, payment and shipping events on your store's backend can call the API directly to send the relevant template the moment the event happens.
Does WhatsApp API integration support chatbots?
Yes, through a no-code flow builder for FAQs and order tracking, and AI-assisted automated replies that hand off to a human agent when needed.
Is there a sandbox for testing before going live?
Yes - request API access to get a sandbox environment for testing integrations, alongside your live credentials, before sending to real customers.
What should I check before deploying to production?
Confirm your templates are approved, your webhook endpoint is publicly reachable and verified, your API key is the live (not sandbox) credential, and monitor your first real sends closely for delivery issues.
What's the most common WhatsApp API integration error?
Template mismatches - sending content that doesn't exactly match what was approved - and webhook misconfiguration are the two most common issues teams run into first. See the troubleshooting table on this page.
How is this page different from the WhatsApp Business API page?
WhatsApp Business API covers what the product is and does. This page is the implementation guide - the concrete steps, code patterns and troubleshooting for actually building the integration.
Ready to unify your business communication?
Most businesses are live on their own branded panel within days, not months - talk to our team today and see how fast you can start sending.