Receive incoming WhatsApp messages and button replies on your server (webhook)

To receive incoming WhatsApp messages and button replies on your own server, create a WhatsApp webhook in Fast2SMS with the event Incoming Messages and your URL. Every time a customer writes to your number, Fast2SMS posts the message to that URL: the sender, the text or media link, and which button they tapped. This guide shows the setup, a body template you can copy, and small receiver examples in PHP, Python and Node.js.

Before you start

  • A connected WhatsApp number in Fast2SMS.
  • A public https URL on your server that accepts POST requests and answers with HTTP 200 within 10 seconds. Localhost and private IP addresses are not allowed.
  • Incoming messages switched on for the number. If someone chose Disable Incoming Messages & Webhooks in the number’s action menu in WhatsApp Manager, no webhook is sent for that number.

Set up the incoming message webhook

  1. Open the WhatsApp webhook page

    Click Webhook under UTILITY in the WhatsApp menu, or go to the Webhook section and choose WhatsApp. You see your existing WhatsApp webhooks with their event, number and method. Click Add Webhook.

    WhatsApp Webhook list with three webhooks, one named Incoming WhatsApp replies with Event RECEIVED, WhatsApp Number all and Method POST, status Active
    A webhook with Event RECEIVED gets incoming messages.
  2. Choose the format

    Enter a Webhook Name. In Select Format pick Standard Webhook to build your own body with placeholders. Pick META DIRECT if your code already reads Meta’s WhatsApp Cloud API webhook format; Fast2SMS then forwards Meta’s raw JSON with a fast2sms_id added.

    CREATE WEBHOOK (WHATSAPP) popup with the Select Format dropdown open showing Standard Webhook, CleverTap (WhatsApp) and META DIRECT
    Standard Webhook lets you design the body; META DIRECT forwards Meta’s format.
  3. Select the Incoming Messages event

    Open Select Event and pick Incoming Messages. Use Default All Events only if one URL should get both delivery updates and incoming messages. In Phone Number Id keep Default All or choose one number.

    Select Event dropdown with Default All Events, On Sent, On Delivered, On Read, On Failed and Incoming Messages
    Incoming Messages is the last option in Select Event.
  4. Enter the URL and body

    Keep Method as POST and Content-Type as JSON. Paste your URL. In the Body tab, use the template below or edit the generated one. Type {{ to pick a field.

  5. Create and test

    Leave Webhook Status (Active) on and click CREATE. Then open the row menu and use Test Webhook: it sends one request with sample values to your URL straight away. Finally send a WhatsApp message to your business number from your own phone and check Webhook Logs.

A body template for incoming messages

{
  "webhook_type": "{{webhook_type}}",
  "message_id": "{{message_id}}",
  "from": "{{from}}",
  "phone_number_id": "{{phone_number_id}}",
  "message_type": "{{message_type}}",
  "body": "{{body}}",
  "media_url": "{{media_url}}",
  "mime_type": "{{mime_type}}",
  "caption": "{{caption}}",
  "context_message_id": "{{context_message_id}}",
  "button_text": "{{button_text}}",
  "button_payload": "{{button_payload}}",
  "button_id": "{{button_id}}",
  "button_title": "{{button_title}}",
  "timestamp": "{{timestamp}}"
}
Field What you get
webhook_type incoming_message for a customer message, status_update for a delivery update
message_id WhatsApp’s ID of the incoming message. Use it to send a reaction
from The customer’s WhatsApp number
message_type For example text, image, document, audio, video, sticker, location, button or a reply to an interactive message
body The text. For image, document, audio, video and sticker messages it is the file link
media_url, mime_type, caption The file link, file type and caption of a media message
context_message_id Set when the customer replied to one of your messages: the ID of that message
button_text, button_payload Filled when the customer taps a quick reply button on your template
button_id, button_title Filled when the customer picks a reply button or list item in an interactive message
timestamp Unix time of the message. Use it to track the 24-hour reply window

Want to know which template a button reply belongs to? Compare context_message_id with the WhatsApp message ID of your sent message. That ID is the request_id field in the status updates and the WhatsApp DLR API.

Receiver examples

Your endpoint should answer with HTTP 200 quickly and do any slow work afterwards. Fast2SMS waits at most 10 seconds.

PHP

<?php
// whatsapp-webhook.php
$event = json_decode(file_get_contents("php://input"), true) ?? [];
http_response_code(200);
echo "ok";

if (($event["webhook_type"] ?? "") === "incoming_message") {
    $from = $event["from"] ?? "";
    $text = ($event["button_text"] ?? "") ?: (($event["button_title"] ?? "") ?: ($event["body"] ?? ""));
    file_put_contents(__DIR__ . "/incoming.log", date("c") . " $from: $text" . PHP_EOL, FILE_APPEND);
}

Python (Flask)

from flask import Flask, request

app = Flask(__name__)

@app.post("/fast2sms/whatsapp")
def whatsapp_webhook():
    event = request.get_json(silent=True) or {}
    if event.get("webhook_type") == "incoming_message":
        text = event.get("button_text") or event.get("button_title") or event.get("body")
        print("From", event.get("from"), "type", event.get("message_type"), "text", text)
        # save to your database or queue here
    return "ok", 200

Node.js (Express)

import express from "express";

const app = express();
app.use(express.json());

app.post("/fast2sms/whatsapp", (req, res) => {
  res.sendStatus(200);
  const event = req.body || {};
  if (event.webhook_type === "incoming_message") {
    const text = event.button_text || event.button_title || event.body;
    console.log("From", event.from, "type", event.message_type, "text", text);
  }
});

app.listen(3000);

To answer the customer, call the session message API within 24 hours. See WhatsApp session message API.

Check that your endpoint is safe

  • Add your own secret header. In the Headers tab of the webhook, add a header such as X-Webhook-Token with a long random value, and reject requests without it.
  • webhook_secret_key. If the webhook signature setting is on for your account, every request also carries the header webhook_secret_key. It is a plain shared secret, not an HMAC, so compare it with your saved value.
  • Use https so message text is encrypted on the way to your server.

Common problems and fixes

Delivery updates arrive but incoming messages do not

The webhook’s event is On Sent, On Delivered, On Read or On Failed. Edit it and choose Incoming Messages or Default All Events.

Nothing arrives for one number

Check the webhook’s Phone Number Id: if it is set to another number, messages to this one are skipped. Also check that incoming messages are not disabled together with webhooks for that number.

Webhook Logs show HTTP 0 or a timeout

Your server did not answer within 10 seconds. Return 200 first, then process. Network errors, timeouts, HTTP 408, 429 and 5xx are retried up to 3 times, 60 seconds apart.

Webhook Logs show HTTP 404 or 401

The path is wrong or your server asked for a login. These are not retried. Fix the URL, then use Resend Webhook on the log row. Each row can be resent once, and logs are kept for 7 days.

The media link stops working later

Download and store files you need to keep. In Live Chat, media files are available for 30 days only.

Frequently asked questions

Can I get WhatsApp replies on my own server?

Yes. Create a WhatsApp webhook with the event Incoming Messages and your public URL. Each customer message is posted to it.

Do incoming messages still show in Live Chat?

Yes, unless incoming messages are disabled for that number. The webhook and the inbox work side by side.

Is receiving messages charged?

No. Incoming WhatsApp messages are free. Your replies are charged as session messages or templates.

How many webhooks can I create for WhatsApp?

Up to 10 per service, so you can send incoming messages and delivery updates to different URLs.

Can I get Meta’s original webhook JSON?

Yes. Choose the META DIRECT format. Fast2SMS forwards Meta’s webhook body and adds fast2sms_id.

Can I create this webhook by API?

Yes, with POST /dev/webhook/v2/whatsapp and event=received. See manage webhooks by API.