Service Messages

Free-form messages inside an open customer service window: types, replies, TTL, and October 2026 pricing with 1,000 free messages per number each month.

What Service Messages Are

Service messages are free-form messages sent through the Cloud API /messages endpoint. They are the counterpart to template messages: where templates are pre-approved formats sent in any window, service messages are composed on the fly and only sendable inside an open customer service window (CSW).

Service messagesTemplate messages
Pre-approval required?NoYes
When can you send?Inside an open 24-hour CSW onlyAny time; charged per delivery, except inside a free entry point window
CompositionFree-formBound to approved template structure
CategoriesServiceMARKETING / UTILITY / AUTHENTICATION
Pricing object categoryservicemarketing, utility, authentication, etc.

Use service messages to respond conversationally inside an active customer interaction. To message a user outside any CSW, you must use marketing, utility, or authentication templates.

Service Pages in This Section

The Customer Service Window

When a WhatsApp user messages or calls you, a 24-hour timer (the customer service window or CSW) starts. While that window is open, you can send any service message type listed below. Each new inbound message or call from the user resets the timer to 24 hours.

When the window closes, you can only send pre-approved template messages.

You may only send messages to WhatsApp users who have opted in to receiving messages from you — the open window is a permission to respond, not a license to broadcast.

In rare cases, an inbound message from a user may not open the CSW for you to respond. This is a known platform-level edge case.

Message Types

The service-message types you can send during an open CSW:

TypeWhat it isWhere documented
textText body with optional link previewMessaging Overview
imageSingle image with optional captionMedia Messages
videoVideo with optional captionMedia Messages
audioVoice message or basic audioMedia Messages
documentFile with download iconMedia Messages
stickerStatic or animated WebP stickerMedia Messages
locationLocation coordinatesContacts & Location
contactsContact card with up to 257 contactsContacts & Location
reactionEmoji reaction on a previous user messageReactions
interactive (cta_url)URL mapped to a buttonInteractive Service Messages
interactive (list)List of options in a modalInteractive Service Messages
interactive (button)Up to 3 reply buttonsInteractive Service Messages
interactive (carousel)Horizontally scrollable media or product cardsInteractive Service Messages
interactive (location_request_message)Send-location buttonInteractive Service Messages
interactive (catalog_message, product, product_list)Your catalog, one product, or up to 30 products in sectionsCatalogs & Product Messages
interactive (voice_call)Button that starts a WhatsApp call to your business (needs Calling enabled)Call Buttons & Deep Links
interactive (address_message)Address-collection form (India only)Address Messages
interactive (flow)Structured Flow messageMeta WhatsApp Flows docs

Core Endpoint

All service messages use the same endpoint:

POST https://api.dualhook.com/v25.0/<PHONE_NUMBER_ID>/messages

The body shape is consistent across types — the type field selects the message kind and the matching property carries the contents:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "12015550123",
  "type": "<MESSAGE_TYPE>",
  "<MESSAGE_TYPE>": { /* contents */ }
}

recipient_type is individual for 1-to-1 messages or group for group messaging in Meta's Groups API. Dualhook's runtime accepts only individual.

Meta also accepts a messaging_account_id property, needed only when the sending token has messaging access to more than one Messaging account on the phone number. Otherwise Meta resolves the account itself. Its older alias paid_messaging_account_id is deprecated: move to messaging_account_id by December 31, 2026. See Messaging Accounts. Dualhook sends with the connection's own authorization, which normally reaches only that connection's Messaging account, so you can leave it out.

A successful response returns the WhatsApp message ID immediately, but does not confirm delivery — delivery status arrives asynchronously via a status webhook. For full status-lifecycle behavior, see Messaging Overview.

WhatsApp User Phone Number Formats

Plus signs (+), hyphens, parentheses, and spaces are all permitted in the to field. Strongly include both the + and country calling code — without them, your business phone number's own country code may be prepended, sending the message to the wrong recipient.

SentDelivered toOutcome (business in India, country code 91)
+16315551234+16315551234Correct
+1 (631) 555-1234+16315551234Correct
(631) 555-1234+916315551234Wrong number — country code prepended
1 (631) 555-1234+9116315551234Wrong number — country code prepended

For Brazil and Mexico, Cloud API may modify the prefix automatically — this is by design, not a bug.

Contextual Replies

You can send a service message as a contextual reply to a specific previous message. WhatsApp displays it with a quote bubble pointing to the message you're replying to. Pass the original message's wamid in the context object on your send call:

{
  "messaging_product": "whatsapp",
  "to": "12015550123",
  "context": { "message_id": "wamid.HBgLM..." },
  "type": "text",
  "text": { "body": "Yes, that order ships tomorrow." }
}

This makes it easier for the user to know which specific message you are replying to — useful in long, multi-thread conversations.

A reaction can't be sent as a contextual reply. The quote bubble is also left out if the original message was deleted or moved to long-term storage (typically after 30 days unless Local Storage is enabled), if you reply with a template, or if you reply with audio, image, or video to a user on KaiOS.

Media Caching (Hosted URLs)

