WhatsApp Campaigns
Learn how to integrate WhatsApp Campaigns
WhatsApp campaigns allows you to stay connected with your customers. Reach out through the world's biggest messaging platform. WhatsApp campaigns APIs allow you to:
- Programatically define campaigns and templates.
- Broadcast marketing messages to all your contacts.
- Fetch statistics for your campaigns.
- Manage the sending of transactional messages and campaigns.
Activating WhatsApp
- You need to log in to your Brevo Account.
- At the top navigation bar, you can find all the applications enabled on your account.
- Choose
Add more apps
and you will find Apps and Integration. - Under Apps, scroll down and enable the WhatsApp campaigns feature.
- You will find WhatsApp campaigns activated in your Brevo dashboard.
After activating WhatsApp, you have to sign up for Facebook and WhatsApp business accounts. You can refer to the help articles in the Brevo resources regarding the WhatsApp onboarding at Whatsapp and SMS > Getting started with WhatsApp campaigns in Brevo.
Introduction
Here you will find an overview of the WhatsApp Campaigns API. The actions available are fetching details of your WhatsApp campaigns or you can delete a WhatsApp campaign through the endpoints along with returning the details of your created WhatsApp templates and campaigns. You can also create and send a WhatsApp campaign and get your WhatsApp API account information. You can check the endpoints on the Brevo API reference site at API Reference > WhatsApp campaigns.
Requirements
To create and manage your Whatsapp campaigns you need to have access to the WhatsApp Campaigns app. If you have not already activated the WhatsApp platform on your account you can go to Whatsapp Campaigns > Activating WhatsApp Campaigns.
1. Get WhatsApp campaign
You can call the endpoint https://api.brevo.com/v3/whatsappCampaigns/{campaignId}
with the method GET
. The cURL request for the endpoint is:
curl --request GET \
--url https://api.brevo.com/v3/whatsappCampaigns/465908589032810 \
--header 'accept: application/json' \
--header 'api-key: '
This endpoint only has one attribute which is mentioned in the table below:
Attribute | Datatype | Description | Value |
---|---|---|---|
campaignId | String | Id of the campaign | 465908589032810 |
You can get the campaign by using the campaignId
as input.
Responses
Response code | Message | Description |
---|---|---|
200 | Whatsapp campaign overview | Whatsapp campaign details displayed. |
400 | Bad request | Request parameters not in correct format. |
404 | campaignId not found | Campaign id is incorrect or it cannot be accessed from the Whatsapp campaigns dashboard. |
2. Delete a WhatsApp campaign
You can call the delete WhatsApp endpoint at https://api.brevo.com/v3/whatsappCampaigns/{campaignId}
with method DELETE
. The cURL request for this endpoint is as follows:
curl --request DELETE \
--url https://api.brevo.com/v3/whatsappCampaigns/465908589032810 \
--header 'accept: application/json' \
--header 'api-key: '
To delete a Whatsapp campaign, you need your campaign id. Notice this won't delete an ongoing campaign**
Attribute | Datatype | Description | Value |
---|---|---|---|
campaignId | String | Id of the campaign | 465908589032810 |
How can you get your campaignId?
You can retrieve the
campaignId
from the Brevo WhatsApp dashboard and use it in the API endpoint.
Responses
Response code | Message | Description |
---|---|---|
204 | Whatsapp campaign has been deleted | Whatsapp campaign details displayed. |
400 | Bad request | Request parameters not in correct format. |
404 | CampaignId not found | Campaign id is incorrect or it cannot be accessed from the Whatsapp campaigns dashboard. |
3. Update a Whatsapp campaign
To update a Whatsapp campaign, the endpoint https://api.brevo.com/v3/whatsappCampaigns/{campaignId}
is used along with the PUT
method. You can refer to the public API reference for this endpoint along with some additional information at Whatsapp Campaigns > Update a Whatsapp campaign.
You can use the cURL request to send the request to the API. This is just a sample cURL request, you can use this and add your own parameters for the accurate running of the request.
curl --request PUT \
--url https://api.brevo.com/v3/whatsappCampaigns/5678 \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"campaignStatus": "scheduled",
"recipients": {
"excludedListIds": [
8
],
"listIds": [
32
],
"segments": [
23
]
},
"campaignName": "Test WhatsApp",
"rescheduleFor": "2017-06-01T12:30:00+02:00"
}
'
There are two types of parameters for this endpoint; path params and body params. They are defined in the table below.
Path params
The parameters to select the specific campaign that is to be updated.
Attribute | Datatype | Description | Value |
---|---|---|---|
campaignId | int64 | Id of the campaign | 5678 |
Body params
The parameters used for the update of the campaign.
Attribute | Datatype | Description | Value |
---|---|---|---|
campaignName | String | Name of the campaign | Test whatsapp |
campaignStatus | String | Status of the campaign | scheduled |
rescheduleFor | String | Reschedule the sending UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) of campaign. Prefer to pass your timezone in date-time format for accurate result.For example: 2017-06-01T12:30:00+02:00** Use this field to update the scheduledAt of any existing draft or scheduled WhatsApp campaign. | 2017-06-01T12:30:00+02:00 |
recipients | Object | Segment ids and List ids to include/exclude from campaign | Object contains array of int64 excludedListIds, listIds and segments |
The int64s of the recipient object are mentioned below.
Attribute | Datatype | Description | Value |
---|---|---|---|
excludedListIds | Int64 | List ids to exclude from the campaign | 8 |
listIds | Int64 | Mandatory if scheduledAt is not empty. List Ids to send the campaign to | 32 |
segments | Int64 | Mandatory if listIds are not used. Segment ids to send the campaign to. | 23 |
Response
A sample JSON response after the request is returned will show no content with the response code 204 as it does not show any content in case of update or deleting any entry. For the response codes, we have defined them in the table below.
Response code | Message | Description |
---|---|---|
204 | Whatsapp campaign has been updated | Shows that the request has been run successfully and the Whatsapp campaign has been updated. |
400 | Bad request | Failed to run the request due to invalid_parameters or missing_parameters |
4. Return all your created WhatsApp templates
You can use the endpoint https://api.brevo.com/v3/whatsappCampaigns/template-list
with the calling method GET
. You can utilize the cURL request below to call the API.
curl --request GET \
--url 'https://api.brevo.com/v3/whatsappCampaigns/template-list?startDate=2022-05-01T12%253A30%253A00Z&endDate=2022-07-01T12%253A30%253A00Z&limit=50&offset=0&sort=asc' \
--header 'accept: application/json' \
--header 'api-key: '
The attributes for this endpoint are mentioned below:
Attribute | Datatype | Description | Value |
---|---|---|---|
startDate | String | Mandatory if endDate is used. Starting (url-encoded) UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter the templates created. It is ideal to pass your timezone in date-time format for accurate result | 2022-05-01T12:30:00Z |
endDate | String | Mandatory if startDate is used. Ending (url-encoded) UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter the templates created. It is ideal to pass your timezone in date-time format for accurate result | 2022-07-01T12:30:00Z |
limit | Int64 | Number of documents per page | 50 |
offset | Int64 | Index of the first document in the page | 0 |
sort | String | Sort the results in the ascending/descending order of record modification. Default order is descending if sort is not passed | asc |
Response
A sample response for this endpoints request looks something like this:
{
"count": 2,
"templates": [
{
"id": 235,
"name": "campaign_22",
"type": "whatsapp",
"status": "approved",
"language": "en",
"category": "MARKETING",
"errorReason": "NONE",
"createdAt": "2017-05-01T12:30:00Z",
"modifiedAt": "2017-05-01T12:30:00Z"
},
{
"id": 124,
"name": "test-template",
"type": "whatsapp",
"status": "draft",
"language": "",
"category": "MARKETING",
"errorReason": "NONE",
"createdAt": "2017-0",
"modifiedAt": "2017-05-01T12:30:00Z"
}
]
}
Some response codes are mentioned below in the table:
Response code | Message | Description |
---|---|---|
200 | WhatsApp templates information | Displays the WhatsApp templates informations |
400 | Bad request | Error code 400 displays in case of a failure because of invalid or missing parameter etc. |
5. Create and send a WhatsApp campaign
To use this endpoint, you have to call https://api.brevo.com/v3/whatsappCampaigns
with the POST
method. You can send the following cURL request:
curl --request POST \
--url https://api.brevo.com/v3/whatsappCampaigns \
--header 'accept: application/json' \
--header 'api-key: ' \
--header 'content-type: application/json' \
--data '
{
"recipients": {
"excludedIds": [
8
],
"listIds": [
32
],
"segments": [
23
]
},
"name": "Test Campaign",
"templateId": 19,
"scheduledAt": "2017-06-01T12:30:00+02:00"
}
'
This API requires the List and Segment ids as recipients in Body params.You can use the below Contact endpoints to get the required information.
The attributes for this endpoint are:
Attribute | Datatype | Description | Value |
---|---|---|---|
name | String | Name of the WhatsApp campaign creation | Test Campaign |
templateId | Integer | Id of the WhatsApp template in approved state | 19 |
scheduledAt | String | Sending UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). It is preferred to pass your timezone in date-time format for accurate result.For example: 2017-06-01T12:30:00+02:00** | 2017-06-01T12:30:00+02:00 |
recipients | Object | Segment ids and List ids to include/exclude from campaign | excludeIds, listIds and segments |
Since recipients is an object, it consists of sub-attributes which are the following:
Attribute | Datatype | Description | Value |
---|---|---|---|
excludedIds | Int64 array | List ids to exclude from the campaign | 8 |
listIds | Int64 array | Mandatory if scheduledAt is not empty. List Ids to send the campaign to | 32 |
segments | Int64 array | Mandatory if listIds are not used. Segment ids to send the campaign to. | 23 |
Response
When you send a request to the API, it will return a response like this:
{
"id": 5
}
The response will return an id for the campaign you created.
You can find detail about the errors in the API reference for the endpoints in the responses heading. Some response codes for the endpoint are:
Response code | Message | Description |
---|---|---|
201 | Successfully created | The response will return an id for the campaign |
400 | Bad request | This error code is shown in case of a failure like invalid_parameter or duplicate_parameter etc. |
6. Return all your created WhatsApp campaigns
You can use the endpoint https://api.brevo.com/v3/whatsappCampaigns
with the GET
method to retrieve your WhatsApp campaigns. You can use the cURL below to send your request:
curl --request GET \
--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' \
--header 'accept: application/json' \
--header 'api-key: '
The attributes for this endpoint are:
Attribute | Datatype | Description | Value |
---|---|---|---|
startDate | String | Mandatory if endDate is used. Starting (urlencoded) UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter the WhatsApp campaigns created. It is ideal to pass your timezone in date-time format for accurate result | 2017-05-01T12:30:00Z |
endDate | String | Mandatory if startDate is used. Ending (urlencoded) UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter the WhatsApp campaigns created. It is ideal to pass your timezone in date-time format for accurate result | 2017-07-01T12:30:00Z |
limit | Int64 | Number of documents per page | 50 |
offset | Int64 | Index of the first document in the page | 0 |
sort | String | Sort the results in the ascending/descending order of record modification. Default order is descending if sort is not passed | desc |
Response
A sample JSON response to retrieve your campaigns would be:
{
"count": 23,
"campaigns": [
{
"id": 1672035851100690,
"campaignName": "campaign_22",
"campaignStatus": "sent",
"templateId": 637660278078655,
"scheduledAt": "2022-12-27T09:50:00Z",
"errorReason": "",
"invalidatedContacts": 0,
"stats": {
"sent": 3,
"delivered": 3,
"read": 2,
"unsubscribe": 0,
"notSent": 4
},
"readPercentage": 28.57,
"createdAt": "2017-05-01T12:30:00Z",
"modifiedAt": "2017-05-01T12:30:00Z"
}
]
}
You can find detail about the errors in the API reference for the endpoints in the responses heading. Some response codes for the endpoint are:
Response code | Message | Description |
---|---|---|
200 | WhatsApp campaigns information | Returns WhatsApp campaigns information |
400 | Bad request | Error code is returned in case of failure because of missing parameters or out of range parameters etc. |
7. Create a WhatsApp template
You can use the endpoint https://api.brevo.com/v3/whatsappCampaigns/template
along with the API POST
method. To send the request, you can use the following cURL request.
curl --request POST \
--url https://api.brevo.com/v3/whatsappCampaigns/template \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"category": "MARKETING",
"name": "Test template",
"language": "en",
"mediaUrl": "https://attachment.domain.com",
"bodyText": "making it look like readable English",
"headerText": "Test WhatsApp campaign"
}
'
There are a few parameters that are shown above in the cURL request. We will define them below in a table.
Attributes | Datatype | Description | Value |
---|---|---|---|
name | String | Name of the template | Test template |
language | String | Language of the template | en |
category | String | Category of the template | Marketing or Transactional |
mediaUrl | String | Absolute url of the media file (no local file) for the header. Use this field in you want to add media in Template header and headerText is empty. Allowed extensions for media files are: jpeg | png | mp4 | pdf | https://attachment.domain.com |
bodyText | String | Body of the template. Maximum allowed characters are 1024 | "making it look like readable English" |
headerText | String | Text content of the header in the template. Maximum allowed characters are 45. Use this field to add text content in template header and if mediaUrl is empty | Test WhatsApp campaign |
Response
A sample JSON response would generate an id for the WhatsApp template. The response with a 201
reponse code would look something like this.
{
"id": 5
}
The response codes for this endpoint are defined below.
Response code | Message | Description |
---|---|---|
201 | Successfully created | The WhatsApp template has been created successfully |
400 | Bad request | Request fails due to a bad request involving invalid_parameter or duplicate_parameter or due to no validation of account etc. |
You can see the detail of the causes of the bad request in the public API reference for the endpoints here.
8. Send WhatsApp template for approval
You can utilise the endpoint https://api.brevo.com/v3/whatsappCampaigns/template/approval/{templateId}
with the POST
method. To send the request to the API, you can use the cURL request below.
curl --request POST \
--url https://api.brevo.com/v3/whatsappCampaigns/template/approval/5 \
--header 'accept: application/json'
It only has one parameter which is the templateId
and you can mention that in the url to send the request.
Attribute | Datatype | Description | Value |
---|---|---|---|
templateId | int64 | id of the template | 5 |
You get this id in the JSON response when you create a WhatsApp template.
Response
If the response shows no content then the WhatsApp template is sent for approval. The response codes are mentioned below in the table.
Response code | Message | Description |
---|---|---|
200 | WhatsApp template sent for approval | Template is sent for approval |
400 | Bad request | Request fails due to a bad request involving errors like invalid_parameters or unauthorized etc. |
9. Get your WhatsApp API account information
You can use the endpoint https://api.brevo.com/v3/whatsappCampaigns/config
with calling the GET
method. You can use the cURL request to call the endpoint:
curl --request GET \
--url https://api.brevo.com/v3/whatsappCampaigns/config \
--header 'accept: application/json' \
--header 'api-key: '
There is no attribute for this endpoint. It uses your API key to return your WhatsApp account information.
Response
A sample response which displays the WhatsApp account information looks like this:
{
"whatsappBusinessAccountID": 105569359072383,
"sendingLimit": "TIER_1K",
"phoneNumberQuality": "GREEN",
"whatsappBusinessAccountStatus": "APPROVED",
"businessStatus": "verified",
"phoneNumberNameStatus": "APPROVED"
}
The response codes and its descriptions are given below in a table:
Response code | Message | Description |
---|---|---|
200 | Get all the information of your WhatsApp API account | Gets all the detailed information about your WhatsApp account like what plan you are using and whats your sending limit etc. |
400 | Bad request | Request failed due to invalid parameters, not enough credits or account is under validation etc. |
503 | Service unavailable | When a server is not able to handle the request, then this error occurs. |
Updated 6 months ago