Send Order Details Template Message

An 'order detail' template message enables businesses to send an invoice or an order details message in a predefined format with 'call-to-action' button components. The order detail template message supports paying the order with payment integrations, such as UPI Intent.
The end-to-end business transaction with 'order details template message' provides an overall better user experience compared to the other standard messaging services.

In the message API, add an approved 'order details' template with a predefined 'Open order details call-to-action' button.
The messaging_object of the API payload contains information about the order details template to use, call-to-action button, and payment app integration details.

The extra_info object of the payload can contain any additional details for certain functionalities.

📘

Note:

Make sure you first upload the product details on the WhatsApp Business Manager portal before sending an order details API message.

Prerequisites

  1. Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
    A prerequisite for using Kaleyra WhatsApp APIs is to have an active WhatsApp plan on kaleyra platform.
  2. To set up a WhatsApp account on kaleyra.io, see Manual Signup
    and Embedded Signup.
  3. An active WhatsApp for Business API plan that includes:
    • A WhatsApp business number.
    • An associated profile with the business number.
    • A WhatsApp verified and approved profile.
    • A WABA ID onboarded on Kaleyra WhatsApp API V2.

Base URL

https://<api_domain>/v2/<SID>

API Domain and Value

api_domainValue
IN podapi.in.kaleyra.io
SG Podapi.kaleyra.io
EU Podapi.eu.kaleyra.io
NA podapi.na.kaleyra.ai

API Request to Send an Order Details Template Message

To send an Order Details Template message, use the https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/messages
endpoint with the following request method.

Request Format

The following is the request format to send an Order Details Template message.

curl -X POST \
  https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/messages \
  -H 'Content-Type: application/json' \
  -H 'api-key: <api-key>' \
  -H 'cache-control: no-cache' \
  -d  '{
    "messaging_object": {
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": "<to_number>",
        "type": "<type>",
        "template": {
            "name": "<template_name>",
            "language": {
                "policy": "<policy>",
                "code": "<language_code>"
            },
            "components": [
                {
                    "type": "<type>",
                    "parameters": [
                        {
                            "type": "<type>", 
                            "image": {
                                "link": "<link_image_url>"
                            }
                        }
                    ]
                },
                {
                    "type": "<type>",
                    "sub_type": "<sub_type>",
                    "index": <value>,
                    "parameters": [
                        {
                            "type": "<type>",
                            "action": {
                                "order_details": {
                                    "currency": "<currency>",
                                    "order": {
                                        "discount": {
                                            "offset": <offset_value>,
                                            "value": <value>
                                        },
                                        "items": [
                                            {
                                               "amount": {
                                                "offset": <offset_value>,
                                                "value": <value>
                                                },
                                                "name": "<item_name>",
                                                "quantity": <value>,
                                                "retailer_id": "<order_item_retailer_id>",
                                                "country_of_origin": "<origin_country>",
                                                "importer_name": "<importer_name>",
                                                "importer_address": {
                                                    "address_line1": "<importer_address>",
                                                    "city": "<city>",
                                                    "country_code": "<country>",
                                                    "postal_code": "<zip_code>"
                                                }
                                            }
                                        ],
                                        "shipping": {
                                            "offset": <offset_value>,
                                            "value": <value>
                                        },
                                        "status": "<status>",
                                        "subtotal": {
                                            "offset": <offset_value>,
                                            "value": <value>
                                        },
                                        "tax": {
                                            "offset": <offset_value>,
                                            "value": <value>
                                        }
                                    },
                                    "payment_configuration": "<unique_payment_config_id>",
                                    "payment_type": "<payment_type>",
                                    "reference_id": "<reference_id_value>",
                                    "total_amount": {
                                        "offset": <offset_value>,
                                        "value": <value>
                                    },
                                    "type": "<goods_type>"
                                }
                            }
                        }
                    ]
                }
            ]
        }
    },
    "extra_info": {
        "ref": "<ref>",
        "ref1": "<ref1>",
        "ref2": "<ref2>",
        "wa_source": "<wa_source>"
    }
}'

Sample Request Format

The following example describes how to send a UPI Intent in order details template message parameters to prompt the consumer to make a payment.

