Sending Text Messages

/v1/messages

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

This document covers:

Prerequisites
Request
Response

Prerequisites

Make sure that you have completed the actions in the Messages — Prerequisites documentation.

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

Name	Required	Description
`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

Name	Required	Description
`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:

Formatting	Symbol	Example
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.