Skip to content

How to send a message with a preview#

In this article, we will tell you how to use a custom preview to send a large or small image along with a link for the transition. Sending messages with a custom preview is carried out using the SendMessage method.

Table of content#

How to send a message with a preview#

To send a custom preview, use the SendMessage method or generate a preview in the constructor in your console.

Sending using the SendMessage method#

With the SendMessage method, you can send a custom preview in your integrations.

To start sending a custom preview, you need to Connect WhatsApp to the GREEN-API service.

First, let's look at how the method works with regular text messages. 

    {
    "chatId": "1111111111@c.us",
    "message": "Hello, John Doe"
    }

In the body of the method request, we only need to specify the recipient's number or chat to send a text message.

To send a site preview, you need to add a link with http(s). In this case, you need to select the preview size:

{
  "chatId": "1111111111@c.us",
  "message": "https://green-api.com\n\nHello, John Doe",
  "linkPreview": true,
  "typePreview": "large"
}

New fields in the form of "linkPreview" are added to the known parameters: true - if the field is not specified or does not have the value true, then the preview will not be generated. Also, we set the preview size using the small/large parameters in the "typePreview" field.

To send your custom preview, there are several options for this case. You can send a preview via a link from your site or cloud storage, while the link must lead to the file itself.

{
  "chatId": "1111111111@c.us",
  "message": "https://green-api.com\n\nHello, John Doe",
  "linkPreview": true,
  "typePreview": "large",
  "customPreview": {
    "title": "New order",
    "description": "Download today",
    "link": "https://green-api.com",
    "urlFile": "https://green-api.com/blog/assets/2025/whatsapp-adds-18-new-colors-to-chats/1.png"
  }
}

In this case, we add a new field customPreview in which you need to fill in the fields:

  • "title" - Text field for the preview table of contents
  • "description" - Text alternative description of the preview
  • "link": "https://green-api.com" - Link to your preview, even if there are several links in the message body, the preview will lead to the link you selected
  • "urlFile" - Link to the preview file

Using the method is very simple, to send, you need to determine the size of the preview. To send images, you must comply with the following restrictions and rules.

In addition, you can upload your image using the UploadFile method, after which you will receive a link for the "urlFile" field, the request will look the same as in the previous case, you will only need to use the link from the response of the UploadFile method.

{
  "chatId": "1111111111@c.us",
  "message": "https://green-api.com\n\nHello, John Doe",
  "linkPreview": true,
  "typePreview": "large",
  "customPreview": {
    "title": "New order",
    "description": "Download today",
    "link": "https://green-api.com",
    "urlFile": "https://do-mediaouts.com/e649e.jpeg"
  }
}

The most reliable way to send a preview is to generate a jpegThumbnail, as the file is the required size and loads very quickly. When you generate a jpegThumbnail, the request will look like this: 

{
  "chatId": "1111111111@c.us",
  "message": "https://green-api.com\n\n Hello, John Doe",
  "linkPreview": true,
  "typePreview": "small",
  "customPreview": {
    "title": "New order",
    "description": "Download today",
    "link": "https://green-api.com",
    "jpegThumbnail": "/9j/4AAQSkZJRgABAQEA8ADwAAD/4QM4RXhd1gEg5nPvHmfWQm0Zt6df0yahHiEdTh9D6cR1Dcdz6ebk/
    ...
    uuqO51jH04j6H6WcfoNfoPQ36E59OfTn049X0fTmf//Z"
  }
}

In this case, the preview size will always be small, and the converted image is entered in the "jpegThumbnail" field.

For a visual perception of the logic of the method, you can refer to the section Sending a preview using the constructor in your console.

To send a preview, you take into account the basic rules and restrictions.

Sending using the constructor in your console#

Go to the SendMessage method in your account or follow the link the constructor in your console.

You must be authorized in the instance, in order to connect and authorize the instance, read the article Connecting WhatsApp to the GREEN-API service.

General view of the constructor in your account

In this window, set the switches Show preview and description of the link and Custom preview to the enabled mode.

Switches

Enter the data into the constructor fields:

  • phone number or chat
  • message text, specify at least one link for transition
  • quoted message identifier - optional parameter, and is used to reply to previous messages
  • select preview size (small is generated by default)
  • title - arbitrary text for image title
  • description - short description of preview
  • link for transition, it must match at least one link from the message text
  • upload custom preview image via link or from your device (in jpg format up to 100Kb in size)

After filling in all the data, the preview will be displayed in the preview window.

Preview

Now you can send your message or continue editing.

In your console, you can see the body of the SendMessage method request for sending a preview, as well as an example of requests in programming languages: Python, PHP, VBA, Delphi, and even a CURL request.

In your console, you can form request bodies for sending:

  • Text message
  • Text message with preview
  • Text message with custom previews of large and small sizes
  • Text message with jpegThumbnail preview

To send a preview, you should consider the basic rules and restrictions.

Rules and restrictions for working with previews and custom previews#

When sending any previews via a link, the following rules must be followed:

  • Your site must be accessible
  • Your site must weigh less than 2MB
  • Your site must load faster than 20 seconds
  • The site must have the tag og:image in which the image must be located
  • The image must also be accessible
  • The image must be of a supported format (jpg, png)
  • The image must be less than 2MB
  • The image must load faster than 20 seconds
  • The image must have a resolution of less than 5000 px on one side
  • The image is recommended to be in the proportions of the preview being sent - for a predictable result (For a large preview, a square aspect ratio is used, and for a small preview, a rectangular one)

For 100% predictable result of user preview

For a downloadable user preview, all previous provisions are relevant, and to achieve a predictable result, use a small preview with jpegThumbnail generation.

Conclusion#

Custom preview is a powerful visual tool for promoting your products to customers.

To send a preview, we recommend using a small preview with jpegThumbnail generation. It is also worth noting that sending messages with a preview takes longer than sending text messages.

In this article, you learned how to work with custom previews. For clarity, we recommend using the preview constructor in your account, in other cases use the SendMessage method in your integrations.