WhatsApp API
Integration
Send WhatsApp messages from your website, app or CRM with one HTTPS call. Approved templates, replies inside the 24-hour window and utility Direct Send, with delivered, read and reply events on your webhook. Ready code in PHP, Python, Node.js, Java and C#.
- Same API key as SMS
- No Meta developer app needed
- Read receipts on webhook
- Failed messages refunded
What is WhatsApp API integration?
WhatsApp API integration connects your own software to the official WhatsApp Business API, so messages go out the moment something happens in your system. An order ships, a payment comes in, an appointment is booked, an OTP is needed: your server makes one HTTPS request to Fast2SMS with the customer's number and an approved template, and the message reaches the customer's WhatsApp from your verified business number.
Working with the WhatsApp Business API directly means building a Meta developer app, managing access tokens, handling Graph API calls and parsing Meta webhooks. With Fast2SMS you skip that. You connect your number in the panel with Facebook login, get templates approved there, and your code calls a few simple endpoints with one API key. The same key and wallet also send SMS, RCS and voice calls.
This page is the WhatsApp developer guide: the three send APIs, every field, copy-ready code, responses, delivery status and webhooks. For an overview of all channels see the Fast2SMS API page, and for the product itself see the WhatsApp Business API page. The full reference with a try-it panel is at docs.fast2sms.com.
WhatsApp API integration in five steps
Most of the wait is template approval. The code itself takes minutes.
- 1
Create a free account
Sign up at Fast2SMS and copy your API key from the API Key page in the panel. One key works for SMS, WhatsApp, RCS and voice calls.
- 2
Connect your WhatsApp number
Onboard a new number, or your existing WhatsApp Business app number, with Facebook login in the panel. Onboarding is free and our team helps you through it.
- 3
Get a template approved
Create a marketing, utility or authentication template in WhatsApp Manager. Meta reviews it. Each approved template gets a message_id in the panel.
- 4
Send a test message
Call /dev/whatsapp with the message_id, your phone_number_id and your own mobile number. Save the request_id that comes back; it starts with W.
- 5
Add a webhook
Create a WhatsApp webhook so sent, delivered, read and failed updates and customer replies reach your server with your udf values.
Three ways to send a WhatsApp message
Pick by who starts the conversation and what you want to say. All three use the same API key, the same numbers and the same wallet.
Template API
Start a conversation at any time with an approved template: order updates, OTPs, reminders and offers.
- Needs an approved template
- One or many numbers per call
- Marketing, utility or authentication rate
Session API
Reply in your own words while the 24-hour customer service window is open, after the customer writes to you.
- No template needed
- Text, image, video, audio, document, sticker, location, reaction
- Service rate
Direct Send API
Send a utility message, such as an order update, without creating a template first. Meta builds the template in the background.
- Utility content only
- Numbers with a 100K or unlimited messaging limit
- Utility rate
Template API endpoint and fields
GET or POST https://www.fast2sms.com/dev/whatsapp with the header authorization: YOUR_API_KEY. POST takes a JSON body.
| Field | Needed | Rule |
|---|---|---|
authorization | Always | Your API key. Send it as a header. On a GET call it can also be a query parameter, but a header keeps it out of logs. |
message_id | Always | The Fast2SMS ID of an approved template, shown in WhatsApp Manager under Templates. Only approved templates send. |
numbers | Always | One or more Indian mobile numbers, comma separated: 10 digits starting with 6 to 9. A +91 or 91 in front is removed for you. |
phone_number_id | Optional | Which connected WhatsApp number sends the message. Copy it from WhatsApp Manager under Numbers. |
variables_values | If the template has variables | Values for the template variables in order, separated by a pipe: Rahul|4821. Up to 1,000 characters in total. |
media_url | If the template has a media header | A public http or https link. JPG or PNG images up to 5 MB, MP4 video up to 16 MB, PDF up to 100 MB. |
document_filename | Optional | The file name the customer sees on a PDF header, such as Invoice-4821.pdf. |
schedule_time | Optional | Send later: a Unix timestamp or a date in DD-MM-YYYY-HH-MM format. It must be in the future. |
udf1, udf2, udf3 | Optional | Your own values, such as an order ID. They come back in the delivery report and the webhook. |
sms_details | Optional | Set to 1 to get the per-message rate, the template category and the amount debited in the response. |
Session API: to (one number), display_number or phone_number_id, type and the fields for that type. Text up to 4,096 characters, captions up to 1,024. Full reference: API documentation.
Send WhatsApp messages with cURL
Replace YOUR_API_KEY, the IDs and the number. Sample values only.
curl -G "https://www.fast2sms.com/dev/whatsapp" \
-H "authorization: YOUR_API_KEY" \
--data-urlencode "message_id=1234" \
--data-urlencode "phone_number_id=109283746561" \
--data-urlencode "numbers=9999999999" \
--data-urlencode "variables_values=Rahul|4821|22 Nov" \
--data-urlencode "udf1=order-4821"
curl -X POST "https://www.fast2sms.com/dev/whatsapp" \
-H "authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message_id":"1235",
"phone_number_id":"109283746561",
"numbers":"9999999999,8888888888",
"variables_values":"INV-4821",
"media_url":"https://example.com/inv/4821.pdf",
"document_filename":"Invoice-4821.pdf"}'
curl -X POST "https://www.fast2sms.com/dev/whatsapp-session" \
-H "authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"phone_number_id":"109283746561",
"to":"9999999999",
"type":"text",
"text":"Yes, reply with the new address."}'
# a document in the same chat
-d '{"phone_number_id":"109283746561",
"to":"9999999999","type":"document",
"url":"https://example.com/menu.pdf",
"document_filename":"Menu.pdf"}'
# send a template at 9 AM on 25 Nov 2026
-d '{"message_id":"1236",
"numbers":"9999999999",
"variables_values":"Rahul",
"schedule_time":"25-11-2026-09-00"}'
# utility message without a template
# POST /dev/whatsapp-direct-send
-d '{"phone_number_id":"109283746561",
"to":"9999999999",
"category":"utility","type":"text",
"text":"Your refund of Rs 499 is processed."}'
WhatsApp API in PHP, Python, Node.js, Java and C#
The same template send in six ways. Read the API key from an environment variable, never from your code or a browser.
$body = [
"message_id" => "1234",
"phone_number_id" => "109283746561",
"numbers" => "9999999999",
"variables_values" => "Rahul|4821|22 Nov",
];
$ch = curl_init("https://www.fast2sms.com/dev/whatsapp");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"authorization: " . getenv("FAST2SMS_API_KEY"),
"Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode($body),
CURLOPT_TIMEOUT => 30,
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $res["request_id"] ?? json_encode($res["errors"] ?? $res);
use Illuminate\Support\Facades\Http;
$res = Http::withHeaders([
"authorization" => env("FAST2SMS_API_KEY"),
])
->timeout(30)
->post("https://www.fast2sms.com/dev/whatsapp", [
"message_id" => "1234",
"phone_number_id" => "109283746561",
"numbers" => "9999999999",
"variables_values" => "Rahul|4821|22 Nov",
"udf1" => "order-4821",
])
->json();
if ($res["return"] ?? false) {
// save $res["request_id"] with the order
}
import os, requests
body = {
"message_id": "1234",
"phone_number_id": "109283746561",
"numbers": "9999999999",
"variables_values": "Rahul|4821|22 Nov",
}
r = requests.post(
"https://www.fast2sms.com/dev/whatsapp",
headers={"authorization":
os.environ["FAST2SMS_API_KEY"]},
json=body, timeout=30)
data = r.json()
print(data["request_id"] if data.get("return")
else data.get("errors"))
const res = await fetch(
"https://www.fast2sms.com/dev/whatsapp", {
method: "POST",
headers: {
authorization: process.env.FAST2SMS_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
message_id: "1234",
phone_number_id: "109283746561",
numbers: "9999999999",
variables_values: "Rahul|4821|22 Nov",
}),
});
const data = await res.json();
console.log(data.return ? data.request_id : data.errors);
import java.net.URI;
import java.net.http.*;
String json = "{\"message_id\":\"1234\","
+ "\"phone_number_id\":\"109283746561\","
+ "\"numbers\":\"9999999999\","
+ "\"variables_values\":\"Rahul|4821|22 Nov\"}";
HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create("https://www.fast2sms.com/dev/whatsapp"))
.header("authorization", System.getenv("FAST2SMS_API_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> res = HttpClient.newHttpClient()
.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
using System.Net.Http;
using System.Text;
var http = new HttpClient();
http.DefaultRequestHeaders.Add("authorization",
Environment.GetEnvironmentVariable("FAST2SMS_API_KEY"));
var json = "{\"message_id\":\"1234\","
+ "\"phone_number_id\":\"109283746561\","
+ "\"numbers\":\"9999999999\","
+ "\"variables_values\":\"Rahul|4821|22 Nov\"}";
var res = await http.PostAsync(
"https://www.fast2sms.com/dev/whatsapp",
new StringContent(json, Encoding.UTF8, "application/json"));
Console.WriteLine(await res.Content.ReadAsStringAsync());
Go and Ruby samples for every channel are on the Fast2SMS API page. Ready requests for each of your approved templates: API Excel in the panel.
Success, errors and what to do
A good request returns at once with a request_id. A bad one returns HTTP 400 with the field names in errors_keys, so your code can tell what to fix.
{
"request_id": "Wa1B2c3D4e5F6g7",
"return": true,
"message": ["Whatsapp Message sent successfully."]
}
# with "sms_details": 1 you also get
# per_sms_rate, category, total_valid_number
# and amount_debited
{
"return": false,
"errors_keys": ["message_id"],
"errors": {
"message_id": [
"WhatsApp Template ID (message_id) is invalid or not approved."
]
}
}
| Error message | Field or code | Fix |
|---|---|---|
| WhatsApp Template ID (message_id) is invalid or not approved. | message_id | Use the message_id of an approved template from WhatsApp Manager, or list them with the template API. |
| WhatsApp Phone Number ID is invalid or not connected. | phone_number_id | Copy the ID of a connected number from WhatsApp Manager under Numbers. The template and number must be on the same WhatsApp account. |
| Mobile Number format is invalid: ... | numbers | Send 10-digit Indian numbers starting with 6 to 9, comma separated. The message lists the numbers it could not read. |
| Media URL is not reachable. Please use a public link. | media_url | Host the file on a public https address. Private or internal addresses are not accepted. |
| Media file is too large. Maximum allowed size for this type is ... MB | media_url | Compress the file: 5 MB for images, 16 MB for video, 100 MB for PDF. |
| Messaging will be available 10 minutes after onboarding. | senderId | A newly connected number needs 10 minutes before it can send. Wait and try again. |
| Insufficient wallet balance, you need at least ₹... | wallet | Recharge the wallet. The message is charged when you send, and failed messages come back to the wallet. |
| Invalid Authentication, Check Authorization Key | 412 | The API key is wrong or missing. Copy it again from the API Key page. |
| IP is blacklisted from Dev API section | 414 | API Security is on and the call came from an IP that is not on your whitelist. Add your server IP. |
Failures that happen after sending, such as a number without WhatsApp, come from WhatsApp itself: WhatsApp API error codes and fixes.
Check delivered and read status when you need it
Webhooks push every update to you, but you can also pull status at any time. All three calls use the same API key in the authorization header.
-
GET /dev/whatsapp/{request_id}: every number in one send, from the last 90 days -
GET /dev/whatsapp_logs?from=&to=: all messages in a date range, up to 3 days per call -
GET /dev/whatsapp_summary?from=&to=: counts per status, up to 30 days per call
Logs and summary reach back up to one year. Each row also carries the category and the amount debited, so you can match the bill to your own records.
| status | Meaning |
|---|---|
pending | Queued with Fast2SMS, not yet handed to WhatsApp |
accepted | WhatsApp accepted the message and is sending it |
sent | WhatsApp sent it; the phone has not confirmed yet |
delivered | It reached the customer's phone |
read | The customer opened it |
failed | It could not be delivered; the reason is in the report and the amount is refunded |
Status updates and customer replies, pushed to your server
Create a WhatsApp webhook in the panel, or with POST /dev/webhook/v2/whatsapp. Choose the events, the method and the body format: JSON, form or XML. Fast2SMS then calls your URL for every change. Return HTTP 200 quickly and do the work afterwards; if your server is down the call is retried and post_attempt counts the tries.
- Events: sent, delivered, read, failed and received
- Customer replies with text, media links and captions
- Your udf1, udf2 and udf3 on every event
- Optional webhook_secret_key header to verify the sender
- Up to 10 webhooks per service
{
"request_id": "Wa1B2c3D4e5F6g7",
"route": "response",
"mobile": "9999999999",
"status": "read",
"status_description": "Read successfully",
"phone_number_id": "109283746561",
"category": "UTILITY",
"udf1": "order-4821",
"post_attempt": 1,
"webhook_type": "status_update"
}
{
"webhook_type": "incoming_message",
"from": "9999999999",
"message_type": "text",
"body": "Can I change the address?"
}
No API fee. Pay per message by category.
API calls, webhooks and the delivery report API are free. Each message you send costs the rate of its category, the same as a message sent from the panel. Meta decides the category when it approves the template. Messages your customers send you are free, and messages that fail are refunded to your wallet automatically. There is no setup fee, no monthly fee and no minimum volume.
- Utility ₹0.25 · Authentication ₹0.25Order updates, alerts and OTPs.
- Marketing ₹0.95Offers, launches and festival messages.
- Service ₹0.13Your replies inside the 24-hour window.
- Incoming free, failed refundedRecharge from ₹100, one wallet for every channel.
Keep it safe and test it properly
Keep the key on your server
Call the API only from your backend and read the key from an environment variable. A key placed in a web page or mobile app can be copied by anyone. If a key leaks, regenerate it in the panel and update your server.
Lock the key to your IPs
Turn on API Security in the panel and whitelist your server IPs. Calls from any other IP then get error 414. Serverless platforms change IP often, so give them a fixed outbound IP first.
Test with your own number
Send each template to your own WhatsApp first and check the request_id in Delivery Report under WhatsApp, where API sends are marked (api). Then point the webhook at a test URL and watch the delivered and read events arrive.
Store request_id and udf values
Save the request_id with the order or customer, and pass your own order ID in udf1. Every status update and report row then matches your records without extra lookups.
Check variables before sending
Send variables_values in the same order as the template, separated by pipes, and keep the total under 1,000 characters. A missing value is the most common reason a message reads oddly.
Handle failures in code
Read errors_keys on a 400 response and fix the named field. For messages that fail after sending, read the reason in the webhook and decide whether to try SMS through the SMS API with the same key.
WhatsApp API vs Bulk WhatsApp panel
Same numbers, same templates, same wallet and the same price. Pick by the job.
| WhatsApp API | Bulk WhatsApp panel | |
|---|---|---|
| Who sends | Your software, when something happens | A person in the panel |
| Numbers per request | One or many numbers in one call | A list or Excel file |
| Different values per customer | Yes, variables_values in every call | One template for the whole list |
| Scheduling | schedule_time field | Schedule in Bulk WhatsApp |
| Status updates | Webhook and delivery report API | Delivery Report, with webhook if you add one |
| Customer replies | Webhook, then reply with the Session API | Live Chat inbox for your team |
| Price | Same per-message rate | Same per-message rate |
Most businesses use both: the API for order, payment and OTP messages, the panel for campaigns, and Live Chat for replies.
Your data is encrypted and stays yours
Your customers' numbers and messages are business data. We treat them that way: encrypted on the wire and in the database, visible only to the people you allow, on infrastructure that is audited every year.
See our certificates- Encrypted in transitEvery panel page and API call runs over HTTPS (TLS 1.2+). Your API key is sent in a header, never in a page.
- Encrypted at restSensitive fields such as API keys, templates and reports are encrypted in our database, with keys kept outside the application.
- Access you controlPer-user API keys you can rotate any time, IP allow-listing, OTP on login, and agents who see only what you assign.
- Audited and certifiedISO 27001 and SOC 2 Type 2 certified, VAPT tested by an external team, MSME registered.
WhatsApp API integration: questions answered
What is WhatsApp API integration?
WhatsApp API integration means connecting your website, app or CRM to the WhatsApp Business API, so your software sends WhatsApp messages by itself. Your server calls a Fast2SMS web address with the customer number and an approved template. The message goes out from your verified business number, and delivery, read and reply updates come back to your server on a webhook.
How do I send a WhatsApp message using the API?
Call https://www.fast2sms.com/dev/whatsapp with your API key in the authorization header, the message_id of an approved template, the customer number in numbers and, if the template has variables, their values in variables_values separated by a pipe. A good request returns "return": true and a request_id that starts with W.
How much does WhatsApp API integration cost?
The API itself is free. There is no setup fee, no monthly fee and no charge per API call. You pay per message by category: ₹0.25 for utility, ₹0.25 for authentication, ₹0.95 for marketing and ₹0.13 for service replies. Incoming messages are free and failed messages are refunded to your wallet.
Can I send WhatsApp messages from PHP?
Yes. Any PHP version that can make an HTTPS request works. Use cURL in plain PHP or the Http client in Laravel, send the API key as the authorization header, and read request_id from the JSON response. This page has both samples ready to copy.
How do I send a WhatsApp message with Python?
Use the requests library: post the message_id, numbers and variables_values to https://www.fast2sms.com/dev/whatsapp with your API key in the authorization header. Check "return" in the JSON response and store the request_id. The full sample is in the code section above.
Do I need a Meta developer account or app?
No. You connect your number through the Fast2SMS panel with Facebook login and get templates approved there. Fast2SMS handles the Meta side, so your code only calls the simple Fast2SMS endpoints with one API key.
Where do I find message_id and phone_number_id?
In WhatsApp Manager in the panel: Templates shows the message_id of each approved template and Numbers shows the phone_number_id of each connected number. You can also list them with GET /dev/dlt_manager/whatsapp?type=template or type=number.
Can I send a WhatsApp message to many numbers in one API call?
Yes. The template API takes several numbers in the numbers field, separated by commas, and returns one request_id for that send. The delivery report for that request_id then shows one row per number.
Can I send a free-form WhatsApp message without a template?
Only inside the 24-hour customer service window, which opens when a customer writes to you. Then POST to /dev/whatsapp-session with a text, image, video, audio, document, sticker, location or reaction. Outside that window you need an approved template, or the Direct Send API for utility messages if your number qualifies.
What is the WhatsApp Direct Send API?
Direct Send lets an eligible number send a utility message, such as an order update, without creating a template first. Meta builds the template from your message in the background and it is charged at the utility rate. In Fast2SMS it works only for numbers with a messaging limit of 100K or unlimited and with Direct Send enabled.
How do I send an image or PDF with the WhatsApp API?
Use a template with a media header and pass media_url with a public link to the file. JPG and PNG images can be up to 5 MB, MP4 video up to 16 MB and PDF up to 100 MB. Add document_filename to set the name the customer sees on a PDF.
How do I get delivered and read status?
Two ways. Create a WhatsApp webhook and Fast2SMS posts sent, delivered, read and failed events to your URL as they happen. Or call GET /dev/whatsapp/{request_id} for the status of every number in one send from the last 90 days.
Can I receive customer replies through the API?
Yes. Incoming messages reach your webhook with "webhook_type": "incoming_message", the sender number, the message type and the text, plus a media link and caption for images and files. Button replies carry the ID of the message they answer.
Which numbers can I send to with the WhatsApp API?
The Fast2SMS WhatsApp API is set up for Indian businesses sending to Indian mobile numbers: 10 digits starting with 6 to 9, with or without +91 in front. The customer must have WhatsApp on that number.
Can I schedule WhatsApp messages through the API?
Yes. Add schedule_time as a Unix timestamp or as a date in DD-MM-YYYY-HH-MM format. The time must be in the future, otherwise the API returns an invalid schedule time error.
Is DLT registration needed for the WhatsApp API?
No. DLT is only for business SMS in India. WhatsApp needs a connected business number and Meta approved templates instead.
How do I keep my WhatsApp API key safe?
Call the API only from your server, never from a web page or mobile app, and read the key from an environment variable. Turn on API Security in the panel to accept calls only from your own IP addresses, and regenerate the key if it ever leaks.
Why do I get error 414 from the API?
Error 414, "IP is blacklisted from Dev API section", means API Security is on and the call came from an IP that is not on your whitelist. Add your server's fixed outgoing IP in the panel. Cloud functions often change IP, so they need a fixed outbound IP or a small relay server.
Is there ready-made source code for the WhatsApp API?
Yes. This page has working samples in cURL, PHP, Laravel, Python, Node.js, Java and C#. In the panel, API Excel also gives you a ready request for each of your approved templates, and docs.fast2sms.com lists every endpoint with a try-it panel.
Does the WhatsApp API work with my CRM or no-code tool?
Yes, if the tool can make an HTTP request and receive a webhook. Map the customer number to numbers and your fields to variables_values in order, and point the WhatsApp webhook at the tool's webhook URL to get status updates and replies back.
Why choose Fast2SMS for WhatsApp API integration in India?
One API key and one wallet for WhatsApp, SMS, RCS and voice, three send APIs for templates, 24-hour replies and Direct Send, webhooks with read receipts and replies, no setup or monthly fee, rates from ₹0.13 per message, automatic refunds for failed messages, free onboarding and support on chat, phone and email.
One API key for WhatsApp, SMS, RCS and voice. No API, setup or monthly fee.