Sending Text Messages

/v1/messages

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

Before You Start

You will need:

Request

Once you have the WhatsApp ID for the user you want to message, use it to send a text message.

Note: A text message can be a max of 4096 characters long.

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

Parameters

NameRequiredDescription

preview_url

No
Specifying preview_url in the request is optional when not including a URL in your message.

Allows for URL previews in messages. Values: false (default), true
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

Value: individual

to

Yes

The WhatsApp ID returned from the contacts endpoint

type

No
Specifying type in the request is optional when you are sending a text message.

Value: text

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 required, IP addresses are not matched.

Example

{
    "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.

URL previews will only be rendered after one of the following has happened:

  1. The business has sent a message template to the user.
  2. The user initiates a conversation with a "click to chat" link.
  3. The user adds the business phone number to their address book and initiates a conversation.

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 ID for the newly created message.

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

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