Service messages are free-form messages that you can send to WhatsApp users during a customer service window. You send them using the Messages API (part of the Cloud API). Unlike template messages, service messages do not require pre-approval — you can compose and send them as needed in response to a WhatsApp user’s message or call.

Service messages can only be sent via the Messages API. To message WhatsApp users outside of a customer service window, use template messages instead. See Marketing messages, Utility messages, or Authentication messages to learn about template-based messaging.

Customer service windows

When a WhatsApp user messages you or calls you, a 24-hour timer called a customer service window starts. If the user messages or calls you again before the timer expires, the timer resets to 24 hours.

While the window is open, you can send any of the service message types listed below to the user. When the window closes, you can only send pre-approved template messages.

As a reminder, you can only send messages to WhatsApp users who have opted-in to receiving messages from you.

Known issue: In rare cases, you may receive a message from a WhatsApp user but be unable to respond within the customer service window.

Pricing

Service messages are billed under the SERVICE pricing category. See Pricing for details.

Message types

You can send the following types of service messages during an open customer service window.

Address messages allow you to easily request a delivery address from WhatsApp users.

Audio messages display an audio icon and a link to an audio file. When the WhatsApp user taps the icon, the WhatsApp client loads and plays the audio file.

Contacts messages allow you to send rich contact information directly to WhatsApp users, such as names, phone numbers, physical addresses, and email addresses.

Document messages display a document icon, linked to a document that a WhatsApp user can tap to download.

Image messages display a single image and an optional caption.

Interactive CTA URL button messages allow you to map any URL to a button, so you don’t have to include lengthy or obscure raw URLs in the message body.

Interactive voice call messages allow you to trigger a WhatsApp call from users.

Interactive Flow messages allow you to send structured messages that are more natural or comfortable for your customers. For example, you can use WhatsApp Flows to book appointments, browse products, collect customer feedback, get new sales leads, or anything else.

For details, see the WhatsApp Flows documentation.

Interactive list messages allow you to present WhatsApp users with a list of options to choose from.

Interactive location request messages display body text and a send location button. When a WhatsApp user taps the button, a location sharing screen appears which the user can use to share their location.

Interactive reply buttons messages allow you to send up to three predefined replies for users to choose from.

Location messages allow you to send a location’s latitude and longitude coordinates to a WhatsApp user.

Sticker messages display animated or static sticker images in a WhatsApp message.

Text messages are messages containing only a text body and an optional link preview.

Video messages display a thumbnail preview of a video image with an optional caption. When the WhatsApp user taps the preview, it loads the video and displays it to the user.

Reaction messages are emoji-reactions that you can apply to a previous WhatsApp user message that you have received.

Message quality

Your message quality is based on how messages have been received by WhatsApp users over the past seven days and is weighted by recency. It is determined by a combination of user feedback signals like blocks, reports, mutes, archives, and reasons users provide when they block you.

Guidelines for sending high-quality messages:

Make sure your messages follow the WhatsApp Business Messaging Policy⁠.

Only send messages to WhatsApp users who have opted into receiving messages from your business.

Make the messages highly personalized and useful to users.

Avoid sending open-ended welcome or introductory messages.

Avoid sending too many messages per day.

Optimize your messages for content and length.

Your business phone number’s status, quality rating⁠, and messaging limits are displayed in the WhatsApp Manager⁠ > Account tools > Phone numbers panel.

Numbers with high traffic commonly experience quality changes within short intervals (even within minutes).

Requests

All send message requests use the Messages API:

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

The post body varies depending on the type of message you want to send, but the payload uses the following common syntax:

{
  "messaging_product": "whatsapp",
  "recipient_type": "<RECIPIENT_TYPE>",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "<MESSAGE_TYPE>",
  "<MESSAGE_TYPE>": {<MESSAGE_CONTENTS>}
}

The type property value in the post body payload indicates the type of message to send, and a property matching that type must be included that describes the message’s contents.

The recipient_type property can be either individual for 1:1 messaging, or group for group messages.

See the Groups API documentation for details.

For example, this is a request to send a text message to a WhatsApp user. Note that type is set to text, and a text object follows, which describes the message’s contents:

curl 'https://graph.facebook.com/v25.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "As requested, here'\''s the link to our latest product: https://www.meta.com/quest/quest-3/"
  }
}'

If delivered, the message appears like this in the WhatsApp client:

Responses

The API returns the following JSON response when it successfully accepts your send message request. This response only indicates that the API successfully accepted your request — it does not indicate successful delivery of your message. You receive delivery status via messages webhooks instead.

Response syntax

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<WHATSAPP_USER_PHONE_NUMBER>",
      "wa_id": "<WHATSAPP_USER_ID>"
    }
  ],
  "messages": [
    {
      "id": "<WHATSAPP_MESSAGE_ID>",
      "group_id": "<GROUP_ID>", <!-- Only included if messaging a group -->
      "message_status": "<PACING_STATUS>" <!-- Only included if sending a template -->
    }
  ]
}

