Messages

You can use the WhatsApp Business Platform to send text messages, media/documents, and template messages to your customers.

The following endpoints allow you to send a message from a business phone number to a customer:

This page provides an overview of how messages work on the WhatsApp Business Platform.

Conversations

Conversation-based pricing is changing starting June 1, 2023. Please see our Pricing Changes document to learn how this will impact you.

Conversations are message threads between you and your customers. Conversations can last up to 24-hours and must be initiated by you (business-initiated) or your customers (user-initiated). Customers can initiate a conversation by sending you any type of message, but you can only initiate a conversation with a template message. Once the conversation has begun, you can then send any type of message to the customer.

User-Initiated Conversations

A user-initiated conversation is a message thread started by a customer who sends any type of message to a business. No prior opt-in is required. When the business responds to the customer it begins a 24-hour customer service window. All messages sent back and forth between the customer and the business within this window are associated with the conversation.

Business-Initiated Conversations

A business-initiated conversation is a message thread started by a business that sends an approved template message to a customer. Prior opt-in is required. When the business sends the template message it begins a 24-hour customer service window. All messages sent back and forth between the customer and the business within this window are associated with the conversation.

Once the customer replies to the business's template message, the business can begin sending any type of message to the customer.

For more information, see:

Customer Service Window

When a customer messages you, a 24-hour timer called a customer service window starts. As long as it has been less than 24 hours since they last messaged you, you can respond with free form messages. If it has been more than 24 hours since they last messaged you, you are outside the customer service window and must use a message template.

The customer service window overlaps with the conversation window for pricing in two ways:

  • If no active conversation exists between you and the customer when they send you a message, you can reply with a free form message and a user-initiated conversation will be opened.
  • If an active conversation exists between you and the customer when they send you a message, you can respond to the customer with a free form message and no additional conversation charges will be incurred.

Conversation-based Pricing

Conversation-based pricing is changing starting June 1, 2023. Please see our Pricing Changes document to learn how this will impact you.

Businesses are charged per conversation, which includes all messages delivered in a 24 hour session. See Conversation-Based Pricing for information.

Scaling Business-Initiated Conversations

Businesses initiate conversations by sending customers a message template from a registered business phone number. Businesses can send message templates to up to 250 unique customers in a rolling 24-hour period, but will need to complete business verification and display name approval in order to scale messages beyond 250.

See Messaging Limits for an explanation of how we automatically scale the amount of message templates you can send to unique customers.

Read Receipts

Businesses can set up read receipts and customers can elect to send read receipts back. If the customer opts out of sending read receipts, the business will only be able to see that the message was delivered. For more information, see:

Message Types

You can send the following message types using the platform:

  • Text messages
  • Media messages: image, video, audio, document, and sticker messages.
  • Contact messages
  • Location messages
  • Interactive messages: List messages, Reply button messages, and Single and Multi Product Messages.
  • Template messages

Message Status

For each message your business sends, you will receive a notification about the status of the message. In the table below, click the arrow in the left column for the WhatsApp app equivalent to each status, if available.

NameDescription

deleted

A message sent by the user was deleted by the user. Upon receiving this notification, you should ensure that the message is deleted from your system if it was downloaded from the server.

WhatsApp App Equivalent

The message is replaced in WhatsApp mobile with a note reading "This message was deleted."

delivered

A message sent by your business was delivered to the user's device.

WhatsApp App Equivalent

Two checkmarks

failed

A message sent by your business failed to send. A reason for the failure will be included in the callback. Check the error message documentation for help debugging:

WhatsApp App Equivalent

Red error triangle

read

A message sent by your business was read by the user. read notifications are only available for users that have read receipts enabled. For users that do not have it enabled, you only receive the delivered notification.

WhatsApp App Equivalent

Two blue checkmarks

sent

A message sent by your business is in transit within our systems.


For On-Premises API users: To receive notifications for sent messages, set the sent_status setting to true in the application settings. The sent status notification is disabled by default.

WhatsApp App Equivalent

One checkmark

warning

A message your business sent contains an item in a catalog that is not available or does not exist.

The order of these notifications in your app may not reflect the actual timing of the message status. View the timestamp to determine the timing, if necessary.

FAQs

Yes! WhatsApp allows you to format selected text inside your messages with Bold, Italics, Strikethrough or Monospace.

There may be cases where you need more time to handle a customer query and may only be able to provide a response after 24 hours. We recommend creating message templates to either:

  • deliver the result to the user, or
  • prompt the user to reply in order to activate the customer service window.

In both cases, please ensure you provide as much context to the message template as possible. For example:

  • "Hello {{1}}, regarding the issue you reported earlier, we regret to inform you that {{2}}. Apologies for any inconvenience caused."
  • We have updates regarding your ticket. Please respond back if you'd like to continue support."