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

1. You need to log in to your Brevo Account.
2. At the top navigation bar, you can find all the applications enabled on your account.
3. Choose Add more apps and you will find Apps and Integration.
4. Under Apps, scroll down and enable the WhatsApp campaigns feature.
5. 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:

You can get the campaign by using the campaignId as input.

Responses

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**

📘

How can you get your campaignId?

You can retrieve the campaignId from the Brevo WhatsApp dashboard and use it in the API endpoint.

Responses

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.

Body params

The parameters used for the update of the campaign.

The int64s of the recipient object are mentioned below.

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.

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:

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:

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.

Get all the lists

Get all the segments

The attributes for this endpoint are:

Since recipients is an object, it consists of sub-attributes which are the following:

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:

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:

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:

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.

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.

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.

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.

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: