WhatsApp session message API: reply to customers within 24 hours

When a customer writes to your WhatsApp number, you can reply with any text, image, video, audio, document, location or reaction for the next 24 hours. With Fast2SMS you send these replies by API through https://www.fast2sms.com/dev/whatsapp-session, no template needed. This guide explains the 24-hour rule, every parameter, the file limits and ready code for cURL, PHP, Python and Node.js.

The 24-hour rule in short

WhatsApp opens a 24-hour customer service window each time the customer sends you a message. Inside that window you can send free-form session messages. After 24 hours with no new message from the customer, you can only send an approved template. Read more in how to message a customer after 24 hours.

The API does not stop you from sending outside the window. WhatsApp itself rejects such a message, and it shows as Failed in your report with Meta’s re-engagement error 131047. Failed messages are refunded automatically. Track the customer’s last message time on your side, or use a template when in doubt.

Before you start

Send a session message step by step

  1. Download the session API samples

    Go to Account Setting, API Excel, and pick WhatsApp. Click Download Session API. The Excel has one row per connected number and message type (text, image, document, audio, video, location, sticker, reaction) with a sample URL and the file rules.

    API Excel page with the WhatsApp tab selected and the WhatsApp Session API Excel card with a Download Session API button
    Download Session API gives sample requests for each message type.
  2. Pick the type and build the request

    Send phone_number_id, the customer’s number in to, the type and the fields that type needs (table below). Put your key in the authorization header.

  3. Read the response

    Success looks like this. Save the request_id to look up the status later.

    {"return":true,"request_id":"Wa1B2c3D4e5F6g7","message":["Whatsapp Message sent successfully."]}
  4. Watch the status

    Sent, delivered, read and failed updates come through the WhatsApp delivery report, the DLR API and your webhook. See WhatsApp delivery and read status by API.

Parameters

Parameter When Rules
phone_number_id Always (or display_number) The connected number that replies. Phone Number ID is the safer choice
to Always The customer’s Indian mobile, 10 digits, with or without 91
type Optional text (default), image, video, audio, document, sticker, location, reaction
text type=text Up to 4,096 characters
url image, video, audio, document, sticker Public link to the file
caption Optional for media Up to 1,024 characters
document_filename type=document Required. The file name the customer sees
latitude, longitude type=location Required. Add name and address if you like
message_id, emoji type=reaction The WhatsApp message ID of the customer’s message (from the incoming webhook) and the emoji
udf1 to udf3 Optional Your own tracking values

File types and sizes for media replies

type Formats Max size
image JPEG, PNG 5 MB
video MP4, 3GP 16 MB
audio AAC, MP4 audio, MP3, AMR, OGG 16 MB
document PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, TXT 100 MB
sticker WebP 100 KB

Fast2SMS checks the link before sending. If the server does not answer, you get “Unable to reach the media URL provided.” A wrong file type or size gets a clear message that names the allowed formats or the limit.

Code examples

Text reply (cURL)

curl -X POST "https://www.fast2sms.com/dev/whatsapp-session" \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number_id":"100000000000002","to":"9999999999","type":"text",
       "text":"Hi Rahul, your replacement jar will reach you by Friday."}'

Image with caption (cURL)

curl -X POST "https://www.fast2sms.com/dev/whatsapp-session" \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number_id":"100000000000002","to":"9999999999","type":"image",
       "url":"https://example.com/catalogue/jar.jpg","caption":"This is the new jar we are sending."}'

Document (cURL)

curl -X POST "https://www.fast2sms.com/dev/whatsapp-session" \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number_id":"100000000000002","to":"9999999999","type":"document",
       "url":"https://example.com/invoices/INV-1042.pdf","document_filename":"Invoice INV-1042.pdf"}'

Location (cURL)

curl -X POST "https://www.fast2sms.com/dev/whatsapp-session" \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number_id":"100000000000002","to":"9999999999","type":"location",
       "latitude":18.5204,"longitude":73.8567,"name":"Demo Traders","address":"12 Demo Market, Pune"}'

PHP

<?php
function sendSessionReply(array $msg): array {
    $ch = curl_init("https://www.fast2sms.com/dev/whatsapp-session");
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ["authorization: YOUR_API_KEY", "Content-Type: application/json"],
        CURLOPT_POSTFIELDS     => json_encode($msg),
        CURLOPT_TIMEOUT        => 30,
    ]);
    $data = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $data ?? [];
}

$res = sendSessionReply([
    "phone_number_id" => "100000000000002",
    "to"              => "9999999999",
    "type"            => "text",
    "text"            => "Thanks for writing to Demo Traders. How can we help?",
]);
echo ($res["return"] ?? false) === true ? $res["request_id"] : json_encode($res);

Python

import requests

def send_session_reply(msg):
    r = requests.post("https://www.fast2sms.com/dev/whatsapp-session",
                      headers={"authorization": "YOUR_API_KEY"}, json=msg, timeout=30)
    return r.json()

res = send_session_reply({
    "phone_number_id": "100000000000002",
    "to": "9999999999",
    "type": "text",
    "text": "Thanks for writing to Demo Traders. How can we help?",
})
print(res.get("request_id") if res.get("return") else res.get("errors"))

Node.js

async function sendSessionReply(msg) {
  const res = await fetch("https://www.fast2sms.com/dev/whatsapp-session", {
    method: "POST",
    headers: { authorization: process.env.FAST2SMS_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify(msg),
  });
  return res.json();
}

const res = await sendSessionReply({
  phone_number_id: "100000000000002",
  to: "9999999999",
  type: "text",
  text: "Thanks for writing to Demo Traders. How can we help?",
});
console.log(res.return === true ? res.request_id : res.errors);

Charges

Each session message you send is charged at your WhatsApp session rate. At the time of writing the panel shows ₹0.13 per outgoing session message, and incoming messages are free. Your own rate is shown in the wallet dropdown and on the WhatsApp pricing page. A session message that fails is refunded with the other failed WhatsApp messages; see WhatsApp failed message charges and refunds.

Sending in bulk? For high WhatsApp volumes our team offers discounted rates. Talk to our team or see WhatsApp pricing.

Common problems and fixes

“WhatsApp number not found or not connected.”

The phone_number_id (or display_number) does not match a Connected number in your account. Copy the Phone Number ID again from Numbers.

“Invalid mobile number format.” or “Mobile Number format is invalid.”

Send the customer’s 10-digit Indian mobile number, with or without 91. One number per request.

“The ‘text’ field is required for text messages.”

Type defaults to text. Send text, or set type to the media type you mean.

“The ‘document_filename’ field is required for document messages.”

Add a file name such as “Invoice INV-1042.pdf”.

The API said success but the message failed

Most often the 24-hour window had closed (error 131047). Send an approved template instead. Other reasons are listed in WhatsApp API error codes.

Frequently asked questions

What is a WhatsApp session message?

A free-form message you send within 24 hours of the customer’s last message. It needs no template approval.

Can I start a conversation with a session message?

No. To message someone first, or after 24 hours, you must send an approved template.

Can I send buttons in a session reply?

Not with this simple API at the time of writing. It supports text, image, video, audio, document, sticker, location and reaction.

How do I know when the customer last wrote?

Set up a WhatsApp webhook with the Incoming Messages event. Each incoming message reaches your server with a timestamp, so you can track the 24-hour window.

Can I reply to international numbers?

Not with this API at the time of writing. The to number must be an Indian mobile.