curl -X POST \
  https://api.in.kaleyra.io/v2/HAXP2142XX/whatsapp/+91863XXX5920/messages \
  -H 'Content-Type: application/json' \
  -H 'api-key: AVGSCFSAFS53215634XXXXX4ac' \
  -H 'cache-control: no-cache' \
  -d  '{
    "messaging_object": {
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": "+91xxxxxxxxxx",
        "type": "template",
        "template": {
            "name": "ord_det_temp1",
            "language": {
                "policy": "deterministic",
                "code": "en_US"
            },
            "components": [
                {
                    "type": "header",
                    "parameters": [
                        {
                            "type": "image", 
                            "image": {
                                "link": "http://shop_order_image.jpg"
                            }
                        }
                    ]
                },
                {
                    "type": "button",
                    "sub_type": "order_details",
                    "index": 0,
                    "parameters": [
                        {
                            "type": "action",
                            "action": {
                                "order_details": {
                                    "currency": "INR",
                                     "order": {
                                        "discount": {
                                            "offset": 100,
                                            "value": 2500
                                            },
                                      "items": [
                                               {
                                               "amount": {
                                                "offset": 100,
                                                "value": 400
                                                },
                                        "name": "ORDER_ITEM_NAME",
                     									  "quantity": 1,
                      													"retailer_id": "ORDER_ITEM_RETAILER_ID",
                      													"country_of_origin": "countryname",
                      													"importer_name": "Mike",
                      				"importer_address": {
                        			"address_line1": "20 Main,street,sector3",
                        			"city": "New city",
                        			"country_code": "India",
                        			"postal_code": "230045"
                                                }
                                            }
                                        ],
                                         "shipping": {
                 			   "offset": 100,
                  			  "value": 0
                 			 },
                  			"status": "pending",
                  			"subtotal": {
                   			"offset": 100,
                    			"value": 400
                			  },
                  			"tax": {
                   		 	"offset": 100,
                    			"value": 500
                  			}
                        },
                       "payment_configuration": "unique_payment_config_id",
               			   "payment_type": "upi",
                		   "reference_id": "reference_id_value",
                		   "total_amount": {
                  "			offset": 100,
                  			"value": 650
                				  },
                		"type": "digital-goods"
                                }
                            }
                        }
                    ]
                }
            ]
        }
    },
     "extra_info": {
        "ref": "customer1",
        "ref1": "marketing",
        "ref2": "dictionary",
        "wa_source": "api"
    }

}'

URL Parameters and Headers

Following is the list of parameters and headers to send the outgoing message request:

Parameter / Headers

Data Type

Description

Example

Mandatory?

sid

String

Account SID (Security Identifier).

HXAP16XXXXXX97IN

Yes

phone_number

String

Phone number of the end customer you want to send a message to.

+91XXXXXXXXXX

Yes
(valid phone numbers only)

Content-Type

String

Indicates the format of the content the API will be processing.

The only allowed value is application/json.

Yes

api-key

String

API key generated from kaleyra platform account.

Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3

Yes

Following is the list of attributes to be used in the payload to send the outgoing message:

ParameterData TypeDescriptionExampleMandatory?
messaging_objectJSON objectPayload is supported only in JSON format. The messaging_object is the payload which contains the message object as defined by Meta which is used to send the WhatsApp message.See the specific table for details.Yes
extra_infoJSON objectThis object will contain additional details that a user can send for certain functionalities.See the specific table for details.No

The following table describes the different attributes used for the messaging_object JSON object:

ParameterData TypeDescriptionExampleMandatory?
messaging_productStringMessaging service used for the request.Only allowed value is whatsappYes
recipient_typeStringCurrently, you can only send messages to individuals. Default is individual.Only allowed value is individualNo
toStringWhatsApp end-user phone number. It should include country code prefix following E.164 format.+16XXXXXX234Yes
typeStringThe type of message you want to send. If omitted, defaults to text.Only allowed value for sending this message is 'template'.Yes
templateJSON ObjectDetails of the template object usedSee the specific table for details.Yes

The following table describes the different attributes of the 'template' JSON object.

