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

  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:

AttributeDatatypeDescriptionValue
campaignIdStringId of the campaign465908589032810

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

Responses

Response codeMessageDescription
200Whatsapp campaign overviewWhatsapp campaign details displayed.
400Bad requestRequest parameters not in correct format.
404campaignId not foundCampaign 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**

AttributeDatatypeDescriptionValue
campaignIdStringId of the campaign465908589032810

📘

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 codeMessageDescription
204Whatsapp campaign has been deletedWhatsapp campaign details displayed.
400Bad requestRequest parameters not in correct format.
404CampaignId not foundCampaign 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.

AttributeDatatypeDescriptionValue
campaignIdint64Id of the campaign5678

Body params

The parameters used for the update of the campaign.

AttributeDatatypeDescriptionValue
campaignNameStringName of the campaignTest whatsapp
campaignStatusStringStatus of the campaignscheduled
rescheduleForStringReschedule 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
recipientsObjectSegment ids and List ids to include/exclude from campaignObject contains array of int64 excludedListIds, listIds and segments

The int64s of the recipient object are mentioned below.

AttributeDatatypeDescriptionValue
excludedListIdsInt64List ids to exclude from the campaign8
listIdsInt64Mandatory if scheduledAt is not empty. List Ids to send the campaign to32
segmentsInt64Mandatory 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 codeMessageDescription
204Whatsapp campaign has been updatedShows that the request has been run successfully and the Whatsapp campaign has been updated.
400Bad requestFailed 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:

AttributeDatatypeDescriptionValue
startDateStringMandatory 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 result2022-05-01T12:30:00Z
endDateStringMandatory 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 result2022-07-01T12:30:00Z
limitInt64Number of documents per page50
offsetInt64Index of the first document in the page0
sortStringSort the results in the ascending/descending order of record modification. Default order is descending if sort is not passedasc

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 codeMessageDescription
200WhatsApp templates informationDisplays the WhatsApp templates informations
400Bad requestError 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.

Get all the lists

Get all the segments


The attributes for this endpoint are:

AttributeDatatypeDescriptionValue
nameStringName of the WhatsApp campaign creationTest Campaign
templateIdIntegerId of the WhatsApp template in approved state19
scheduledAtStringSending 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
recipientsObjectSegment ids and List ids to include/exclude from campaignexcludeIds, listIds and segments

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

AttributeDatatypeDescriptionValue
excludedIdsInt64 arrayList ids to exclude from the campaign8
listIdsInt64 arrayMandatory if scheduledAt is not empty. List Ids to send the campaign to32
segmentsInt64 arrayMandatory 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 codeMessageDescription
201Successfully createdThe response will return an id for the campaign
400Bad requestThis 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:

AttributeDatatypeDescriptionValue
startDateStringMandatory 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 result2017-05-01T12:30:00Z
endDateStringMandatory 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 result2017-07-01T12:30:00Z
limitInt64Number of documents per page50
offsetInt64Index of the first document in the page0
sortStringSort the results in the ascending/descending order of record modification. Default order is descending if sort is not passeddesc

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 codeMessageDescription
200WhatsApp campaigns informationReturns WhatsApp campaigns information
400Bad requestError 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.

AttributesDatatypeDescriptionValue
nameStringName of the templateTest template
languageStringLanguage of the templateen
categoryStringCategory of the templateMarketing or Transactional
mediaUrlStringAbsolute 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
bodyTextStringBody of the template. Maximum allowed characters are 1024"making it look like readable English"
headerTextStringText 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 emptyTest 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 codeMessageDescription
201Successfully createdThe WhatsApp template has been created successfully
400Bad requestRequest 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.

AttributeDatatypeDescriptionValue
templateIdint64id of the template5

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 codeMessageDescription
200WhatsApp template sent for approvalTemplate is sent for approval
400Bad requestRequest 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 codeMessageDescription
200Get all the information of your WhatsApp API accountGets all the detailed information about your WhatsApp account like what plan you are using and whats your sending limit etc.
400Bad requestRequest failed due to invalid parameters, not enough credits or account is under validation etc.
503Service unavailableWhen a server is not able to handle the request, then this error occurs.