Creating WhatsApp Regular Message

Suggest Edits

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

If your application sends a message to a WhatsApp user outside a 24-hour session, the message must use an approved template as described in the previous section.

In your POST call, the request body is composed by the following parameters to send a regular message containing text, media, contacts, locations, and interactive objects.

The content of the JSON message body differs for each type of message (text, image, etc.)

HTTP Request : POST /whatsapp/messages

Main Parameters

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 No

The type of message you want to send.

Supported Options:

  • "text": for text messages.

  • "image": for image messages.

  • "audio": for audio messages.

  • "video": for video messages.

  • "document": for document messages.

  • "contacts": for contact messages.

  • "location": for location messages.

  • "interactive": for reply button messages..
externalId No Alphanumeric identifier used for reporting purposes.
callbacks No Webhook URL to notify about the events of the whatsApp message.

Text Parameter

Parameter Required Description
body Yes

Required when type is "text", "image", "audio","video", or "document".

Contains the text of the message, which can contain URLs.

Enter the URL of the audio, image, video or document according to the type of media option chosen.

Supported media option types and sizes:

MediaContent TypePost-Processing Media Size
imageimage/jpeg
image/png		5 MB
audioaudio/aac
audio/mp4
audio/amr
audio/mpeg
audio/ogg; codecs=opus

Note: The base audio/pgg type is not supported.		5 MB
videovideo/mp4
video/3gpp

Note: Only H.264 video codec and AAC audio codec are supported.		5 MB
documentdocument/pdf5 MB

Example of a Text parameter with Main parameters.

{
  "from": "1000000001",
  "to": "1000000002",  
  "type": "image",
  "body": "http://domain.com/image"
}

Contacts Parameter

Inside contacts, you can nest the following parameters: addresses, birthday, emails, name, org, phone, and urls. Pluralized parameters are to be wrapped in an array as shown in the example below.

Required when type is "contacts".

Parameter Required Description
addresses No

Full contact address(es). The parameter can contain the following fields:

  • "street": Optional. Street number and name.

  • "city": Optional. City name.

  • "state": Optional. State abbreviation.

  • "zip": Optional. ZIP code.

  • "country": Optional. Full country name.

  • "country_code": Optional. Two-letter country abbreviation.

  • "type": Optional. Standard values are "HOME" and "WORK".
birthday No

YYYY-MM-DD formatted string.
emails No

Contact email address(es). The parameter can contain the following fields:

  • "email": Optional. Email address.

  • "type": Optional. Standard values are "HOME" and "WORK".
name Yes

Full contact name formatted. The parameter can contain the following fields:

:

  • "formatted_name": Required. Full name, as it normally appears.

  • "first_name": Optional. First name.

  • "last_name": Optional. Last name.

    • At least one of the optional parameters needs to be included along with the formatted_name parameter.
org No

Contact organization information. The parameter can contain the following fields:

  • "company": Optional. Name of the contact's company.

  • "department": Optional. Name of the contact's department.

  • "title": Optional. Contact's business title.
phones No

Contact phone number(s). The parameter can contain the following fields:

  • "phone":Optional. Automatically populated with the "wa_id" value as a formatted phone number.

  • "type": Optional. Standard Values are "HOME" and "WORK".

  • "wa_id": Optional. WhatsApp ID.
urls No

Contact URL(s). The parameter can contain the following fields:

  • "url": Optional. URL.

  • "type": Optional. Standard Values are "HOME" and "WORK".

Example of a contacts parameter with Main Parameters and pluralized parameters nested inside:

{
  "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": "John",
          "formatted_name": "John Smith",
          "last_name": "Smith"
        },
        "org": {
          "company": "WhatsApp",
          "department": "Design",
          "title": "Manager"
        },
        "phones": [
          {
            "phone": "+1 (940) 555-1234",
            "type": "HOME"
          }
        ],
        "urls": [
          {
            "url": "https://www.facebook.com",
            "type": "WORK"
          }
        ]
      }
   ]
}

Location Parameter

Parameter Required Description
longitude Yes

Longitude of the location.
latitude Yes Latitude of the location.
name No Name of the location.
address No Address of the location. Only displayed if "name" is present.

Example of a Location parameter with Main parameters.

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

Interactive Parameter

The interactive parameter generally contains the action component.

  • Inside "action", you can nest button parameters.
Parameter Required Description
type Yes

The type of interactive message you want to send. Supported values:

  • "button":
    • Use it for Reply Buttons.
body Yes

Parameter with the body of the message.

The body parameter contains the following field:

  • "text": Required if body is present. The content of the message. Emojis and markdown are supported. Maximum length: 1024 characters.
action Yes

An action parameter with what you want the user to perform after reading the message.

Action Parameter

Parameter Required Description
buttons Yes

Required for Reply Button Messages.

A button parameter. The parameter can contain the following parameters:

  • "type": The only supported option is "reply" for Reply Button Messages**.

  • "title": Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters.

  • "id": Unique identifier for your button. Maximum length: 256 characters.

Example of a Interactive parameter with Action and Main parameters.

{
  "from": "1000000001",
  "to": "+1000000002",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "your-text-body-content"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "0",
            "title": "First"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "1",
            "title": "Second"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "2",
            "title": "three"
          }
        }
      ]
    }
  }
}

Updated 3 months ago