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/HXEU1725093638IT/messages' \
--header 'api-key: A2c7e28ec22e02e8b8d4d0ce06584d2db' \
--form 'to="91XXXXXX9732"' \
--form 'type="singleproduct"' \
--form 'channel="WhatsApp"' \
--form 'from="447534490271"' \
--form 'body="T-Shirt XL"' \
--form 'footer="Save Trees Half Sleeve T-Shirt Blue"' \
--form 'action="{
    \"catalog_id\": \"6472279379511924\",
    \"product_retailer_id\": \"Blue_Tshirt\"
}"' \
--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:

Parameter

Data Type

Description

Example

Mandatory

SID

String

Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key.

HXXXXXXX071US

Yes

API_KEY

String

API Key generated by Kaleyra.io.

Abab61eebcxxxxxx03640eca9f85f3fc

Yes

TO

Integer

A valid WhatsApp number of the recipient. Ensure that the country code is prefixed to the number. (E164 format).

1202XXXXXXX

Yes

TYPE

String

The type of interactive session message. For catalogs, the value must be product_details.

product_details

Yes

CHANNEL

String

Channel on which message must be sent.

WhatsApp

Yes

FROM

Integer

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

BODY

String

The body of the message. Emojis and markdown are supported.

Maximum length: 1024 characters.

T-Shirt XL

No

FOOTER

String

The footer of the message. Emojis and markdown are supported.

Maximum length: 60 characters.

Save Trees Half Sleeve T-Shirt Blue

No

ACTION

JSON

The action field must include CATALOG_ID and PRODUCT_RETAILER_ID.

{
"catalog_id": "6472279379511924",
"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/HXEU1725093638IT/messages' \
--header 'api-key: A2c7e28ec22e02e8b8d4d0ce06584d2db' \
--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\": \"6472279379511924\",
\"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:

Parameter

Data Type

Description

Example

Mandatory

SID

String

Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key.

HXAxxxxx26471IN

Yes

API_KEY

String

API Key generated by Kaleyra.io.

Abab61eebcxxxxxx03640eca9f85f3fc

Yes

TO

Integer

A valid WhatsApp number of the recipient. Ensure that the country code is prefixed to the number. (E164 format).

1202XXXXXXX

Yes

TYPE

String

The type of interactive session message.

For catalogs, the value must be product_details.

product_details

Yes

CHANNEL

String

Channel on which message must be sent.

WhatsApp

Yes

FROM

Integer

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

BODY

String

The body of the message. Emojis and markdown are supported.

Maximum length: 1024 characters.

T-Shirt XL

No

FOOTER

String

The footer of the message. Emojis and markdown are supported.

Maximum length: 60 characters.

Save Trees Half Sleeve T-Shirt Blue

No

ACTION

JSON

The 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:

Parameter

Data Type

Description

CATALOG_ID

Integer

ID for the catalog you want to use for this message. Retrieve this ID via Commerce Manager.

SECTIONS

JSON

Array of section objects. You must include at least one section.

Inside each section, you can include TITLE and PRODUCT_ITEMS.

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

Parameter

Data Type

Description

TITLE

String

Include a title for each section if you plan to use more than one.

PRODUCT_ITEMS

JSON

Array of product objects that should be displayed.

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-cdaaef0c60a5",
    "type": "multiproduct",
    "body": "Product body",
    "createdDateTime": "2022-04-12 07:15:33+00:00",
    "totalCount": 1,
    "data": [
        {
            "message_id": "0a9ed012-2f4d-483b-95bc-cdaaef0c60a5:0",
            "recipient": "917358469469"
        }
    ],
    "error": {}
}

Did this page help you?