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.