Sending Text Messages

/v1/messages

Use the messages endpoint to send text messages to your customers.

This document covers:

Prerequisites

Request

After you have the WhatsApp ID or WhatsApp group ID for the user or group you want to message, use it to send a text message. A text message can be a max of 4096 characters long.

POST /v1/messages
{
    "preview_url": false | true,
    "recipient_type": "individual",
    "to": "whatsapp-id" | "whatsapp-group-id",
    "type": "text",
    "text": {
        "body": "your-text-message-content"
    }
}

Parameters

NameRequiredDescription

preview_url

No

Options: false (default), true
Specifying preview_url in the request is optional when not including a URL in your message.
To include a URL preview, set preview_url to true in the message body and make sure the URL begins with http:// or https://. For more information, see the Sending URLs in Text Messages section.

recipient_type

No

Options: individual (default), group
Determines whether the recipient is an individual or a group
Specifying recipient_type in the request is optional when the value is individual. However, recipient_type is required when using group. If sending a text message to a group, see the Sending Group Messages documentation.

to

Yes

When recipient_type is individual, this field is the WhatsApp ID (phone number) returned from contacts endpoint. When recipient_type is group, this field is the WhatsApp group ID.

type

No

Default: text
Specifying type in the request is optional when you are sending a text message. For media message types, see the Sending Media Messages documentation.

text

Yes

Contains the body field

The text object

NameRequiredDescription

body

Yes

The text of the text message, which can contain URLs and formatting. See the Sending URLs in Text Messages and Formatting in Text Messages sections for more information.

Sending URLs in Text Messages

By default, the mobile WhatsApp application recognizes URLs and makes them clickable. To include a URL preview, include "preview_url": true in the message body and make sure the URL begins with http:// or https://. A hostname is also required, IP addresses are not matched.

{
    "preview_url": true,
    "to": "whatsapp-id",
    "text": {
        "body": "You have to check out this amazing messaging service https://www.whatsapp.com/"
     }

The majority of the time when you send a URL, whether with a preview or not, the receiver of the message will see a URL that they can click on. The exception to this is when you create a group and send an invitation URL to join that group. You will include the invitation URL as shown in the example above, but when the user receives the message, they will be prompted to "Cancel" or "Join Group" instead of seeing a clickable link.

Formatting in Text Messages

WhatsApp allows some formatting in messages. To format all or part of a message, use these formatting symbols:

FormattingSymbolExample

Bold

Asterisk (*)

Your total is *$10.50*.

Italics

Underscore (_)

Welcome to _WhatsApp_!

Strike-through

Tilde (~)

This is ~better~ best!

Code

Three backticks (```)

```print 'Hello World';```

Response

A successful response includes a messages object with an identifier for the newly created message.

{
  "messages": [{
    "id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
  }]
}  

An unsuccessful response will contain an error message. See Error and Status Codes for more information.