Product Catalog Message APIs

Product Catalog Message APIs lets you share the product details when chatting with their customers. The product catalog message options are as follows:

  • Multi-Product Messages: Messages containing a selection of up to 30 items from a business’ inventory.
  • Single Product Messages: Messages with a single product item from the business’ inventory. The product is displayed in a Product Detail Page (PDP) format.

For more information refer to Product Catalog Messages.

Prerequisites

🚧

Important:

Ensure that you follow the pre-requisites to send a product message to be able to successfully send product messages.

Pre-requisites for using Kaleyra WhatsApp APIs

  • A WhatsApp business number.
  • An associated profile with the business number.
  • A WhatsApp verified and approved profile.
  • Activated and Verified WhatsApp Business Account (WABA).

📘

Note:

To know more, read what WhatsApp has to say about creating a business account.

Base URL

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

Send Single Product Catalog

Request Format

The request format to send a Single Product Catalog is as follows:

curl --location --request POST 'https://api.kaleyra.io/v1/<SID>/messages' \
--header 'api-key: <API_KEY>' \
--form 'to=<TO_NUMBER>' \
--form 'type=<CATALOG_TYPE>' \
--form 'channel=<CHANNEL_NAME>' \
--form 'from=<FROM_NUMBER>' \
--form 'body=<PRODUCT_BODY>' \
--form 'footer=<PRODUCT_FOOTER>' \
--form 'action={
    \"catalog_id\": \<CATALOG_ID>\,
    \"product_retailer_id\": \PRODUCT_RETAILER_ID\

Sample Request

Here is a sample Single Product Catalog API request for your reference:

curl --location --request POST 'https://api.kaleyra.io/v1/HXEU1XXXXXXX78IT/messages' \
--header 'api-key: A2c7e28ec22e0XXXXXXX2ece06584d2db' \
--form 'to="91XXXXXX9732"' \
--form 'type="singleproduct"' \
--form 'channel="WhatsApp"' \
--form 'from="44XXXXXX7571"' \
--form 'body="T-Shirt XL"' \
--form 'footer="Save Trees Half Sleeve T-Shirt Blue"' \
--form 'action="{
    \"catalog_id\": \"64722XXXXXX79324\",
    \"product_retailer_id\": \"Blue_Tshirt\"
}"' \
--form 'callback_url="https://webhook.site/b0cd75bb-ec66-434e-9865-7dXXXXXX59df"'

Parameters and Data Types

Following is the list of parameters and data types supported:

ParameterData TypeDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXXXXXXX071USYes
API_KEYStringAPI Key generated by Kaleyra.io.Abab61eebcxxxxxx03640eca9f85f3fcYes
TOIntegerA valid WhatsApp number of the recipient. Ensure that the country code is prefixed to the number. (E164 format).1202XXXXXXXYes
TYPEStringThe type of interactive session message. For catalogs, the value must be product_details.product_detailsYes
CHANNELStringChannel on which message must be sent.WhatsAppYes
FROMIntegerThe 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
BODYStringThe body of the message. Emojis and markdown are supported.

Maximum length: 1024 characters.
T-Shirt XLNo
FOOTERStringThe footer of the message. Emojis and markdown are supported.

Maximum length: 60 characters.
Save Trees Half Sleeve T-Shirt BlueNo
ACTIONJSONThe action field must include CATALOG_ID and PRODUCT_RETAILER_ID.{
"catalog_id": "64XXXXXXXX511924",
"product_retailer_id": "Blue_Tshirt"
}
Yes

Following is the list of parameters and data types within the ACTION object:

ParameterData TypeDescriptionExampleMandatory
CATALOG_IDIntegerID for the catalog you want to use for this message. Retrieve this ID via Commerce Manager.64XXXXXXXX511924Yes
PRODUCT_RETAILER_IDStringA product’s unique identifier. Retrieve this ID via Commerce Manager.Blue_TshirtYes

Response Format

Single Product Catalog success response

{
    "id": "19ab783c-99f8-4c0c-abbc-8ff10a6b7421",
    "type": "singleproduct",
    "body": "Product body",
    "createdDateTime": "2022-04-12 07:17:04+00:00",
    "totalCount": 1,
    "data": [
        {
            "message_id": "19ab783c-99f8-4c0c-abbc-8ff10a6b7421:0",
            "recipient": "917358469469"
        }
    ],
    "error": {}
}

Send Multi-Product Catalog

Request Format

The request format to send a Multi-Product Catalog is as follows:

