Guides

Creating WhatsApp Session Messages

Suggest Edits

If a WhatsApp user has sent your application a message — whether it’s a reply to one of your outbound messages 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:

  1. 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.

  2. 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.

  3. Message Types. These session message types can be sent as a reply to a previous message.

Text messages

Text messages are messages containing only a text body.

HTTP Request: POST /v3/messages

The following text message example includes only a text body:

 {
  "from": "1000000001",
  "to": "+1000000002",
  "type": "text",
  "body": "As requested, your order ID is: 45890"
 }

The parameters presented in the request body example when creating the Text message are the following:

Parameter Required Description
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.
to Yes Determines the destination phone number for your regular message. Numbers are specified in E.164 format → (‘+’ and a country code).
type Yes

Type of message you want to send.

Supported options:

  • "text": Sends a plain text message.

  • "image": Sends an image file (.jpeg, .png).

  • "audio": Sends an audio file (.acc, .mp3, .amr, .mpeg).

  • "video": Sends a video file (.mp4, .3gpp.)

  • "document": Sends a document file (.pdf).

  • "contacts": Sends contact information.

  • "location": Sends a location with latitude and longitude.

  • "interactive": Sends an interactive message with reply buttons or list .

In this example, we set the "text" parameter.
body Yes

Only applies to the "text" type, "image" type, "audio" type, "document" type.

For Text messages, enter the text message body to be sent. The text body has a limit of 1024 characters.

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.
externalId No Alphanumeric identifier used for reporting purposes.
callbacks No Webhook URL to notify about the events of the whatsApp message.

Media messages

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

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

Options
.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 the format .pdf.

HTTP Request: POST /v3/messages

The following Media message example includes only an image:

 {
  "from": "1000000001",
  "to": "+1000000002",
  "type": "image",
  "body": "https://example.com?media=image.png",
  "caption": "The best coffee in the town!"
 }

The parameters presented in the request body example when creating the Media message are the following:

Parameter Required Description
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.
to Yes Determines the destination phone number for your regular message. Numbers are specified in E.164 format → (‘+’ and a country code).
type Yes

Type of message you want to send.

Supported options:

  • "text": Sends a plain text message.

  • "image": Sends an image file (.jpeg, .png).

  • "audio": Sends an audio file (.acc, .mp3, .amr, .mpeg).

  • "video": Sends a video file (.mp4, .3gpp.)

  • "document": Sends a document file (.pdf).

  • "contacts": Sends contact information.

  • "location": Sends a location with latitude and longitude.

  • "interactive": Sends an interactive message with reply buttons or list .

In this example, we set the "image" parameter.
body Yes

Only applies to the "text" type, "image" type, "audio" type, "document" type.

For Text messages, enter the text message body to be sent. The text body has a limit of 1024 characters.

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.
caption No

Only applies to the "image" type.

Image caption text.
externalId No Alphanumeric identifier used for reporting purposes.
callbacks No Webhook URL to notify about the events of the whatsApp message.

Contacts messages

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

When a WhatsApp user taps the message's profile arrow, it displays the contact's information in a profile view:

HTTP Request: POST /v3/messages

The Contacts message example includes the following contact information:

{
  "from": "1000000001",
  "to": "+1000000002",
  "type": "contacts",
  "contacts": [
    {
      "addresses": [
        {
          "city": "Menlo Park",
          "country": "United States",
          "country_code": "us",
          "state": "CA",
          "street": "1 Hacker Way",
          "type": "HOME",
          "zip": "94025"
        }
      ],
      "birthday": "2012-08-18",
      "emails": [
        {
          "email": "[email protected]",
          "type": "WORK"
        }
      ],
      "name": {
        "first_name": "Joe",
        "formatted_name": "Dr. Joe Doe Smith",
        "last_name": "Smith"
      },
      "org": {
        "company": "EliPackage",
        "department": "Programming",
        "title": "Lead Programmer"
      },
      "phones": [
        {
          "phone": "+525544444444",
          "type": "HOME"
        },
        {
          "phone": "+525555555555",
          "type": "MOBILE",
          "wa_id": "16505551234"
        }
      ],
      "urls": [
        {
          "url": "https://www.facebook.com",
          "type": "WORK"
        }
      ]
    }
  ]
}

