Send Coupon Code Template Messages
The 'Send Coupon Code Template API' message enables you to send coupon code messages to customers.
The 'messaging_object' in the payload holds the information about the coupon code template used in the message, and the 'copy code' button that carries the 'coupon code'.
The extra_info part of the payload contains any additional information related to the API requests submitted to send the coupon code message.
Note:
Before sending a Coupon Code message, make sure to have a 'Coupon Code template' that you can use in the 'Send Coupon Code Message' API.
For information on how to create a Coupon Code Template, see: Create a Coupon Code Template
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.
Base URL
https://<api_domain>/v2/<SID>
API Domains and Values
api_domain | Value |
---|---|
IN pod | https://api.in.kaleyra.io/ |
SG Pod | https://api.ap.kaleyra.io/ |
EU Pod | https://api.eu.kaleyra.io/ |
API Request to Send Coupon Code Message
To send coupon code messages, use the endpoint with the following request method:
https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/messages
Request Format
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": "<messaging_product>",
"to": "<to>",
"type": "<type>",
"template": {
"name": "<name>",
"language": {
"code": "<code>"
},
"components": [
{
"type": "<type>",
"sub_type": "<sub_type>,
"index": <index>,
"parameters": [
{
"type": "<type>",
"coupon_code": "<coupon_code>"
}
]
}
]
}
},
"extra_info": {
"ref": "ref",
"ref1": "ref1",
"ref2": "ref2",
"wa_source": "<wa_source>"
}
}'
Sample Request Format
The following is the sample request format to send a coupon code message.
curl -X POST \
'https://api.in.kaleyra.io/v2/xxxxx6913850xxxx/whatsapp/+XX731xxxx124/messages' \
-H 'Content-Type: application/json' \
-H 'api-key: xxxxx3b8497f58a94e84b671aca43xxxx' \
-H 'cache-control: no-cache' \
-d '{
"messaging_object":
{
"messaging_product": "whatsapp",
"to": "+91xxxxxxxxxxxx",
"type": "template",
"template": {
"name": "cc_img_statics20",
"language": {
"code": "en_US"
},
"components": [
{
"type": "button",
"sub_type": "COPY_CODE",
"index": 0,
"parameters": [
{
"type": "coupon_code",
"coupon_code": "2532334"
}
]
}
]
}
},
"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 | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
sid | String | Account SID (Security Identifier). | Account SID (Security Identifier). | Yes |
phone_number | String | Phone number of end customer you want to send a message to. | +91xxxxxxxxxx | Yes |
content_type | String | Indicates the format of the content the API will be processing. | The only value allowed 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 object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
messaging_product | String | Messaging service used for the request. | The only value allowed is 'whatsapp'. | Yes |
to | String | WhatsApp end-user phone number. It should include country code prefix following E.164 format. | +91xxxxxxxxxx | Yes |
type | String | The type of message you want to send. If omitted, defaults to text. | template | No |
template | Object | The template used to send the coupon code message. | See the specific table for details. | Yes |
The following table describes the parameters of the 'template' object.
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
name | String | The name of the template to be used. | cc_img_statics20 | Yes |
language | Object | The language used in the template. | See the specific table for details. | Yes |
components | Object | The components in the template. | See the specific table for details. | Yes |
The following table describes the parameters of the 'language' object.
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
code | String | The code of the language used in the template | en_US | Yes |
The following table describes the parameters of the 'components' object.
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
type | String | The type of the component used in the template. | button | Yes |
sub_type | String | The sub type of the component used in the template. | COPY_CODE | Yes |
index | Numeric | The order in which the button should appear, if the template uses multiple buttons. | 0 | Yes |
parameters | Object | The type of value and the value associated with the button. | See specific table for details | Yes |
The following table describes the parameters of the 'parameters' object.
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
type | String | The type of parameter to be copied when the user taps the button. | coupon_code | Yes |
coupon_code | String | The coupon code that the user can copy to avail discount. | 2532334 | Yes |
The following table describes the different attributes used for the extra_info
JSON 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":{}
}
Failure Responses
Following are the error responses for the API level and the business level validations.
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 about 15 hours ago