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.

Prerequisites

The following are the prerequisites for sending catalog messages:

Sign up for free with kaleyra.io. Before you get started, create a kaleyra.io account for free and Create an API Key. To view the API Key and the SID, see View API Key and SID.
A WhatsApp business number.
An associated profile with the business number.
A WhatsApp verified and approved profile.
A working API key and SID key.
Approved WhatsApp catalog message template with a product thumbnail.

Base URL

https://api.kaleyra.io/v1/<SID>

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 'https://api.kaleyra.io/v1/HXXXXXXX071US/messages' \
 --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="<https://webhook.site/e5xxxx3f-cxx4-4xx4-axx8-2exxxxxxxx95>"' \
 --form 'thumbnail_product_retailer_id="3jxxxxxxxe"' \

Parameters and Data Types

Following is the list of parameters and data types supported:

Parameter	Data Type	Description	Examples	Mandatory?
`sid`	String	Account SID (Security Identifier).	HXXXXXXX071US	Yes
`api_key`	String	The API Key generated by kaleyra.io.	Ac4XXXXX21f	Yes
`to_number`	String	A 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 (,).	+1202XXXXXXX	Yes
`message_type`	String	Message format for the message.	template	Yes
`template_name`	String	Name 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_test	Yes
`params`	String	The 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>, .	"`Hi`"	Yes
`channel_name`	String	Only the WhatsApp channel is supported for the WhatsApp catalog template.	WhatsApp	Yes
`from_number`	String	The 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).	+1202XXXXXXX	Yes
`callback_url`	String	Specifies 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.	`<https://webhook.site/e5xxxx3f-cxx4-4xx4-axx8-2exxxxxxxx95>`	No
`thumbnail_product_retailer_id`	String	The 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.	3jxxxxxxxe	Yes

Sample Success Response

The following success message appears with the status 202 Accepted:

{
    "id": "1b408138-61bf-46d3-9a1d-f13089dbf0a5",
    "type": "template",
  	"body":null,
    "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 Code	Parameter	Description
E13008	from_invalid	Invalid or incorrect input of the From number.
E13009	to_invalid	Invalid or incorrect input of the TO number.
E13004	template_params	The Template parameters do not match.
E13005	template_name_missmatch	Invalid template.

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

Updated 2 months ago