The parameters presented in the request body example when creating the Contacts message are the following:

Parameter Required Description
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.
to Yes Determines the destination phone number for your regular message. Numbers are specified in E.164 format → (‘+’ and a country code).
type Yes

Type of message you want to send.

Supported options:

  • "text": Sends a plain text message.

  • "image": Sends an image file (.jpeg, .png).

  • "audio": Sends an audio file (.acc, .mp3, .amr, .mpeg).

  • "video": Sends a video file (.mp4, .3gpp.)

  • "document": Sends a document file (.pdf).

  • "contacts": Sends contact information.

  • "location": Sends a location with latitude and longitude.

  • "interactive": Sends an interactive message with reply buttons or list .

In this example, we set the "contacts" parameter.
contacts Yes

Only applies to the "contacs" type.

Array that contains the contact information.

Contact information options:

  • "addresses": Full contact address(es).

  • "birthday": Birthday of the contact.

  • "emails": Contact email address(es).

  • "name": Full contact name formatted.

  • "org": Contact organization information.

  • "phones": Contact phone number(s).

  • "urls": Contact URL(s).
contacts.
addresses		 No

Only applies to the "contacs" type.

Array of addresses associated with the contact.
contacts.
addresses.
city		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

City where the contact resides.
contacts.
addresses.
country		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

Country
contacts.
addresses.
country_code		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

Country code in ISO format (e.g., "us")
contacts.
addresses.
state		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

State or province (e.g., "CA").
contacts.
addresses.
street		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

Street address.
contacts.
addresses.
type		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

Type of address, such as "HOME" or "WORK".
contacts.
addresses.
zip		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

ZIP or postal code.
contacts.
birthday		 No

Only applies to the "contacs" type.

Contact's birthday in YYYY-MM-DD format.
contacts.
emails		 No

Only applies to the "contacs" type.

Array of email addresses associated with the contact.
contacts.
emails.
email		 No

Only applies to the "contacs" type, and the "emails" contact information option.

Email address of the contact.
contacts.
emails.
type		 No

Only applies to the "contacs" type, and the "emails" contact information option.

Type of email, such as "HOME" or "WORK".
contacts.
name		 Yes

Only applies to the "contacs" type.

Object representing the name of the contact.
contacts.
name.
first_name		 Yes

Only applies to the "contacs" type, and the "name" contact information option.

Contact's first name.
contacts.
name.
formatted_name		 Yes

Only applies to the "contacs" type, and the "name" contact information option.

Contact's formatted name. This will appear in the message alongside the profile arrow button.
contacts.
name.
last_name		 Yes

Only applies to the "contacs" type, and the "name" contact information option.

Contact's last name.
contacts.
org		 No

Only applies to the "contacs" type.

Object representing the organization the contact is associated with.
contacts.
org.
company		 No

Only applies to the "contacs" type, and the "org" contact information option.

Name of the company where the contact works.
contacts.
org.
department		 No

Only applies to the "contacs" type, and the "org" contact information option.

The department within the company.
contacts.
org.
title		 No

Only applies to the "contacs" type, and the "org" contact information option.

Contact's job title.
contacts.
phones		 No

Only applies to the "contacs" type.

Array of phone numbers associated with the contact.
contacts.
phones.
phone		 No

Only applies to the "contacs" type, and the "phones" contact information option.

WhatsApp user phone number in E.164 format.
contacts.
phones.
type		 No

Only applies to the "contacs" type, and the "phones" contact information option.

Type of phone number, such as "HOME" or "WORK".
contacts.
phones.
wa_id		 No

Only applies to the "contacs" type, and the "phones" contact information option.

WhatsApp user ID.
contacts.
urls		 No

Only applies to the "contacs" type.

Array of URLs associated with the contact.
contacts.
urls.
url		 No

Only applies to the "contacs" type, and the "urls" contact information option.

Website URL associated with the contact or their company.
contacts.
urls.
type		 No

Only applies to the "contacs" type, and the "urls" contact information option.

Type of website, such as "HOME" or "WORK".
externalId No Alphanumeric identifier used for reporting purposes.
callbacks No Webhook URL to notify about the events of the whatsApp message.

Location messages

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

HTTP Request: POST /v3/messages

The Location message example includes the following details about the location:

{
  "from": "1000000001",
  "to": "+1000000002",
  "type": "location",
  "location": {
    "longitude": -122.425332,
    "latitude": 37.758056,
    "name": "Facebook HQ",
    "address": "1 Hacker Way, Menlo Park, CA 94025"
  }
}

The parameters presented in the request body example when creating the Location message are the following

Parameter Required Description
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.
to Yes Determines the destination phone number for your regular message. Numbers are specified in E.164 format → (‘+’ and a country code).
type Yes

Type of message you want to send.

Supported options:

  • "text": Sends a plain text message.

  • "image": Sends an image file (.jpeg, .png).

  • "audio": Sends an audio file (.acc, .mp3, .amr, .mpeg).

  • "video": Sends a video file (.mp4, .3gpp.)

  • "document": Sends a document file (.pdf).

  • "contacts": Sends contact information.

  • "location": Sends a location with latitude and longitude.

  • "interactive": Sends an interactive message with reply buttons or list .

In this example, we set the "location" parameter.
location Yes

Only applies to the "location" type.

Object contains the geographic information being shared.

Contact information options:
location.
longitude		 Yes

Only applies to the "location" type.

The longitude coordinate of the location.
location.
latitude		 Yes

Only applies to the "location" type.

The latitude coordinate of the location.
location.
name		 No

Only applies to the "location" type.

Name or title of the location.
location.
address		 No

Only applies to the "location" type.

Location address.
externalId No Alphanumeric identifier used for reporting purposes.
callbacks No Webhook URL to notify about the events of the whatsApp message.

Interactive messages

Interactive messages include interactive elements like buttons or lists, designed to enhance engagement by making it easier for users to respond and take action. These messages are a powerful tool for businesses to create more user-friendly and dynamic interactions, such as allowing customers to select options from the message.

There are two types of interactive messages supported in WhatsApp:

  • Reply Buttons: These messages include up to three buttons that allow users to quickly reply to the message by selecting one of the predefined options.
  • Interactive List: These messages present a scrollable list of options (up to 10 items) that users can select from. This is particularly helpful when you need to offer multiple options in a structured manner.

Reply Buttons

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

HTTP Request: POST /v3/messages

The Reply button message example includes the following details about the button:

{
  "from": "1000000001",
  "to": "+1000000002",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": {
      "type": "image",
      "image": {
        "link": "https://example.com?media=image.png"
      }
    },
    "body": {
      "text": "Hi Alex! Your appointment with Dr. Smith is scheduled for 3:00 PM on Friday, September 15th. If you need to make changes, please use the buttons below."
    },
    "footer": {
      "text": "Looking forward to seeing you!"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "0",
            "title": "Change"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "1",
            "title": "Cancel"
          }
        }
      ]
    }
  }
}

The parameters presented in the request body example when creating the Reply button are the following:

Parameter Required Description
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.
to Yes Determines the destination phone number for your regular message. Numbers are specified in E.164 format → (‘+’ and a country code).
type Yes

Type of message you want to send.

Supported options:

  • "text": Sends a plain text message.

  • "image": Sends an image file (.jpeg, .png).

  • "audio": Sends an audio file (.acc, .mp3, .amr, .mpeg).

  • "video": Sends a video file (.mp4, .3gpp.)

  • "document": Sends a document file (.pdf).

  • "contacts": Sends contact information.

  • "location": Sends a location with latitude and longitude.

  • "interactive": Sends an interactive message with reply buttons or list .

In this example, we set the "interactive" parameter.
interactive Yes

Only applies to the "interactive" type.

This object contains the details of the interactive messsage,specifying the type of interaction (in this case, reply buttons) and the structure for buttons, headers, body text, and footer text.
interactive.
type		 Yes

Only applies to the "interactive" type.

Defines the type of interactive message.

  • "button": Set this parameter to include reply button(s).

  • "list": Set this parameter to include an interactive list.

In this example, we set the "button" parameter.
interactive.
header		 No

Only applies to the "interactive" type.

Object contains the details of the message’s header.

This is the content displayed at the top of the message. It can be used to provide context or a brief introduction to the interactive buttons.
interactive.
header.
type		 No

Only applies to the "interactive" type, and the "header" option.

Specifies the type of content in the header.