ParameterData TypeDescriptionExampleMandatory?
nameStringThe name of the template used.ord_det_temp1Yes
languageJSON Object The details of the language object.See the specific table for detailsYes
componentArrayThe details of the component array.See the specific table for detailsYes

The following table describes the different attributes of the 'language' JSON object.

ParameterData TypeDescriptionExampleMandatory?
policyStringThe name of the policy used.deterministicYes
codeString The language code.en_USYes

The following tables describe the different attributes of the 'header - component'.

ParameterData TypeDescriptionExampleMandatory?
typeStringThe component type used.headerNo
parametersJSON ObjectThe header component object details.See the specific table for details.Yes

The following tables describes the different attributes of the 'header-parameters' object.

ParameterData TypeDescriptionExampleMandatory?
typeStringThe component type used.headerNo
imageJSON ObjectThe header component object details.See the specific table for details.Yes

The following tables describes the different attributes of the 'header-image' object.

ParameterData TypeDescriptionExampleMandatory?
linkStringURL link of the image to be added in the header.https://shop_order_image.jpgYes

The following table describe the different attributes of the 'button-component'.

ParameterData TypeDescriptionExampleMandatory?
typeStringThe component type used.buttonYes
sub-typeStringThe sub type of the button used.order_detailsYes
indexNumericThe order number of the button in the message.0Yes
parametersArrayThe button details to be shown when clicked.See the specific table for details.Yes

The following table describes the different attributes of the 'parameters' array.

ParameterData TypeDescriptionExampleMandatory?
typeStringThe button type to be used.actionYes
actionJSON ObjectThe button action when the button is clicked.See the specific table for details.Yes

The following table describes the different attributes of the 'action' object.

ParameterData TypeDescriptionExampleMandatory?
order_detailsJSON ObjectThe button type to be usedSee the specific table for detailsYes

The following table describes the different attributes of the 'order_details' object.

Parameter

Data Type

Description

Example

Mandatory?

Currency

String

The currency used for order payment.

INR

Yes

Order

JSON Object

The order object details

See the specific table for details

Yes

payment_configuration

String

The name of the pre-configured payment configuration to use for this order.

unique_payment_config_id

Yes

payment_type

String

The payment type used for order amount payment.

upi

Yes

reference_id

String

Unique ID given by the business.
It is case sensitive and cannot be an empty string. It can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters.

If there is a need to send multiple order_details messages for the same order, add a sequence number in the reference_id (for example, "BM345A-12") to ensure reference_id uniqueness.

reference_id_value

Yes

total_amount

JSON Object

The total order amount.

See the specific table for details.

Yes

type

String

The type of items ordered.

digital_goods

Yes

The following table describes the different attributes of the 'order' object.

Parameter

Data Type

Description

Example

Mandatory?

discount

JSON Object

The discount given on the order amount.

See the specific table for details.

Yes

items

array

The total order amount.

See the specific table for details.

Yes

shipping

JSON
Object

The shipping details.

See the specific table for details.

Yes

status

String

The order status.

Pending

Yes

sub_total

JSON Object

The sub total amount of the order.

See the specific table for details.

Yes

tax

JSON Object

The tax amount on the order.

See the specific table for details.

Yes

The following table describes the different attributes of the 'discount' object.

Data Type

Parameter

Description

Example

Mandatory?

offset

Numeric

The offset is 100 for INR.
The offset value indicates how many decimals should be considered for the currency.
INR is the only supported value.

100

Yes

value

Numeric

The discount given on the order amount.

2500

Yes

The following table describes the different attributes of the 'Items' array.

Parameter

Data Type

Description

Example

Mandatory?

amount

JSON Object

The order amount.

See the specific table for details

Yes

name

String

The name of the order.

ORDER_ITEM_NAME

Yes

quantity

Numeric

The item quantity in the order.

1

Yes

retailer_id

String

The ID of the retailer.

ORDER_ITEM_RETAILER_ID

Yes

country_or_origin

String

The country in which the order is placed.

countryname

Yes

importer_name

String

The name of the person who has placed the order.

Mike

Yes

importer_address

JSON
Object

The address of the person that has placed the order.

See the specific table for details.

