Marketing Platform

WhatsApp campaigns

Learn how to create and manage WhatsApp campaigns using the Brevo API

Overview

The WhatsApp Campaigns API enables you to programmatically create and manage WhatsApp marketing campaigns. Use the API to:

  • Create and manage WhatsApp campaigns and templates
  • Broadcast messages to contact lists and segments
  • Retrieve campaign statistics and performance metrics
  • Schedule and update campaign delivery

You need access to the WhatsApp Campaigns feature in your Brevo account. See the activation section below.

Activating WhatsApp

Before using the WhatsApp Campaigns API, activate WhatsApp in your Brevo account.

1

Access Campaigns

Log in to your Brevo account and navigate to Campaigns from the left sidebar.

2

Create Campaign

Click Create Campaign in the top-right corner of the Campaigns page.

3

Select WhatsApp

Under Standard campaigns, select WhatsApp to activate the feature on your account.

After activation, you must link your WhatsApp Business account to Brevo. For detailed setup instructions, see the WhatsApp onboarding guide.

Get a WhatsApp campaign

Retrieve details for a specific WhatsApp campaign.

Endpoint

GET https://api.brevo.com/v3/whatsappCampaigns/{campaignId}

Path parameters

ParameterTypeDescription
campaignIdStringCampaign ID

Request example

1curl --request GET \
2     --url https://api.brevo.com/v3/whatsappCampaigns/465908589032810 \
3     --header 'accept: application/json' \
4     --header 'api-key: YOUR_API_KEY'

Response codes

CodeDescription
200Campaign details returned successfully
400Invalid request parameters
404Campaign ID not found or not accessible

Delete a WhatsApp campaign

Delete a WhatsApp campaign. You cannot delete campaigns that are currently being sent.

Endpoint

DELETE https://api.brevo.com/v3/whatsappCampaigns/{campaignId}

Path parameters

ParameterTypeDescription
campaignIdStringCampaign ID

Retrieve the campaignId from the Brevo WhatsApp dashboard or use the get all campaigns endpoint.

Request example

1curl --request DELETE \
2     --url https://api.brevo.com/v3/whatsappCampaigns/465908589032810 \
3     --header 'accept: application/json' \
4     --header 'api-key: YOUR_API_KEY'

Response codes

CodeDescription
204Campaign deleted successfully
400Invalid request parameters
404Campaign ID not found or not accessible

Update a WhatsApp campaign

Update campaign details, including status, recipients, and scheduling.

Endpoint

PUT https://api.brevo.com/v3/whatsappCampaigns/{campaignId}

For detailed parameter information, see the API reference.

Path parameters

ParameterTypeDescription
campaignIdint64Campaign ID

Body parameters

ParameterTypeDescription
campaignNameStringCampaign name
campaignStatusStringCampaign status
rescheduleForStringUTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to reschedule the campaign. Include timezone for accurate results. Example: 2017-06-01T12:30:00+02:00
recipientsObjectLists and segments to include or exclude

Recipients object

ParameterTypeDescription
excludedListIdsint64[]List IDs to exclude from the campaign
listIdsint64[]Required if scheduledAt is provided. List IDs to send the campaign to
segmentsint64[]Required if listIds is not used. Segment IDs to send the campaign to

Request example

1curl --request PUT \
2     --url https://api.brevo.com/v3/whatsappCampaigns/5678 \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --header 'api-key: YOUR_API_KEY' \
6     --data '{
7  "campaignStatus": "scheduled",
8  "recipients": {
9    "excludedListIds": [8],
10    "listIds": [32],
11    "segments": [23]
12  },
13  "campaignName": "Test WhatsApp",
14  "rescheduleFor": "2017-06-01T12:30:00+02:00"
15}'

Response codes

CodeDescription
204Campaign updated successfully
400Invalid or missing parameters

Get all WhatsApp templates

Retrieve all created WhatsApp templates with optional filtering.

Endpoint

GET https://api.brevo.com/v3/whatsappCampaigns/template-list

Query parameters

ParameterTypeDescription
startDateStringRequired if endDate is used. Starting UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter templates. Include timezone for accuracy
endDateStringRequired if startDate is used. Ending UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter templates. Include timezone for accuracy
limitint64Number of documents per page
offsetint64Index of the first document in the page
sortStringSort order: asc or desc. Default is desc

Request example

1curl --request GET \
2     --url 'https://api.brevo.com/v3/whatsappCampaigns/template-list?startDate=2022-05-01T12%3A30%3A00Z&endDate=2022-07-01T12%3A30%3A00Z&limit=50&offset=0&sort=asc' \
3     --header 'accept: application/json' \
4     --header 'api-key: YOUR_API_KEY'

Response example

1{
2  "count": 2,
3  "templates": [
4    {
5      "id": 235,
6      "name": "campaign_22",
7      "type": "whatsapp",
8      "status": "approved",
9      "language": "en",
10      "category": "MARKETING",
11      "errorReason": "NONE",
12      "createdAt": "2017-05-01T12:30:00Z",
13      "modifiedAt": "2017-05-01T12:30:00Z"
14    }
15  ]
16}

Response codes

CodeDescription
200Templates retrieved successfully
400Invalid or missing parameters

Create and send a WhatsApp campaign

Create a new WhatsApp campaign and schedule it for delivery.

Endpoint

POST https://api.brevo.com/v3/whatsappCampaigns

Body parameters

ParameterTypeDescription
nameStringCampaign name
templateIdIntegerID of an approved WhatsApp template
scheduledAtStringUTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to schedule delivery. Include timezone for accuracy. Example: 2017-06-01T12:30:00+02:00
recipientsObjectLists and segments to include or exclude