Supports the following types:

  • "text": For text-based headers.

  • "image": For image headers (.jpeg, .png).

  • "video": For video headers (.mp4, .3gpp.).

  • "document": For document headers (.pdf).
interactive.
header.
text		 No

Only applies to the "interactive" type, and the "header" option.

Enter the text message header to be sent. A text header has a limit of 60 characters including emojis.
interactive.
header.
image		 No

Only applies to the "interactive" type, the "header" option, and the media file type header.

Object that contains details about the media file to be displayed in the header of the message.

Specifies the type of header content: "image", "video", "document".

In this example, the object is "image".
interactive.
header.
image.
link		 No

Only applies to the "interactive" type, the "header" option, and the media file type header.

if you set the Video, Image or Document as Header type header, enter the URL of the chosen media.

The URL of the header (image, video and document) must be a valid URL that starts with "http://…" or "https://…" and provides a direct download. Redirects are not supported.

In this example, the file is an image.
interactive.
body		 Yes

Only applies to the "interactive" type.

The main text content of the message. This is where the core message is communicated, prompting the user to choose one of the available options.
interactive.
body.
text		 Yes

Only applies to the "interactive" type, and the "body" option.

Enter the text message body to be sent. Only contain text, markdown, and emojis. A text body has a limit of 1024 characters including emojis.
interactive.
footer		 No

Only applies to the "interactive" type.

An additional text section displayed at the bottom of the message.
interactive.
footer.
text		 No

Only applies to the "interactive" type, and the "footer" option.

Enter the text message footer to be sent. A text footer has a limit of 60 characters.
interactive.
action		 Yes

Only applies to the "interactive" type.

For Reply buttons, defines the interactive components of the message, specifically the buttons used for user interaction. This field contains an array of buttons that the user can tap to respond.
interactive.
action.
buttons		 Yes

Only applies to the "interactive" type.

Array of buttons that users can tap to respond to the message. Each button contains a type and reply object.

You can have up to 3 buttons.
interactive.
action.
buttons.
type		 Yes

Only applies to the "interactive" type, and the "buttons" option.

Specifies the type of button. For reply buttons, this is set to "reply".
interactive.
action.
buttons.
reply		 Yes

Only applies to the "interactive" type, and the "buttons" option.

This object defines the specific reply option that a user can select by tapping a button. Each reply button in the interactive message is associated with a unique “reply” object that contains an ID and a title.
interactive.
action.
buttons.
reply.id		 Yes

Only applies to the "interactive" type, and the "buttons" option.

A unique identifier for each button. Supports up to 3 buttons.
interactive.
action.
buttons.
reply.
title		 Yes

Only applies to the "interactive" type, and the "buttons" option.

Button label text.

Maximum 20 characters.
externalId No Alphanumeric identifier used for reporting purposes.
callbacks No Webhook URL to notify about the events of the whatsApp message.

Interactive List

Interactive list messages allow you to present WhatsApp users with a list of options to choose from (options are defined as rows in the request payload):

When a user taps the button in the message, it displays a modal that lists the options available:

Users can then choose one option and their selection will be sent as a reply.

Interactive list messages support up to 10 sections, with up to 10 rows per section, and can include an optional header and footer.

HTTP Request: POST /v3/messages

The Interactive List example includes the following details about the list:

{
  "from": "1000000001",
  "to": "+1000000002",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "Choose Your Meal Option"
    },
    "body": {
      "text": "What would you like for lunch today? Please select an option below."
    },
    "footer": {
      "text": "Foodie's Delight: Fresh meals, delivered fast."
    },
    "action": {
      "sections": [
        {
          "title": "I'm Hungry!",
          "rows": [
            {
              "id": "first-option",
              "title": "Grilled Chicken Salad",
              "description": "Fresh greens with a grilled chicken breast (300 kcal)"
            },
            {
              "id": "second-option",
              "title": "Veggie Wrap",
              "description": "Tortilla stuffed with fresh veggies and hummus (250 kcal)"
            }
          ]
        },
        {
          "title": "Light Bites",
          "rows": [
            {
              "id": "third-option",
              "title": "Fruit Bowl",
              "description": "A mix of seasonal fruits (150 kcal)"
            },
            {
              "id": "fourth-option",
              "title": "Greek Yogurt",
              "description": "Creamy yogurt with honey and granola (200 kcal)"
            }
          ]
        }
      ],
      "button": "Select Meal"
    }
  }
}

