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:
| 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. | 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": "64XXXXXXXX511924", "product_retailer_id": "Blue_Tshirt" } | Yes |
Following is the list of parameters and data types within the ACTION object:
| Parameter | Data Type | Description | Example | Mandatory |
|---|---|---|---|---|
CATALOG_ID | Integer | ID for the catalog you want to use for this message. Retrieve this ID via Commerce Manager. | 64XXXXXXXX511924 | Yes |
PRODUCT_RETAILER_ID | String | A product’s unique identifier. Retrieve this ID via Commerce Manager. | Blue_Tshirt | Yes |
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:
| 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. | 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 | Example | Mandatory |
|---|---|---|---|---|
CATALOG_ID | Integer | ID for the catalog you want to use for this message. Retrieve this ID via Commerce Manager. | 64XXXXXXXX511924 | Yes |
SECTIONS | JSON | Array 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:
| Parameter | Data Type | Description | Example | Mandatory |
|---|---|---|---|---|
TITLE | String | Include a title for each section if you plan to use more than one. | Tshirt | Yes |
PRODUCT_ITEMS | JSON | Array 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:
| Parameter | Data Type | Description | Example | Mandatory |
|---|---|---|---|---|
PRODUCT_RETAILER_ID | String | A product’s unique identifier. Retrieve this ID via Commerce Manager. | Blue_Tshirt | Yes |
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": {}
}
Updated 5 months ago