· 4 min · TextMeFlow Team

Which WhatsApp Webhook Events Does TextMeFlow Send? An Overview

You've set up a webhook URL and TextMeFlow is sending data to your server — but which events exactly, and what's in each payload? This overview helps you decide which events to catch and which you can ignore.

Why events (and not just "message received")

Most integrations only think about incoming messages, but a WhatsApp connection generates more signals than that: delivery status, the session status of the linked device, and error reports. If you only react to incoming messages, you'll miss, for example, that your number has lost its connection and that outgoing messages haven't been arriving for a while.

Every webhook call is a POST with a JSON body and an event field that indicates the type. For correctly verifying the HMAC signature on every call, see our separate guide on verifying webhook signatures — this article focuses on the events themselves.

message.received

The most-used event: someone sends a WhatsApp message to your linked number. The payload contains the sender's number, the message type (text, image, document, location, …), the content or media URL, and a timestamp. This is the event on which you build chatbots, auto-replies and ticket routing.

Note: media (photos, PDFs, voice messages) doesn't come inline in the payload, but as a temporary download URL. Fetch the file immediately — the URL isn't valid forever.

message.delivered and message.read

For outgoing messages you sent yourself via the API, you get status updates back:

  • message.delivered — the message has arrived on the recipient's device.
  • message.read — the recipient has opened the message (blue tick), provided they haven't turned that feature off on their side.

These events are ideal for building delivery dashboards or for detecting that a particular number is systematically not being reached — often a sign of a wrong or disconnected number, not of a problem on your side.

message.failed

An outgoing message couldn't be delivered. The payload contains an error code and description. Usually it's an invalid or non-WhatsApp number, a recipient who has blocked you, or a temporary delivery error at WhatsApp itself. Build retry logic on this sparingly: blindly resending after a failed raises your risk score in the anti-spam pipeline.

session.connected and session.disconnected

These two events aren't about messages, but about the status of the linked WhatsApp device itself:

  • session.connected — the device is (re)linked and active. This event also fires on a reconnection, not just on the first link.
  • session.disconnected — the link has been broken (device offline, WhatsApp logged out, network problem). From this moment on, no messages are sent or received until it's linked again.

For every production environment it's advisable to send an alert on session.disconnected (Slack, email, monitoring tool) — this is the event you most want to know about fastest, because without an active session your entire WhatsApp channel is down.

In practice: one endpoint, one switch

Most teams process all events on one webhook endpoint and route internally on the event field:

app.post('/webhooks/textmeflow', (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case 'message.received':
      handleIncoming(data);
      break;
    case 'message.delivered':
    case 'message.read':
      updateDeliveryStatus(data);
      break;
    case 'message.failed':
      logFailure(data);
      break;
    case 'session.disconnected':
      alertTeam(data);
      break;
  }

  res.sendStatus(200);
});

Always respond quickly with a 2xx status, even if your processing happens asynchronously — otherwise TextMeFlow interprets the call as failed and a retry follows, which can lead to double processing if you aren't idempotent.

Getting started

Set your webhook URL in the dashboard and test with a message to yourself: you'll immediately see message.received come in, followed by message.delivered as soon as WhatsApp confirms it. No account yet? Start free with 50 messages per month, forever — sign up here.

Want to send WhatsApp messages via API yourself?

Free forever up to 50 messages/month. Scan a QR and send your first message within 5 minutes.

Free forever