Yes

The following table describes the different attributes of the 'shipping' object.

Parameter

Data Type

Description

Example

Mandatory?

offset

Numeric

The offset is 100 for INR.
The offset value indicates how many decimals should be considered for the currency.
INR is the only supported value.

100

Yes

value

Numeric

The total order amount.

650

Yes

The following table describes the different attributes of the 'sub_total' object.

Data Type

Parameter

Description

Example

Mandatory?

offset

Numeric

The offset is 100 for INR.
The offset value indicates how many decimals should be considered for the currency.
INR is the only supported value.

100

Yes

value

Numeric

The shipping amount.

0

Yes

The following table describes the different attributes of the 'tax' object.

Parameter

Data Type

Description

Example

Mandatory?

offset

Numeric

The offset is 100 for INR.
The offset value indicates how many decimals should be considered for the currency.
INR is the only supported value.

100

Yes

value

Numeric

The tax amount charged on the order.

500

Yes

The following table describes the different attributes of the 'amount' object.

Parameter

Data Type

Description

Example

Mandatory?

offset

Numeric

The offset is 100 for INR.
The offset value indicates how many decimals should be considered for the currency.
INR is the only supported value.

100

Yes

value

Numeric

The order amount.

400

Yes

The following table describes the different attributes of the 'importer_address' object.

Parameter

Data Type

Description

Example

Mandatory?

addressline1

String

The button type to be used

20 Main,street,
sector3

Yes

city

String

The button action when the button is clicked

New city

Yes

country_code

String

The country to which the importer belongs.

India

Yes

postal_code

String

The postal code of the coutnry to which the importer belongs.

230045

Yes


The following table describes the different attributes used for the extra_info object.

Parameter

Data Type

Description

Example

Mandatory?

ref

String

Include any contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more.
Limit: The variable can be 255 characters long only. This parameter will be available in report and callback.

customer1

No

ref1

String

Include the contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more.
Limit: The variable can be 255 characters long only. This parameter will be available in report and callback.

marketing

No

ref2

String

Include the contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more.
Limit: The variable can be 255 characters long only. This parameter will be available in report and callback.

dictionary

No

wa_source

String

Indicates the source from where the API has been triggered. Supported values for wa_source are "api", "clevertap", "zoho", "webengage", "shopify", "leadsquared", "responsys", "braze", "hubspot", "salesforce", "zapier", "eloqua", and "moengage".
Note: If the customer passes any other value other than above specified values, then the system will override that as the "API".

api

No

Sample Success Response

The following success message appears with the status 202 Accepted:

202 Accepted 
{
"code":"WA202"
"message":"Request Accepted",
"data":{
  "message_id":"AXXXXXXXXXXXXXXXXXXX"
}
"error":{}
}

Sample Failure Response

The following are the failure responses:

401 Unauthorized
{
    "code": "RBC001",
    "message": "Incorrect SID or API key.",
    "data": [],
    "error": {
        "error": "Incorrect SID or API key."
    }
}
401 Unauthorized phone number
{
    "code": "WA401",
    "message": "Phone number is not present or does not belong to the account.",
    "data": {},
    "error": {
        "phone_number": "Phone number is not present or does not belong to the account."
    }
}
400 Incorrect payload
{
    "code": "WA400",
    "message": "Refer to correct payload format",
    "data": {},
    "error": {
        "payload": "Incorrect payload format"
    }
}
500 Internal Server Error
{
    "code": "WA500",
    "message": "Please try again later",
    "data": {},
    "error": {
        "error": "Internal server error"
    }
}
400 Low balance
{
    "code": "E110",
    "message": "Please check your balance, You have a low balance!",
    "data": {},
    "error": {
        "balance": "Please check your balance, You have a low balance!"
    }
}
401 Unauthorised Account type
{
    "code": "WA-401",
    "message": "API is not available for given customer.Please contact support for more info",
    "data": {},
    "error": {
        "account": "API is not available for given customer.Please contact support for more info"
    }
}
401 Unauthorized phone number version
{
    "code": "WA-401",
    "message": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint.",
    "data": {},
    "error": {
        "phone_number": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint."
    }
}