When you send media via the link property (a URL on your public server) instead of id (an uploaded media asset), Cloud API fetches the asset and caches it for 10 minutes. Subsequent sends with the same URL within that window reuse the cached copy.

To bypass the cache (e.g. you re-uploaded under the same path), append a random query string:

First send:  https://link.to.media/sample.jpg          → fetched, cached 10 min
Second send: https://link.to.media/sample.jpg          → cached copy reused
Third send:  https://link.to.media/sample.jpg?abc123   → fetched, cached 10 min

This is also why Meta recommends id over link for production sends — uploaded media has a stable identifier and avoids the caching footgun entirely. See Media Messages → Send Media by Media ID.

Delivery Sequence of Multiple Messages

When sending a series of messages, delivery order is not guaranteed to match request order. If sequence matters (e.g. an intro message before a follow-up question), wait for the delivered status webhook on message N before sending message N+1.

For high-volume bursts where strict ordering doesn't matter (e.g. a list of independent updates), pipeline freely.

Time-To-Live (TTL) and Dropped Messages

If Cloud API can't deliver a message immediately (recipient offline, network issue), it retries for a default TTL window:

Message kindDefault TTL
All service messages30 days
Authentication templates10 minutes
All other templates30 days

You can customize TTL per template (utility, authentication, and marketing-via-MM-API only). See Meta's Time-to-live documentation for the full TTL parameter reference.

If you don't receive a delivered status webhook before the TTL elapses, assume the message was dropped. Failed sends emit a failed status webhook, but with a small possible delay — build a buffer before treating absence as failure.

Message Quality

Quality is computed from the last seven days of recipient feedback signals, weighted by recency: blocks, reports, mutes, archives, and the reasons users provide when blocking you.

To keep quality high:

  • Follow the WhatsApp Business Messaging Policy.
  • Only message users who have explicitly opted in.
  • Make messages personalized and useful — avoid generic greetings.
  • Don't send too many messages per day.
  • Optimize content and length for the audience.

Per-number status, quality rating, and messaging limits are visible in WhatsApp Manager → Account tools → Phone numbers, and are also surfaced via Health Monitoring in Dualhook. High-traffic numbers can shift quality state within minutes — see Capacity, Quality & Limits for monitoring guidance.

Pricing

Through September 30, 2026, service messages sent inside an open CSW were free. Since October 1, 2026, each phone number gets 1,000 free service messages per month; only the 1,001st onward is charged. The allowance refreshes monthly, does not roll over, and is separate for each phone number. Paid service messages use the utility and authentication list rate for the recipient's market and do not receive volume-tier discounts.

Service messages inside a free entry point window (up to 7 days, opened from an ad that clicks to WhatsApp) remain free. The status-webhook pricing.category remains service; read type to see how Meta treated a delivery: free_customer_service within the monthly free tier, regular once it is used up, and free_entry_point inside a free entry point window. See Pricing → Free vs Billed Messages and WhatsApp Pricing Changes 2026.

Dualhook Boundary

Dualhook forwards service messages; it does not compose, store, or read them. The Runtime API POST /v25.0/<PHONE_NUMBER_ID>/messages route accepts every type on this page, plus read receipts and typing indicators, and passes the contents to Meta unchanged. It accepts only recipient_type: "individual", so group messages need your own Meta app. There is no inbox or message composer in the dashboard: send from your own backend, or reply by hand in the WhatsApp Business app on a Coexistence number.

Inbound messages and status webhooks go from Meta straight to your endpoint through Webhook Override; Dualhook does not process them. Dualhook can send flow messages but does not create or manage Flows; build those in WhatsApp Manager or with your own Meta app. voice_call buttons need Calling enabled on the number, which Coexistence numbers can't do (see Calling).

Related

  • Interactive Service MessagesInteractive WhatsApp messages: CTA URL button, reply buttons, list, media carousel, and location request. Includes payload shapes and inbound-webhook formats for each type.
  • Address Messages (India)India-only interactive form for collecting structured shipping addresses inside WhatsApp. Covers prefill, saved addresses, validation errors, the nfm_reply submission webhook, and feature-not-supported (error 1026) fallback.
  • Reaction MessagesApply emoji reactions to WhatsApp user messages. Limitations (sent-only status, 30-day window, error 131009), how to remove a reaction, and inbound user reaction webhooks.
  • Media MessagesSending and receiving images, video, audio, documents, and stickers via Cloud API.
  • Contacts & Location MessagesSending and receiving contact cards and location messages via Cloud API.
  • Messaging OverviewCore messaging endpoint, text messages, formatting, delivery statuses, and common errors.
  • PricingDualhook subscription plans, what is included, and how pricing relates to Meta messaging fees.
  • WhatsApp Pricing Changes 2026Meta's 2026 WhatsApp pricing changes: Meta Business Agent billing, 1,000 free monthly service messages per number, chargeable service and in-window utility messages, and October rate cards.
  • WhatsApp Groups APIMeta's Groups API for Cloud API numbers: OBA eligibility, 8-participant limit, invite links, group messages, webhooks, per-recipient pricing, and error codes. Dualhook does not offer it.
Browse more docsStart Free Trial