Response contents

Placeholder	Description	Sample Value
`<GROUP_ID>` String	The string identifier of a group made using the Groups API. This field shows when messages are sent, received, or read from a group. Learn more about the Groups API	`Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD`
`<PACING_STATUS>` String	Indicates template pacing status. The `message_status` property is only included in responses when sending a template message that uses a template that is being paced.	`wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI4MjZGRDA0OUE2OTQ3RkEyMzcA`
`<WHATSAPP_USER_PHONE_NUMBER>` String	WhatsApp user’s WhatsApp phone number. May not match `wa_id` value.	`+16505551234`
`<WHATSAPP_USER_ID>` String	WhatsApp user’s WhatsApp ID. May not match `input` value.	`16505551234`
`<WHATSAPP_MESSAGE_ID>` String	WhatsApp Message ID. This ID appears in associated messages webhooks, such as sent, read, and delivered webhooks.	`wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI4MjZGRDA0OUE2OTQ3RkEyMzcA`

Commerce messages

Commerce messages are interactive messages used in conjunction with a product catalog. See Share Products With Customers to see how to use these types of messages.

Read receipts

You can let a WhatsApp user know you have read their message by marking it as read, which causes two blue check marks (called “read receipts”) to appear below the user’s message:

Typing indicators

If it may take you a few seconds or more to respond to a WhatsApp user, you can let them know that you are preparing a response by displaying a typing indicator and read receipts in the WhatsApp client:

Contextual replies

You can send a message to a WhatsApp user as a contextual reply, which quotes a previous message in a contextual bubble:

This makes it easier for the user to know which specific message you are replying to.

Webhooks

Messages sent to WhatsApp users trigger messages webhooks, so be sure to subscribe to this topic to receive message status notifications.

WhatsApp user phone number formats

Plus signs (+), hyphens (-), parenthesis ((,)), and spaces are supported in send message requests.

We highly recommend that you include both the plus sign and country calling code when sending a message to a customer. If the plus sign is omitted, your business phone number’s country calling code is prepended to the customer’s phone number. This can result in undelivered or misdelivered messages.

For example, if your business is in India (country calling code 91) and you send a message to the following customer phone number in various formats:

Number In Send Message Request	Number Message Delivered To	Outcome
`+16315551234`	`+16315551234`	Correct number
`+1 (631) 555-1234`	`+16315551234`	Correct number
`(631) 555-1234`	`+916315551234`	Potentially wrong number
`1 (631) 555-1234`	`+9116315551234`	Potentially wrong number

Note: For Brazil and Mexico, the extra added prefix of the phone number may be modified by the Cloud API. This is a standard behavior of the system and is not considered a bug.

Media caching

If you are using a link (link) to a media asset on your server (as opposed to the ID (id) of an asset you have uploaded to the Meta servers), the Cloud API internally caches the asset for 10 minutes. The cached asset is reused in subsequent send message requests if the link in subsequent payloads is the same as the link in the initial payload.

If you don’t want the cached asset reused in a subsequent message within the 10 minute time period, append a random query string to the asset link in the new send message request payload. The Cloud API treats this as a new asset, fetches it from your server, and caches it for 10 minutes.

For example:

Asset link in first send message request: https://link.to.media/sample.jpg — asset fetched, cached for 10 minutes

Asset link in second send message request: https://link.to.media/sample.jpg — cached asset reused

Asset link in third send message request: https://link.to.media/sample.jpg?abc123 — asset fetched, cached for 10 minutes

Delivery sequence of multiple messages

When sending a series of messages, the order in which messages are delivered is not guaranteed to match the order of your API requests. If you need to ensure the sequence of message delivery, confirm receipt of a delivered status in a status messages webhook before sending the next message in your message sequence.

Message time-to-live (TTL)

If the Cloud API is unable to deliver a message to a WhatsApp user, it retries delivery for a period of time known as a time-to-live, TTL, or the message validity period.

Default TTL

All messages except authentication templates: 30 days.

Authentication templates: 10 minutes

Customizing TTL for templates

You can customize the default TTL for authentication and utility templates, and for marketing templates sent using the Marketing Messages API for WhatsApp. See Time-to-live for details.

When TTL is exceeded: Dropped messages

The platform drops messages that cannot be delivered within the default or customized TTL.

If you do not receive a status messages webhook with status set to delivered before the TTL is exceeded, assume the message was dropped.

If you send a message that fails (status set to failed), there could be a minor delay before you receive the webhook, so you may wish to build in a small buffer before assuming the message was dropped.

Troubleshooting

If you are experiencing problems with message delivery, see Message Not Delivered.

Did you find this page helpful?