Recipients object

ParameterTypeDescription
excludedIdsint64[]List IDs to exclude from the campaign
listIdsint64[]Required if scheduledAt is provided. List IDs to send the campaign to
segmentsint64[]Required if listIds is not used. Segment IDs to send the campaign to

Get list and segment IDs using the get all lists and get all segments endpoints.

Request example

1curl --request POST \
2     --url https://api.brevo.com/v3/whatsappCampaigns \
3     --header 'accept: application/json' \
4     --header 'api-key: YOUR_API_KEY' \
5     --header 'content-type: application/json' \
6     --data '{
7  "recipients": {
8    "excludedIds": [8],
9    "listIds": [32],
10    "segments": [23]
11  },
12  "name": "Test Campaign",
13  "templateId": 19,
14  "scheduledAt": "2017-06-01T12:30:00+02:00"
15}'

Response example

1{
2  "id": 5
3}

Response codes

CodeDescription
201Campaign created successfully
400Invalid parameters, duplicate campaign, or template not approved

Get all WhatsApp campaigns

Retrieve all WhatsApp campaigns with optional filtering.

Endpoint

GET https://api.brevo.com/v3/whatsappCampaigns

Query parameters

ParameterTypeDescription
startDateStringRequired if endDate is used. Starting UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter campaigns. Include timezone for accuracy
endDateStringRequired if startDate is used. Ending UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter campaigns. Include timezone for accuracy
limitint64Number of documents per page
offsetint64Index of the first document in the page
sortStringSort order: asc or desc. Default is desc

Request example

1curl --request GET \
2     --url 'https://api.brevo.com/v3/whatsappCampaigns?startDate=2017-05-01T12%3A30%3A00Z&endDate=2017-07-01T12%3A30%3A00Z&limit=50&offset=0&sort=desc' \
3     --header 'accept: application/json' \
4     --header 'api-key: YOUR_API_KEY'

Response example

1{
2  "count": 23,
3  "campaigns": [
4    {
5      "id": 1672035851100690,
6      "campaignName": "campaign_22",
7      "campaignStatus": "sent",
8      "templateId": 637660278078655,
9      "scheduledAt": "2022-12-27T09:50:00Z",
10      "errorReason": "",
11      "invalidatedContacts": 0,
12      "stats": {
13        "sent": 3,
14        "delivered": 3,
15        "read": 2,
16        "unsubscribe": 0,
17        "notSent": 4
18      },
19      "readPercentage": 28.57,
20      "createdAt": "2017-05-01T12:30:00Z",
21      "modifiedAt": "2017-05-01T12:30:00Z"
22    }
23  ]
24}

Response codes

CodeDescription
200Campaigns retrieved successfully
400Invalid or missing parameters

Create a WhatsApp template

Create a new WhatsApp template. Templates must be approved before use in campaigns.

Endpoint

POST https://api.brevo.com/v3/whatsappCampaigns/template

Body parameters

ParameterTypeDescription
nameStringTemplate name
languageStringTemplate language code (e.g., en)
categoryStringTemplate category: MARKETING or TRANSACTIONAL
mediaUrlStringAbsolute URL of the media file for the header. Use when headerText is empty. Allowed formats: jpeg, png, mp4, pdf
bodyTextStringTemplate body text. Maximum 1024 characters
headerTextStringTemplate header text. Maximum 45 characters. Use when mediaUrl is empty

Request example

1curl --request POST \
2     --url https://api.brevo.com/v3/whatsappCampaigns/template \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --header 'api-key: YOUR_API_KEY' \
6     --data '{
7  "category": "MARKETING",
8  "name": "Test template",
9  "language": "en",
10  "mediaUrl": "https://attachment.domain.com",
11  "bodyText": "making it look like readable English",
12  "headerText": "Test WhatsApp campaign"
13}'

Response example

1{
2  "id": 5
3}

Response codes

CodeDescription
201Template created successfully
400Invalid parameters, duplicate template, or account validation required

For detailed error information, see the API reference.

Send WhatsApp template for approval

Submit a template for WhatsApp approval. Approved templates can be used in campaigns.

Endpoint

POST https://api.brevo.com/v3/whatsappCampaigns/template/approval/{templateId}

Path parameters

ParameterTypeDescription
templateIdint64Template ID

Get the templateId from the response when creating a WhatsApp template.

Request example

1curl --request POST \
2     --url https://api.brevo.com/v3/whatsappCampaigns/template/approval/5 \
3     --header 'accept: application/json' \
4     --header 'api-key: YOUR_API_KEY'

Response codes

CodeDescription
200Template submitted for approval successfully
400Invalid parameters or unauthorized

Get WhatsApp API account information

Retrieve your WhatsApp Business account information, including sending limits and account status.

Endpoint

GET https://api.brevo.com/v3/whatsappCampaigns/config

Request example

1curl --request GET \
2     --url https://api.brevo.com/v3/whatsappCampaigns/config \
3     --header 'accept: application/json' \
4     --header 'api-key: YOUR_API_KEY'

Response example

1{
2  "whatsappBusinessAccountID": 105569359072383,
3  "sendingLimit": "TIER_1K",
4  "phoneNumberQuality": "GREEN",
5  "whatsappBusinessAccountStatus": "APPROVED",
6  "businessStatus": "verified",
7  "phoneNumberNameStatus": "APPROVED"
8}

Response codes

CodeDescription
200Account information retrieved successfully
400Invalid parameters, insufficient credits, or account validation required
503Service unavailable