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.

Access Campaigns

Create Campaign

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

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

Parameter	Type	Description
`campaignId`	String	Campaign ID

Request example

1 curl --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

Code	Description
`200`	Campaign details returned successfully
`400`	Invalid request parameters
`404`	Campaign 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

Parameter	Type	Description
`campaignId`	String	Campaign ID

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

Request example

1 curl --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

Code	Description
`204`	Campaign deleted successfully
`400`	Invalid request parameters
`404`	Campaign 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

Parameter	Type	Description
`campaignId`	int64	Campaign ID

Body parameters

Parameter	Type	Description
`campaignName`	String	Campaign name
`campaignStatus`	String	Campaign status
`rescheduleFor`	String	UTC 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`
`recipients`	Object	Lists and segments to include or exclude

Recipients object

Parameter	Type	Description
`excludedListIds`	int64[]	List IDs to exclude from the campaign
`listIds`	int64[]	Required if `scheduledAt` is provided. List IDs to send the campaign to
`segments`	int64[]	Required if `listIds` is not used. Segment IDs to send the campaign to

Request example

1 curl --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

Code	Description
`204`	Campaign updated successfully
`400`	Invalid 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

Parameter	Type	Description
`startDate`	String	Required if `endDate` is used. Starting UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter templates. Include timezone for accuracy
`endDate`	String	Required if `startDate` is used. Ending UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter templates. Include timezone for accuracy
`limit`	int64	Number of documents per page
`offset`	int64	Index of the first document in the page
`sort`	String	Sort order: `asc` or `desc`. Default is `desc`

Request example

1 curl --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

Code	Description
`200`	Templates retrieved successfully
`400`	Invalid 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

Parameter	Type	Description
`name`	String	Campaign name
`templateId`	Integer	ID of an approved WhatsApp template
`scheduledAt`	String	UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to schedule delivery. Include timezone for accuracy. Example: `2017-06-01T12:30:00+02:00`
`recipients`	Object	Lists and segments to include or exclude

Recipients object

Parameter	Type	Description
`excludedIds`	int64[]	List IDs to exclude from the campaign
`listIds`	int64[]	Required if `scheduledAt` is provided. List IDs to send the campaign to
`segments`	int64[]	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

1 curl --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

Code	Description
`201`	Campaign created successfully
`400`	Invalid 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

Parameter	Type	Description
`startDate`	String	Required if `endDate` is used. Starting UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter campaigns. Include timezone for accuracy
`endDate`	String	Required if `startDate` is used. Ending UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter campaigns. Include timezone for accuracy
`limit`	int64	Number of documents per page
`offset`	int64	Index of the first document in the page
`sort`	String	Sort order: `asc` or `desc`. Default is `desc`

Request example

1 curl --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

Code	Description
`200`	Campaigns retrieved successfully
`400`	Invalid 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

Parameter	Type	Description
`name`	String	Template name
`language`	String	Template language code (e.g., `en`)
`category`	String	Template category: `MARKETING` or `TRANSACTIONAL`
`mediaUrl`	String	Absolute URL of the media file for the header. Use when `headerText` is empty. Allowed formats: jpeg, png, mp4, pdf
`bodyText`	String	Template body text. Maximum 1024 characters
`headerText`	String	Template header text. Maximum 45 characters. Use when `mediaUrl` is empty

Request example

1 curl --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

Code	Description
`201`	Template created successfully
`400`	Invalid 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

Parameter	Type	Description
`templateId`	int64	Template ID

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

Request example

1 curl --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

Code	Description
`200`	Template submitted for approval successfully
`400`	Invalid 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

1 curl --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

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

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

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

1	curl --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	}'

1	curl --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'

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	}

1	curl --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	}'

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	}

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