The parameters presented in the request body example when creating the Interactive List are the following:

Parameter Required Description
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.
to Yes Determines the destination phone number for your regular message. Numbers are specified in E.164 format → (‘+’ and a country code).
type Yes

Type of message you want to send.

Supported options:

  • "text": Sends a plain text message.

  • "image": Sends an image file (.jpeg, .png).

  • "audio": Sends an audio file (.acc, .mp3, .amr, .mpeg).

  • "video": Sends a video file (.mp4, .3gpp.)

  • "document": Sends a document file (.pdf).

  • "contacts": Sends contact information.

  • "location": Sends a location with latitude and longitude.

  • "interactive": Sends an interactive message with reply buttons or list .

In this example, we set the "interactive" parameter.
interactive Yes

Only applies to the "interactive" type.

This object contains the details of the interactive message, specifying the type of interaction (in this case, a list), and the structure of the list (sections, rows, buttons).
interactive.
type		 Yes

Only applies to the "interactive" type.

Defines the type of interactive message.

  • "button": Set this parameter to include reply button(s).

  • "list": Set this parameter to include an interactive list.

In this example, we set the "list" parameter.
interactive.
header		 No

Only applies to the "interactive" type.

Object contains the details of the message’s header.

This is the content displayed at the top of the message. It can be used to provide context or a brief introduction to the interactive buttons.
interactive.
header.
type		 No

Only applies to the "interactive" type, and the "header" option.

Specifies the type of content in the header.

Supports the following types:

  • "text": For text-based headers.
interactive.
header.
text		 No

Only applies to the "interactive" type, and the "header" option.

Enter the text message header to be sent. A text header has a limit of 60 characters including emojis.
interactive.
body		 Yes

Only applies to the "interactive" type.

The main text content of the message. This is where the core message is communicated, prompting the user to choose one of the available options.
interactive.
body.
text		 Yes

Only applies to the "interactive" type, and the "body" option.

Enter the text message body to be sent. Only contain text, markdown, and emojis. A text body has a limit of 1024 characters including emojis.
interactive.
footer		 No

Only applies to the "interactive" type.

An additional text section displayed at the bottom of the message.
interactive.
footer.
text		 No

Only applies to the "interactive" type, and the "footer" option.

Enter the text message footer to be sent. A text footer has a limit of 60 characters.
interactive.
action		 Yes

Only applies to the "interactive" type.

For Interactive List, defines the interactive components of the message, specifically the list of options (organized into sections) and the button that the user presses to interact with the list.
interactive.
action.
sections		 Yes

Only applies to the "interactive" type.

Array of sections. Each section can contain multiple rows (list items). A section helps organize the options in the list into categories or groups.

Interactive list messages support up to 10 sections, with up to 10 rows per section.
interactive.
action.
sections.
title		 Yes

Only applies to the "interactive" type, and the "sections" option.

Section title text. At least 1 section is required. Supports up to 10 sections. Maximum 24 characters.
interactive.
action.
sections.
rows		 Yes

Only applies to the "interactive" type, and the "sections" option.

Array of individual rows (list options) that belong to this section.

Rows represent the individual list items (or options) that the user can select. Each row contains an id and a title.
interactive.
action.
sections.
rows.
id		 Yes

Only applies to the "interactive" type, and the "sections" option.

A unique identifier for the row, which will be sent back to the server when the user selects this option.

At least one row is required. Supports up to 10 rows.

Maximum 200 characters.
interactive.
action.
sections.
rows.
title		 Yes

Only applies to the "interactive" type, and the "sections" option.

Row title. At least 1 row is required.

Supports up to 10 rows.

Maximum 24 characters.
interactive.
action.
sections.
rows.
description		 No

Only applies to the "interactive" type, and the "sections" option.

Row description.

Maximum 72 characters.
interactive.
action.
button		 Yes

Only applies to the "interactive" type.

Button label text. When tapped, reveals rows (options the WhatsApp user can tap). Supports a single button.

Maximum 20 characters.
externalId No Alphanumeric identifier used for reporting purposes.
callbacks No Webhook URL to notify about the events of the whatsApp message.

Updated 3 months ago