Guides

Creating & Sending WhatsApp Session Messages

Send WhatsApp session messages without a template during the 24-hour window after a contact messages your application. For developers sending free-form replies within the active session window.

Send WhatsApp session messages without a template during the 24-hour window after a user messages your application.

📘

Message Throughput (TPS)

For delivery throughput and how TPS applies across channels, see Message throughput and rate limits.

Session message requirements

  1. Stay within the 24-hour messaging window. The window starts when a user messages your business. During this period, you can send any supported session message.
  2. Send without template pre-approval. Session messages do not require WhatsApp pre-approval when sent within the 24-hour window.
  3. Choose a message type. You can send these session messages:

Text messages

Send a text message when you only need to include a text body.

HTTP Request: POST /v3/messages

This example sends a text-only session message:

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

The following table describes the request body parameters for a text message:

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 session message. Numbers are specified in E.164 format → (‘+’ and a country code).
type Yes

Specifies the type of the message that will be sent: "text", "document", "image", "video".

In this case, we enter the "text" type to send a session text message without attaching any media files.
body Yes

Content of the session text message that will be sent to the end user.

Emojis and markdown are supported. Maximum length: 1024 characters.
externalId No Alphanumeric identifier used for reporting purposes.
callbacks No

Indicate one or more (separated by comma) webhook URLs to notify about the status of the message delivery.That is, If you want to receive the status of the message you've sent to your contacts, you need to specify your endpoint.

Your endpoint must have a HTTP POST access method and receive a JSON body.

The URL is the external callback where the events of the Email will be registered and published. Once an email is processed, its status will be posted to your callback URL.

To view the full list and meaning of each status, please refer to the WhatsApp Status section.

Media messages

Send a media message to include an image, video, document, or audio file.

The following table lists the supported media formats and file-size limits.

File typeSupported formatsMaximum file size
Image.jpeg, .jpg, .png5 MB
Video.mp416 MB
Document.pdf100 MB
Audio.aac, .amr, .mp3, .ogg, .m4a16 MB

Requirements:

  • Use 8-bit RGB or RGBA images.
  • Use the H.264 video codec for video files.
  • Use the AAC codec for audio tracks in video files.

HTTP Request: POST /v3/messages

This example sends an image message:

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

The following table describes the request body parameters for a media message:

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 session 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 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.
fileName No

Only applies to the "document" type.

Enter the name and file extension (.pdf) of the document to be sent.
externalId No Alphanumeric identifier used for reporting purposes.
callbacks No

Indicate one or more (separated by comma) webhook URLs to notify about the status of the message delivery.That is, If you want to receive the status of the message you've sent to your contacts, you need to specify your endpoint.

Your endpoint must have a HTTP POST access method and receive a JSON body.

The URL is the external callback where the events of the Email will be registered and published. Once an email is processed, its status will be posted to your callback URL.

To view the full list and meaning of each status, please refer to the WhatsApp Status section.

Contacts messages

Send contact messages to share names, phone numbers, physical addresses, and email addresses with WhatsApp users.

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

HTTP Request: POST /v3/messages

This example sends a contact with address, birthday, email, name, organization, phone, and URL details:

{
  "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 following table describes the request body parameters for a contacts message:

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 session 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 "contacts" 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 "contacts" type.

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

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

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

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

Country
contacts.
addresses.
country_code		 No

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

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

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

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

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

Street address.
contacts.
addresses.
type		 No

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

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

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

ZIP or postal code.
contacts.
birthday		 No

Only applies to the "contacts" type.

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

Only applies to the "contacts" type.

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

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

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

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

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

Only applies to the "contacts" type.

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

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

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

Only applies to the "contacts" 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 "contacts" type, and the "name" contact information option.

Contact's last name.
contacts.
org		 No

Only applies to the "contacts" type.

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

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

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

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

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

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

Contact's job title.
contacts.
phones		 No

Only applies to the "contacts" type.

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

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

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

Only applies to the "contacts" 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 "contacts" type, and the "phones" contact information option.

WhatsApp user ID.
contacts.
urls		 No

Only applies to the "contacts" type.

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

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

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

Only applies to the "contacts" 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

Indicate one or more (separated by comma) webhook URLs to notify about the status of the message delivery.That is, If you want to receive the status of the message you've sent to your contacts, you need to specify your endpoint.

Your endpoint must have a HTTP POST access method and receive a JSON body.

The URL is the external callback where the events of the Email will be registered and published. Once an email is processed, its status will be posted to your callback URL.

To view the full list and meaning of each status, please refer to the WhatsApp Status section.

Location messages

Send a location message to share a location’s latitude and longitude coordinates with a WhatsApp user.

HTTP Request: POST /v3/messages

This example sends a location with coordinates, name, and address:

{
  "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 following table describes the request body parameters for a location message:

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 session 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

Indicate one or more (separated by comma) webhook URLs to notify about the status of the message delivery.That is, If you want to receive the status of the message you've sent to your contacts, you need to specify your endpoint.

Your endpoint must have a HTTP POST access method and receive a JSON body.

The URL is the external callback where the events of the Email will be registered and published. Once an email is processed, its status will be posted to your callback URL.

To view the full list and meaning of each status, please refer to the WhatsApp Status section.

Interactive messages

Send an interactive message to let users choose a response from buttons or a list.

WhatsApp supports two interactive message types:

Reply buttons

Send up to three predefined replies for a user to choose from.

HTTP Request: POST /v3/messages

This example sends a reply-button message with an image header, body, footer, and two response options:

{
  "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 following table describes the request body parameters for a reply-button message:

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 session 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 lists

Send an interactive list to present options as rows in the request payload:

When a user taps the button in the message, WhatsApp displays the available options in a modal:

The user can select one option, which WhatsApp sends as a reply.

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

HTTP Request: POST /v3/messages

This example sends an interactive list with two sections and multiple options:

{
  "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 following table describes the request body parameters for an interactive list:

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 session 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 2 days ago