The Brevo WhatsApp API enables developers to send transactional WhatsApp messages such as order confirmations, status updates, and password reset links through the WhatsApp Business platform. It provides endpoints for sending template-based messages, managing WhatsApp campaigns, and tracking message delivery and read status. The API leverages WhatsApp's high engagement rates to deliver important notifications directly to users on their preferred messaging platform.
openapi: 3.1.0
info:
title: Brevo WhatsApp API
description: >-
The Brevo WhatsApp API enables developers to send transactional WhatsApp
messages such as order confirmations, status updates, and password reset
links through the WhatsApp Business platform. It provides endpoints for
sending template-based messages, managing WhatsApp campaigns, and tracking
message delivery and read status. The API leverages WhatsApp's high
engagement rates to deliver important notifications directly to users on
their preferred messaging platform.
version: '3.0'
contact:
name: Brevo Support
url: https://help.brevo.com
termsOfService: https://www.brevo.com/legal/termsofuse/
externalDocs:
description: Brevo WhatsApp Messages Documentation
url: https://developers.brevo.com/docs/whatsapp-messages
servers:
- url: https://api.brevo.com/v3
description: Brevo Production API Server
tags:
- name: WhatsApp Campaigns
description: >-
Create, manage, and send WhatsApp marketing campaigns.
- name: WhatsApp Messages
description: >-
Send transactional WhatsApp messages to recipients using approved
templates or plain text.
- name: WhatsApp Templates
description: >-
Create and manage WhatsApp message templates that require Meta
approval before use.
security:
- apiKeyAuth: []
paths:
/whatsapp/sendMessage:
post:
operationId: sendWhatsAppMessage
summary: Send a WhatsApp message
description: >-
Sends a transactional WhatsApp message to a recipient using an
approved template or plain text content. Messages are delivered
through the WhatsApp Business platform and support dynamic
parameter substitution in templates.
tags:
- WhatsApp Messages
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendWhatsAppMessage'
responses:
'201':
description: WhatsApp message sent successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SendWhatsAppResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/whatsappCampaigns:
get:
operationId: listWhatsAppCampaigns
summary: Return all WhatsApp campaigns
description: >-
Retrieves a paginated list of all WhatsApp campaigns created in
the account. Supports filtering by status and date range.
tags:
- WhatsApp Campaigns
parameters:
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- name: startDate
in: query
description: >-
Filter campaigns created on or after this date.
schema:
type: string
format: date
- name: endDate
in: query
description: >-
Filter campaigns created on or before this date.
schema:
type: string
format: date
- name: sort
in: query
description: >-
Sort direction for the results.
schema:
type: string
enum:
- asc
- desc
responses:
'200':
description: WhatsApp campaigns retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsAppCampaignList'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
operationId: createWhatsAppCampaign
summary: Create and send a WhatsApp campaign
description: >-
Creates a new WhatsApp marketing campaign with the specified
template, recipients, and scheduling options.
tags:
- WhatsApp Campaigns
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWhatsAppCampaign'
responses:
'201':
description: WhatsApp campaign created successfully
content:
application/json:
schema:
type: object
properties:
id:
type: integer
format: int64
description: >-
Unique identifier of the newly created campaign.
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/whatsappCampaigns/{campaignId}:
get:
operationId: getWhatsAppCampaign
summary: Get a WhatsApp campaign
description: >-
Retrieves the details of a specific WhatsApp campaign including
template, recipients, and delivery statistics.
tags:
- WhatsApp Campaigns
parameters:
- $ref: '#/components/parameters/campaignIdParam'
responses:
'200':
description: WhatsApp campaign retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsAppCampaign'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
operationId: updateWhatsAppCampaign
summary: Update a WhatsApp campaign
description: >-
Updates an existing WhatsApp campaign with new template, recipients,
or scheduling options. Only draft campaigns can be updated.
tags:
- WhatsApp Campaigns
parameters:
- $ref: '#/components/parameters/campaignIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWhatsAppCampaign'
responses:
'204':
description: Campaign updated successfully
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
operationId: deleteWhatsAppCampaign
summary: Delete a WhatsApp campaign
description: >-
Permanently deletes a WhatsApp campaign by its unique identifier.
tags:
- WhatsApp Campaigns
parameters:
- $ref: '#/components/parameters/campaignIdParam'
responses:
'204':
description: Campaign deleted successfully
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/whatsappCampaigns/template:
post:
operationId: createWhatsAppTemplate
summary: Create a WhatsApp template
description: >-
Creates a new WhatsApp message template. Templates must be
approved by Meta before they can be used for sending messages.
tags:
- WhatsApp Templates
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWhatsAppTemplate'
responses:
'201':
description: Template created successfully
content:
application/json:
schema:
type: object
properties:
id:
type: integer
format: int64
description: >-
Unique identifier of the newly created template.
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/whatsappCampaigns/template-list:
get:
operationId: listWhatsAppTemplates
summary: Return all WhatsApp templates
description: >-
Retrieves all WhatsApp message templates created in the account
including their approval status and content.
tags:
- WhatsApp Templates
parameters:
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
responses:
'200':
description: Templates retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsAppTemplateList'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/whatsappCampaigns/template/approval/{templateId}:
post:
operationId: sendWhatsAppTemplateForApproval
summary: Send a WhatsApp template for approval
description: >-
Submits a WhatsApp message template to Meta for review and
approval. Templates must be approved before they can be used
for sending messages to recipients.
tags:
- WhatsApp Templates
parameters:
- name: templateId
in: path
required: true
description: >-
Unique identifier of the template to submit for approval.
schema:
type: integer
format: int64
responses:
'204':
description: Template submitted for approval successfully
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Template not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: api-key
description: >-
Brevo API key passed in the api-key request header for
authentication.
parameters:
limitParam:
name: limit
in: query
description: >-
Maximum number of results to return per request.
schema:
type: integer
format: int64
default: 50
offsetParam:
name: offset
in: query
description: >-
Number of results to skip for pagination.
schema:
type: integer
format: int64
default: 0
campaignIdParam:
name: campaignId
in: path
required: true
description: >-
Unique identifier of the WhatsApp campaign.
schema:
type: integer
format: int64
schemas:
SendWhatsAppMessage:
type: object
required:
- contactNumbers
- templateId
properties:
contactNumbers:
type: array
description: >-
List of recipient phone numbers in international format.
items:
type: string
templateId:
type: integer
format: int64
description: >-
ID of the approved WhatsApp template to use.
params:
type: array
description: >-
Dynamic parameter values to substitute into the template.
items:
type: string
SendWhatsAppResponse:
type: object
properties:
messageId:
type: string
description: >-
Unique identifier assigned to the sent WhatsApp message.
WhatsAppCampaignList:
type: object
properties:
count:
type: integer
format: int64
description: >-
Total number of WhatsApp campaigns.
campaigns:
type: array
description: >-
List of WhatsApp campaign summaries.
items:
$ref: '#/components/schemas/WhatsAppCampaign'
WhatsAppCampaign:
type: object
properties:
id:
type: integer
format: int64
description: >-
Unique identifier of the campaign.
campaignName:
type: string
description: >-
Name of the campaign.
campaignStatus:
type: string
description: >-
Current status of the campaign.
enum:
- draft
- scheduled
- sent
- archive
templateId:
type: integer
format: int64
description: >-
ID of the WhatsApp template used for the campaign.
scheduledAt:
type: string
format: date-time
description: >-
UTC date-time when the campaign is scheduled to send.
recipients:
type: object
description: >-
Target audience for the campaign.
properties:
lists:
type: array
description: >-
IDs of contact lists to target.
items:
type: integer
format: int64
segments:
type: array
description: >-
IDs of segments to target.
items:
type: integer
format: int64
statistics:
type: object
description: >-
Campaign delivery statistics.
properties:
sent:
type: integer
format: int64
description: >-
Number of messages sent.
delivered:
type: integer
format: int64
description: >-
Number of messages delivered.
read:
type: integer
format: int64
description: >-
Number of messages read.
createdAt:
type: string
format: date-time
description: >-
UTC date-time when the campaign was created.
modifiedAt:
type: string
format: date-time
description: >-
UTC date-time when the campaign was last modified.
CreateWhatsAppCampaign:
type: object
required:
- name
- templateId
- recipients
properties:
name:
type: string
description: >-
Name for the campaign.
templateId:
type: integer
format: int64
description: >-
ID of the approved WhatsApp template to use.
scheduledAt:
type: string
format: date-time
description: >-
UTC date-time to schedule the campaign send.
recipients:
type: object
description: >-
Target audience for the campaign.
required:
- listIds
properties:
listIds:
type: array
description: >-
IDs of contact lists to target.
items:
type: integer
format: int64
segments:
type: array
description: >-
IDs of segments to target.
items:
type: integer
format: int64
UpdateWhatsAppCampaign:
type: object
properties:
campaignName:
type: string
description: >-
Updated name for the campaign.
templateId:
type: integer
format: int64
description: >-
Updated template ID for the campaign.
scheduledAt:
type: string
format: date-time
description: >-
Updated scheduled send date-time.
recipients:
type: object
description: >-
Updated target audience.
properties:
listIds:
type: array
description: >-
IDs of contact lists to target.
items:
type: integer
format: int64
segments:
type: array
description: >-
IDs of segments to target.
items:
type: integer
format: int64
CreateWhatsAppTemplate:
type: object
required:
- name
- language
- category
- bodyText
properties:
name:
type: string
description: >-
Name for the template.
language:
type: string
description: >-
Language code for the template such as en for English.
category:
type: string
description: >-
Template category required by Meta for approval.
enum:
- MARKETING
- UTILITY
headerText:
type: string
description: >-
Header text content for the template.
bodyText:
type: string
description: >-
Body text content for the template with parameter placeholders.
footerText:
type: string
description: >-
Footer text content for the template.
WhatsAppTemplateList:
type: object
properties:
count:
type: integer
format: int64
description: >-
Total number of WhatsApp templates.
templates:
type: array
description: >-
List of WhatsApp template summaries.
items:
type: object
properties:
id:
type: integer
format: int64
description: >-
Unique identifier of the template.
name:
type: string
description: >-
Name of the template.
status:
type: string
description: >-
Approval status of the template.
enum:
- approved
- pending
- rejected
language:
type: string
description: >-
Language code of the template.
category:
type: string
description: >-
Category of the template.
createdAt:
type: string
format: date-time
description: >-
UTC date-time when the template was created.
modifiedAt:
type: string
format: date-time
description: >-
UTC date-time when the template was last modified.
ErrorResponse:
type: object
properties:
code:
type: string
description: >-
Error code identifying the type of error.
message:
type: string
description: >-
Human-readable description of the error.