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
Creates and launches a new WhatsApp promotional campaign.
Request Syntax
POST api/v2/promotion/{{msgkartId}}/template/launch?name={{nameOfTargetList}}
Form Data
Use multipart/form-data to upload the CSV file along with the request body.
file: {{csvFile}}
body: JSON
{
"businessId": "{{msgkartId}}",
"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": "https://image.jpeg"
}
}
]
},
{
"card_index": 1,
"components": [
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "https://image.jpeg"
}
}
]
}
]
}
]
},
"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 Body
{
"businessId": "{{msgkartId}}",
"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": "https://image.jpeg"
}
}
]
},
{
"card_index": 1,
"components": [
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "https://image.jpeg"
}
}
]
}
]
}
]
},
"channelType": "whatsapp"
}
Get Promotions
Retrieves all WhatsApp promotions for a specific business account.
Request Syntax
GET /api/v2/promotion/{{msgkartId}}
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
Response Body
{
"totalItems": 811,
"promotions": [
{
"promotionId": "5d58cb288b0d46ffbe839fec303f8bb4",
"businessId": "107698525673716",
"msgkartId": "107698525673716",
"name": "Adil testing",
"channelType": "whatsapp",
"status": "Completed",
"createdBy": null,
"promotionType": "IMMEDIATE",
"targetSource": "CSV",
"targetType": "Digitap 1.csv_1765385758146",
"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
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
Datta,919986014713,read,10 Dec 2025 10:27 PM,null,null,0,cpr_adil,en_US
Joel,919895566812,failed,10 Dec 2025 10:27 PM,This message was not delivered to maintain healthy ecosystem engagement.,null,null,0,cpr_adil,en_US
Get Promotion Stats
Retrieves real-time statistics for a specific WhatsApp promotion.
Request Syntax
GET /api/v2/promotion/{{msgkartId}}/{{promotionId}}/stats
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
}
]
}
Update Promotion Status
Updates the status of a WhatsApp promotion (stop or cancel).
Request Syntax
PATCH /api/v2/promotion/{{msgkartId}}/{{promotionId}}
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
promotionId | string | Yes | ID of the promotion to update |
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": "a33a29a41afb40e5a5bca1d333b8d998",
"businessId": "107698525673716",
"msgkartId": "107698525673716",
"name": "response",
"targetListId": "4d47d5f540a74abea1b23f4ebeb4664d",
"targetListName": "adilMaheshHariKris",
"phoneNumberId": "126875363728090",
"template": {
"name": "abc_adil_nawaz",
"id": "701692262430813",
"language": "en_US",
"category": "MARKETING",
"components": [
{
"variables": [
{
"type": "text",
"value": "Adil"
}
],
"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 |