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 for the user 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",
    "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

Value: individual

to

Yes

The WhatsApp ID (phone number) returned from contacts endpoint

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.

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.