WhatsApp 24-hour window and template fallback

This page describes how to handle expired WhatsApp session sendout error.

How the 24-hour customer service window works

WhatsApp opens a rolling 24-hour customer service window when a customer interacts with the business in a way that generates an inbound WhatsApp event. This includes sending a message or replying through an interactive element, such as a quick-reply button. Every qualifying inbound interaction resets the window.

While the window is open, the business can send service messages. Once 24 hours have passed since the customer's last qualifying interaction, WhatsApp accepts only an approved message template. An outbound message sent by the business does not reopen the window; the customer must send a message or perform another qualifying inbound interaction before service messaging becomes available again.

Not every button click qualifies. For example, a quick-reply button sends a response back to the business and therefore counts as an inbound interaction. Opening a URL or another action that does not generate an inbound WhatsApp response must not be assumed to open or reset the window.

The restriction protects customers from unsolicited messages and keeps business-initiated communication predictable. It also means that customer opt-in is still required: an approved template is not permission to contact a person who has not agreed to receive WhatsApp messages.

The 24-hour rule controls which message format may be used. Pricing, template category, quality, and delivery rules are separate WhatsApp policies and may change independently.

What happens when the window is closed

A service message outside the window is rejected. ChatWerk detects the closed window before sending and returns HTTP 422:

{
  "code": 422,
  "message": "Invalid data",
  "errors": [
    {
      "message": "session expired"
    }
  ]
}

Do not retry the same service message. Send an approved WhatsApp template instead.

Check the window before sending

Retrieve the conversation before sending a service message:

GET /inbox/channels/{channel_id}/conversations/{conversation_id}

The response contains last_sent_msg_at, which represents the latest qualifying inbound interaction recorded for the conversation. Despite the field name, it is updated when ChatWerk receives a customer message or another qualifying interaction, such as a quick-reply button response.

Example response fragment:

{
  "id": "conv_01HABC",
  "gateway_id": "gtw_01HXYZ",
  "last_sent_msg_at": "2026-11-04T10:15:00Z"
}

Calculate the window status as follows:

window_expires_at = last_sent_msg_at + 24 hours
window_is_open = current_time < window_expires_at

Treat a missing last_sent_msg_at as a closed window. Use UTC timestamps and account for request latency and clock differences. If the window is close to expiring, use the template endpoint instead of relying on the remaining time.

This check is a preview only. ChatWerk validates the session again while processing the send request, so the result can change between reading the conversation and sending the message.

Recommended fallback flow

Use the template endpoint for messages that must be deliverable both inside and outside the 24-hour window:

POST /inbox/channels/{channel_id}/messages/template

ChatWerk selects the appropriate format:

  • inside the window, it can send the template content as a regular message;
  • outside the window, it sends the approved WhatsApp template.

A message sent through the regular /messages endpoint cannot use this fallback because it does not contain template metadata. Use the template endpoint when the message must also be deliverable outside the 24-hour window.

Prerequisites

Before sending, make sure that:

  1. The contact has opted in to receive WhatsApp messages.
  2. The ChatWerk template belongs to the same organization as the channel.
  3. The template is approved and has an approved WhatsApp counterpart for the gateway namespace.
  4. Every required placeholder has a value in internal_components.
  5. The selected gateway belongs to the channel in the request path.
  6. Any referenced media has already been uploaded and is valid for the template header type.

Request fields

FieldRequiredDescription
gateway_idYesWhatsApp gateway used to send the message.
template_idYesChatWerk template ID. ChatWerk resolves the linked approved WhatsApp template.
toYesReceiver identifier interpreted according to receiver_type.
receiver_typeNo0 = WhatsApp messenger ID (default), 1 = communication channel ID, 2 = conversation ID.
internal_componentsWhen the template has placeholdersKey-value map used for both the regular message and WhatsApp template parameters.
header_media.idWhen a media header is requiredID of an uploaded media file.

Payload examples

Template without placeholders

This example targets an existing conversation:

{
  "gateway_id": "gtw_01HXYZ",
  "template_id": "tpl_order_ready",
  "receiver_type": 2,
  "to": "conv_01HABC"
}

Template with placeholders

For a template containing {{name}} and {{city}}, pass values using the same component names:

{
  "gateway_id": "gtw_01HXYZ",
  "template_id": "tpl_appointment_reminder",
  "receiver_type": 1,
  "to": "com_channel_01HABC",
  "internal_components": {
    "name": "Alex",
    "city": "Berlin"
  }
}

ChatWerk substitutes these values into the internal message and maps them to the positional parameters of the approved WhatsApp template.

Template with a media header

{
  "gateway_id": "gtw_01HXYZ",
  "template_id": "tpl_monthly_statement",
  "receiver_type": 2,
  "to": "conv_01HABC",
  "internal_components": {
    "name": "Alex",
    "period": "October 2026"
  },
  "header_media": {
    "id": "media_01HFILE"
  }
}

The media type must match the approved template header. Do not replace the media type or omit required media at send time.

Example response

A successful request returns the stored message. When a WhatsApp template is used, the response contains type: "template" and the resolved template data:

{
  "id": "message_01HMSG",
  "gateway_id": "gtw_01HXYZ",
  "conversation_id": "conv_01HABC",
  "text": "Hello Alex, your appointment is in Berlin.",
  "type": "template",
  "status": "accepted",
  "direction": "out",
  "data": {
    "template": {
      "type": "whatsapp",
      "template_id": "tpl_appointment_reminder",
      "internal_components": {
        "name": "Alex",
        "city": "Berlin"
      }
    }
  }
}

accepted is not a delivery receipt. Continue tracking status changes until the message reaches a terminal state such as delivered, read, or error.
More about event tracking is described in Channel Webhooks section.

Failure handling

ResultRecommended action
HTTP 422, session expired, after using /messagesSend through /messages/template; do not retry the service message.
Template not found or no linked WhatsApp templateVerify template_id, organization ownership, gateway namespace, and template synchronization.
Template submitted, rejected, paused, disabled, or not approvedDo not retry unchanged. Use an approved template or resolve its status first.
Invalid or missing componentCorrect internal_components; component keys and values must match the template definition.
Invalid mediaUpload supported media and use its ID; ensure the media type matches the approved header.
Contact opted outStop sending. A template must not bypass consent.

Best practices

  • Prefer /messages/template when a message may be sent near or after the 24-hour boundary.
  • Keep one business purpose per template and use the correct WhatsApp template category.
  • Keep templates approved and synchronized for every active WhatsApp gateway namespace.
  • Do not retry a service message after receiving the session expired error. Send an approved template instead.
  • Make client-side sending idempotent to prevent duplicate messages.
  • Validate required components and media before sending.
  • Monitor final delivery statuses.
  • Respect opt-in, opt-out, frequency, localization, and data-minimization requirements.
  • Do not assume that sending a template reopens the service messaging window. Wait for a qualifying inbound interaction from the customer, such as a message or quick-reply button response.

Further reading


Did this page help you?