Send a Catalog Message through WhatsApp Template

POST Method

Kaleyra's WhatsApp Business allows you to send WhatsApp catalog messages to your end customers. The catalog messages can be used for sharing your products and services with end customers.


The following are the prerequisites for sending catalog messages:


API request to Send a WhatsApp Catalog Message Template

To send a WhatsApp catalog message template, use the /messages endpoint.

Request Format

The following is the request format to send a WhatsApp catalog message template:

curl --location --request POST '<base_url>/messages' \
 --header 'api-key: <api_key>' \
 --form 'to="<to_number>"' \
 --form 'type="<message_type>"' \
 --form 'template_name="<template_name>"' \
 --form 'params="<template_parameters>"' \
 --form 'channel="<channel>"' \
 --form 'from="<from_number>"' \
 --form 'callback_url="<callback_url>>"' \
 --form 'thumbnail_product_retailer_id="<thumbnail_product_retailer_id>"' \

Sample Request

The following is the sample request to send a WhatsApp catalog message template:

curl --location --request POST '' \
 --header 'api-key: Ac4XXXXX21f' \
 --form 'to="+1202XXXXXXX"' \
 --form 'type="template"' \
 --form 'template_name="catalog_test"' \
 --form 'params="\"value1\",\"value2\""' \
 --form 'channel="whatsapp"' \
 --form 'from="+1202XXXXXXX"' \
 --form 'callback_url="<>"' \
 --form 'thumbnail_product_retailer_id="3jxxxxxxxe"' \

Parameters and Data Types

Following is the list of parameters and data types supported:

ParameterData TypeDescriptionExamplesMandatory?
sidStringAccount SID (Security Identifier).HXXXXXXX071USYes
api_keyStringThe API Key generated by
to_numberStringA valid WhatsApp number of the recipient. Ensure that the country code is prefixed to the number. (E164 format).

Note: You can add multiple numbers, separate each number using the comma (,).
message_typeStringMessage format for the message.templateYes
template_nameStringName of the WhatsApp template that was created for the WhatsApp catalog message template. This name must be approved by WhatsApp before you start using this API.catalog_testYes
paramsStringThe values that you will pass when you want to send a message using the template. Since the values are dynamic, it must be passed through the key. Multiple parameters are allowed that must be separated with a comma.

For a template that says: Hi your booking id is for date the params to be passed would be
, <id_number>, .
channel_nameStringOnly the WhatsApp channel is supported for the WhatsApp catalog template.WhatsAppYes
from_numberStringThe number registered with WhatsApp business from which the message is to be sent. Ensure that the country code is prefixed to the number. (E164 format).+1202XXXXXXXYes
callback_urlStringSpecifies the callback URL to receive notifications regarding the WhatsApp message status (sent, delivered, read, and failed). For more information related to callback profiles, see the Callback profiles page.
The URL can be accessed publicly.
Click here for an example.
thumbnail_product_retailer_idStringThe thumbnail product retailer ID will be used as the header image of the message being sent. You can access this information from the Business Manager portal.3jxxxxxxxeYes

Sample Success Response

The following success message appears with the status 202 Accepted:

    "id": "1b408138-61bf-46d3-9a1d-f13089dbf0a5",
    "type": "template",
    "createdDateTime": "2024-01-29 05:30:39+00:00", 
    "totalCount": 1, 
    "data": [
            "message_id": "1b408138-61bf-46d3-9a1d-f13089dbf0a5:0",
            "recipient": "1202XXXXXXX" 
    "error": {}

Error Codes

The following table provides information about the error codes you would receive when executing the WhatsApp catalog message template API:

Error CodeParameterDescription
E13008from_invalidInvalid or incorrect input of the From number.
E13009to_invalidInvalid or incorrect input of the TO number.
E13004template_paramsThe Template parameters do not match.
E13005template_name_missmatchInvalid template.

For information related to the other WhatsApp error codes, see WhatsApp Error Codes.