WhatsApp Promotion APIs
The WhatsApp Promotion APIs allow businesses to launch and manage promotional campaigns through WhatsApp. These APIs support creating promotions, tracking performance, and managing campaign lifecycle.
Prerequisites
- WhatsApp Business Account: Active WhatsApp Business account with approved templates
- Msgkart Account: An active Msgkart account with API Key
- CSV File Upload (Optional): For bulk promotions with uploaded contact lists
Launch WhatsApp Promotion with Form Data
Creates and launches a new WhatsApp promotional campaign.
Request Syntax
POST api/v2/promotion/{{msgkartId}}/template/launch?name={{nameOfTargetList}}
Request headers
"x-api-key": "<API KEY>"
Form Data
Use multipart/form-data to upload the CSV file along with the request body.
file: {{csvFile}}
body: JSON
{
"name": "{{promotionName}}",
"promotionType": "IMMEDIATE",
"promotionBase": "TEMPLATE",
"promotionTemplateType": "TEMPLATE",
"phoneNumberId":"{{phoneNumberId}}",
"template": {
"name": "{{tempalteName}}",
"language": "{{templateLanguage}}",
"components": [
{
"type": "CAROUSEL",
"cards": [
{
"card_index": 0,
"components": [
{
"type": "BODY",
"variables": [
{
"type": "text",
"value": "${name}"
},
{
"type": "text",
"value": "${phone}"
},
{
"type": "text",
"value": "${language}"
},
{
"type": "text",
"value": "${businesssubscriberid}"
},
{
"type": "text",
"value": "${name}"
},
{
"type": "text",
"value": "${language}"
},
{
"type": "text",
"value": "${phone}"
}
]
},
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "{{mediaUrl}}"
}
}
]
},
{
"card_index": 1,
"components": [
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "{{mediaUrl}}"
}
}
]
}
]
}
]
},
"channelType": "whatsapp"
}
Launch WhatsApp Promotion On an Uploaded list
Launches an WhatsApp promotional campaign targeting contacts from an uploaded CSV file with rich interactive content.
Request Syntax
POST api/v2/promotion/{{msgkartId}}/template/launch?name={{nameOfTargetList}}
Request headers
"x-api-key": "<API KEY>"
Request Body
{
"name": "{{promotionName}}",
"promotionType": "IMMEDIATE",
"promotionBase": "TEMPLATE",
"promotionTemplateType": "TEMPLATE",
"phoneNumberId":"{{phoneNumberId}}",
"template": {
"name": "{{tempalteName}}",
"language": "{{templateLanguage}}",
"components": [
{
"type": "CAROUSEL",
"cards": [
{
"card_index": 0,
"components": [
{
"type": "BODY",
"variables": [
{
"type": "text",
"value": "${name}"
},
{
"type": "text",
"value": "${phone}"
},
{
"type": "text",
"value": "${language}"
},
{
"type": "text",
"value": "${businesssubscriberid}"
},
{
"type": "text",
"value": "${name}"
},
{
"type": "text",
"value": "${language}"
},
{
"type": "text",
"value": "${phone}"
}
]
},
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "{{mediaUrl}}"
}
}
]
},
{
"card_index": 1,
"components": [
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "{{mediaUrl}}"
}
}
]
}
]
}
]
},
"channelType": "whatsapp"
}
Get Promotions
Retrieves all WhatsApp promotions for a specific business account.
Request Syntax
GET /api/v2/promotion/{{msgkartId}}
Request headers
"x-api-key": "<API KEY>"
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
Response Body
{
"totalItems": 811,
"promotions": [
{
"promotionId": "{{promotionId}}",
"businessId": "{{businessId}}",
"msgkartId": "{{msgkartId}}",
"name": "{{promotionName}}",
"channelType": "whatsapp",
"status": "Completed",
"createdBy": null,
"promotionType": "IMMEDIATE",
"targetSource": "CSV",
"targetType": "{{targetType}}",
"flowId": null,
"flowName": null,
"promotionBase": null,
"attributionWindow": 0,
"promotionEndTime": 1765385829,
"createdDate": 1765385766
}
]
}
Get Promotion Statistics Report
Retrieves detailed statistics report for a specific WhatsApp promotion campaign in CSV format.
Request Syntax
GET /api/v2/promotion/{{msgkartId}}/statistics/{{promotionId}}/report
Request headers
"x-api-key": "<API KEY>"
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
promotionId | string | Yes | ID of the promotion |
Response Body (CSV Format)
Name,Phone,Status,Timestamp,Error,FlowId,FlowName,RetryCount,TemplateName,Language
{{name}},{{phone}},{{status}},{{timestamp}},{{error}},{{flowId}},{{flowName}},{{retryCount}},{{templateName}},{{language}}
Get Promotion Stats
Retrieves real-time statistics for a specific WhatsApp promotion.
Request Syntax
GET /api/v2/promotion/{{msgkartId}}/{{promotionId}}/stats
Request headers
"x-api-key": "<API KEY>"
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
promotionId | string | Yes | ID of the promotion |
Response Body
{
"attempted": 8,
"failed": 2,
"sent": 0,
"delivered": 0,
"read": 6,
"interacted": 0,
"optout": 0,
"statsReport": [
{
"attempted": 8,
"failed": 2,
"sent": 0,
"delivered": 0,
"read": 6,
"interacted": 0,
"optout": 0,
"promotionRetryNumber": 0
}
]
}
Cancel WhatsApp Promotion
This action is allowed only during the promotion preparation phase. Once cancelled, the promotion will not exist and cannot be resumed.
Request Syntax
PATCH /api/v2/promotion/{{msgkartId}}/{{promotionId}}
Request headers
"x-api-key": "<API KEY>"
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
promotionId | string | Yes | ID of the promotion to Cancel |
Request Body
{
"type": "status",
"status": "Stopped"
}
Status Values
| Value | Description |
|---|---|
Stopped | Temporarily stop the promotion (can be resumed) |
Cancelled | Permanently cancel the promotion (cannot be resumed) |
Response Body
{
"promotionId": "{{promotionId}}",
"businessId": "{{businessId}}",
"msgkartId": "{{msgkartId}}",
"name": "{{promotionName}}",
"targetListId": "{{targetListId}}",
"targetListName": "{{targetListName}}",
"phoneNumberId": "{{phoneNumberId}}",
"template": {
"name": "{{templateName}}",
"id": "{{templateId}}",
"language": "{{templateLanguage}}",
"category": "{{templateCategory}}",
"components": [
{
"variables": [
{
"type": "text",
"value": "{{name}}"
}
],
"type": "BODY"
},
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "https://media.msgkart.com/107698525673716/48b4e7cead794afdbb9b42c3eb417481.jpeg",
"fileName": "msgkart_healthcare"
}
}
]
},
"createdDate": 1765777610,
"startTime": 0,
"mostRecentStartTime": 0,
"status": "Cancelled",
"createdBy": "a599947d-bc5c-4b45-b93c-5a318e2e2243",
"promotionType": "IMMEDIATE",
"scheduleTime": "0",
"targetSource": "CSV",
"tagSearchCriteria": "ANY",
"retryPromotion": true,
"maxRetries": 3,
"retriesLeft": 3,
"channelType": "whatsapp",
"batchSize": 0,
"batchTimer": 0,
"staggered": false,
"subscriberLimitPerGroup": 0,
"attributionWindow": 0,
"promotionBase": "TEMPLATE",
"promotionEndTime": 1765777679,
"callCampaign": false,
"utilityTemplateIndex": 0,
"stopOnCategoryUpdate": false
}
Properties
| Property | Description | Sample |
|---|---|---|
campaignName | Name of the promotional campaign | Summer Sale 2024 |
templateName | WhatsApp template name to use | promo_template |
language | Language code for the template | en_US |
targetAudience | Target audience segment | all, premium, new |
uploadedListId | ID of the uploaded contact list | list_xyz789 |
scheduledTime | Scheduled launch time (ISO 8601 format) | 2024-12-20T10:00:00Z |
status | Promotion status | scheduled, active, paused, completed |