curl --location --request POST 'https://api.kaleyra.io/v1/<SID>/messages' \
--header 'api-key: <API_KEY>' \
--form 'to=<TO_NUMBER>' \
--form 'type=<CATALOG-TYPE>' \
--form 'channel=<CHANNEL>' \
--form 'from=<FROM_NUMBER>' \
--form 'body=<PRODUCT_BODY>' \
--form 'footer=<PRODUCT_FOOTER>' \
--form 'action="{
    \"catalog_id\": \<CATALOG_ID>\",
    \"sections\": [
        {
            \"title\": \<TITLE>\",
            \"product_items\": [
                {
                    \"product_retailer_id\": \PRODUCT_RETAILER_ID\"
                }
            ]
        }
    ]

Sample Request

Here is a sample Multi-Product Catalog API request for your reference:

curl --location --request POST 'https://api.kaleyra.io/v1/HXAxxxxx26471IN/messages' \
--header 'api-key: Abab61eebcxxxxxx03640eca9f85f3fc' \
--form 'to="91XXXXXXXX32"' \
--form 'type="multiproduct"' \
--form 'channel="WhatsApp"' \
--form 'from="447534490271"' \
--form 'body="T-Shirt XL"' \
--form 'footer="Save Trees Half Sleeve T-Shirt Blue"' \
--form 'action="{
\"catalog_id\": \"6472XXXXXXX27934\",
\"sections\": [
{
\"title\": \"Tshirt\",
\"product_items\": [
{
\"product_retailer_id\": \"Blue_Tshirt\"
}
]
},
{
\"title\": \"Tshirt\",
\"product_items\": [
{
\"product_retailer_id\": \"Blue_Tshirt\"
}
]
}
]
}"' \
--form 'header_type="text"' \
--form 'header_value="T-Shirt"' \
--form 'callback_url="https://webhook.site/b0cd75bb-ec66-434e-9865-7d20c46559df"'

Parameters and Data Types

Following is the list of parameters and data types supported:

ParameterData TypeDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXAxxxxx26471INYes
API_KEYStringAPI Key generated by Kaleyra.io.Abab61eebcxxxxxx03640eca9f85f3fcYes
TOIntegerA valid WhatsApp number of the recipient. Ensure that the country code is prefixed to the number. (E164 format).1202XXXXXXXYes
TYPEStringThe type of interactive session message.

For catalogs, the value must be product_details.
product_detailsYes
CHANNELStringChannel on which message must be sent.WhatsAppYes
FROMIntegerThe 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
BODYStringThe body of the message. Emojis and markdown are supported.

Maximum length: 1024 characters.
T-Shirt XLNo
FOOTERStringThe footer of the message. Emojis and markdown are supported.

Maximum length: 60 characters.
Save Trees Half Sleeve T-Shirt BlueNo
ACTIONJSONThe action field must include CATALOG_ID and PRODUCT_RETAILER_ID.{
"catalog_id": "6472279379511924",
"sections": [
{
"title": "Tshirt",
"product_items": [
{
"product_retailer_id": "Blue_Tshirt"
}
Yes

Following is the list of parameters and data types of the ACTION object:

ParameterData TypeDescriptionExampleMandatory
CATALOG_IDIntegerID for the catalog you want to use for this message. Retrieve this ID via Commerce Manager.64XXXXXXXX511924Yes
SECTIONSJSONArray of section objects. You must include at least one section.

Inside each section, you can include TITLE and PRODUCT_ITEMS.
[
{
"title": "Tshirt",
"product_items": [
{
"product_retailer_id": "Blue_Tshirt"
}
]
},
{
"title": "Tshirt",
"product_items": [
{
"product_retailer_id": "Blue_Tshirt"
}
]
Yes

Following is the list of parameters and data types of the SECTIONS object:

ParameterData TypeDescriptionExampleMandatory
TITLEStringInclude a title for each section if you plan to use more than one.TshirtYes
PRODUCT_ITEMSJSONArray of product objects that should be displayed.[
{
"product_retailer_id": "Blue_Tshirt"
}
]
Yes

Following is the list of parameters and data types of the PRODUCT_ITEMS object:

ParameterData TypeDescriptionExampleMandatory
PRODUCT_RETAILER_IDStringA product’s unique identifier. Retrieve this ID via Commerce Manager.Blue_TshirtYes

Response Format

Multi-Product Catalog success response

{
    "id": "0a9ed012-2f4d-483b-95bc-cdXXef0c60a5",
    "type": "multiproduct",
    "body": "Product body",
    "createdDateTime": "2022-04-12 07:15:33+00:00",
    "totalCount": 1,
    "data": [
        {
            "message_id": "0a9XX012-2f4d-483b-95bc-cdXXef0c60a5:0",
            "recipient": "91XXXXXX7359"
        }
    ],
    "error": {}
}