If a WhatsApp user has sent your application a message — whether it’s a reply to one of your outbound message templates, or they have initiated communication themselves — your application has a 24-hour window to send that user any messages, without using a template. These are known as Session Messages.

Key Characteristics of Session Messages:

24-Hour Messaging Window
- The 24-hour window starts when the customer sends a message to the business.
- During this period, the business can respond freely with any type of message.
No Pre-Approval Required
- Unlike template messages, session messages do not require pre-approval from WhatsApp. Businesses can send any content type as long as it’s within the 24-hour window.
Message Types. These session message types can be sent as a reply to a previous message.
- Text messages: Basic conversational text.
- Media messages: Image, video, and document files.

Text Messages

Text messages are messages containing only a text body.

The following text message example includes only a text body without placeholders:

{
  "campaignName": "Next Order",
  "from": "1000000001",
  "message": "Your order will be delivered soon.",
  "data": [
      {
          "to": "+1000000002"
          }
      }
   ]
}

The following text message example includes only a text body with two placeholders:

{
  "campaignName": "Coffee Shop Order",
  "from": "1000000001",
  "message": "Hi [[name]], your [[drink]] is ready! Please pick it up at the counter.",
  "placeholders": [
      "name",
      "drink"
  ],
  "data": [
      {
          "to": "+1000000002",
          "placeholders": {
              "name": "Julian",
              "drink": "Cappuccino"
          }
      }
   ]
}

The parameters presented in the request body example when sending a Session Text Message are the following:

Parameter	Required	Description
campaignName	Yes	Name of the campaign.
from	Yes	Phone number of the sender. Phone number provided during the WABA account setup will be used as the sender of the notification message. Only accepts numeric characters. Do not include the "+" sign.
message	Yes	Content of the session text message that will be sent to the end user. Emojis and markdown are supported. Maximum length: 1024 characters. If the message body include personalized fields (placeholders), they must be defined inside double square brackets (`[[ ]]`)
placeholders	No	It is required when the message body contains placeholders. Array listing all placeholders defined in the message body
data	Yes	Array that contains the recipients, each defined by their phone number in E.164 format, and provide the corresponding placeholder values.
data.to	Yes	Destination address of the message. This is the cell phone number where you want to send your message to. The destination address must be specified in E.164 format → (‘+’ and a country code). The plus sign prefix of the format is optional.
data.placeholders	No	It is required when the message body contains placeholders. Set as parameter the placeholder you defined in the message body that is inside double square brackets `[[...]]`. Then set the value of the placeholder parameter. The placeholders must be correctly formatted in order of how the message was defined. For example, for a text message body like `“Here is your {{code}}”`, you would set the placeholder as `"code": "34871"`.

Media Messages

Media messages are messages that include multimedia content, such as images, videos, and document files.

The next table summarizes each component you can include in the media messages and their different options.

Options	Description
Image	It must be less than 5MB and the format .jpg or .png.
Video	It must be less than 5MB and the format .mp4, .3gpp (Only H.264 video codec and AAC audio codec are supported).
Document	It must be less than 5MB and in the format .pdf.

The following Session Media message example includes only an image:

{
  "campaignName": "Coffee Shop Receipt",
  "from": "1000000001",
  "body": "https://coffee-shop-files.s3.amazonaws.com/receipts/order-1234.pdf",
  "caption": "Hi [[name]], thanks for your order! Here’s your receipt for the [[drink]].",
  "multimediaFileName": "receipt_order_1234.pdf",
  "type": "document",
  "placeholders": [
    "name",
    "drink"
  ],
  "data": [
    {
      "to": "+1000000002",
      "placeholders": {
        "name": "Julian",
        "drink": "Cappuccino"
      }
    }
  ]
}

The parameters presented in the request body example when sending a Session Media Message are the following:

Parameter	Required	Description
campaignName	Yes	Name of the campaign.
from	Yes	Phone number of the sender. Phone number provided during the WABA account setup will be used as the sender of the notification message. Only accepts numeric characters. Do not include the "+" sign.
caption	No	Only applies to the `"image"`, `"video"`, and `"document"` type. If the caption text include personalized fields (placeholders) , they must be defined inside double square brackets (`[[ ]]`)
body	Yes	Only applies to the `"image"`, `"video"`, and `"document"` type. For Media messages, enter the URL of the chosen media file (image, video and document). The URL must be a valid URL that starts with `"http://…"` or `"https://…"` and provides a direct download. Redirects are not supported.
multimediaFileName	Yes	Only applies to the `"image"`, `"video"`, and `"document"` type. if you set a media file (image, video or document), enter the name and file extension of the file to be sent.
type	Yes	Only applies to the `"image"`, `"video"`, and `"document"` type. Type of media file you want to send. Supported options: `"image"`: Sends an image file (.jpeg, .png). `"video"`: Sends a video file (.mp4, .3gpp.) `"document"`: Sends a document file (.pdf).
placeholders	No	It is required when the caption text contains placeholders. Array listing all placeholders defined in the caption text
data	Yes	Array that contains the recipients, each defined by their phone number in E.164 format, and provide the corresponding placeholder values.
data.to	Yes	Destination address of the message. This is the cell phone number where you want to send your message to. The destination address must be specified in E.164 format → (‘+’ and a country code). The plus sign prefix of the format is optional.
data.placeholders	No	It is required when the caption text contains placeholders. Set as parameter the placeholder you defined in the caption text that is inside double square brackets `[[...]]`. Then set the value of the placeholder parameter. The placeholders must be correctly formatted in order of how the message was defined. For example, for a caption text like `“Here is your {{code}}”`, you would set the placeholder as `"code": "34871"`.