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

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.
To set up a WhatsApp account on kaleyra.io, see Manual Signup
and Embedded Signup.
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_domain	Value
IN pod	api.in.kaleyra.io
SG Pod	api.kaleyra.io
EU Pod	api.eu.kaleyra.io
NA pod	api.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:

Parameter	Data Type	Description	Example	Mandatory?
`messaging_object`	JSON object	Payload 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_info`	JSON object	This 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:

Parameter	Data Type	Description	Example	Mandatory?
messaging_product	String	Messaging service used for the request.	Only allowed value is whatsapp	Yes
recipient_type	String	Currently, you can only send messages to individuals. Default is individual.	Only allowed value is individual	No
to	String	WhatsApp end-user phone number. It should include country code prefix following E.164 format.	+16XXXXXX234	Yes
type	String	The type of message you want to send. If omitted, defaults to text.	Only allowed value for sending this message is 'template'.	Yes
template	JSON Object	Details of the template object used	See the specific table for details.	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
name	String	The name of the template used.	ord_det_temp1	Yes
language	JSON Object	The details of the language object.	See the specific table for details	Yes
component	Array	The details of the component array.	See the specific table for details	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
policy	String	The name of the policy used.	deterministic	Yes
code	String	The language code.	en_US	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
type	String	The component type used.	header	No
parameters	JSON Object	The header component object details.	See the specific table for details.	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
type	String	The component type used.	header	No
image	JSON Object	The header component object details.	See the specific table for details.	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
link	String	URL link of the image to be added in the header.	https://shop_order_image.jpg	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
type	String	The component type used.	button	Yes
sub-type	String	The sub type of the button used.	order_details	Yes
index	Numeric	The order number of the button in the message.	0	Yes
parameters	Array	The 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.

Parameter	Data Type	Description	Example	Mandatory?
type	String	The button type to be used.	action	Yes
action	JSON Object	The 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.

Parameter	Data Type	Description	Example	Mandatory?
order_details	JSON Object	The button type to be used	See the specific table for details	Yes

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."
    }
}

Updated 2 days ago