brevo WhatsApp Campaigns API

openapi: 3.1.0
info:
  title: Brevo Contacts Agent Status WhatsApp Campaigns API
  description: The Brevo Contacts API provides programmatic access to contact management features including creating, updating, and deleting contacts. Developers can organize contacts into lists, apply attributes and tags, import contacts in bulk, and build audience segments for targeted campaigns. The API also supports managing folders, contact attributes, and custom fields to structure contact data according to business needs.
  version: '3.0'
  contact:
    name: Brevo Support
    url: https://help.brevo.com
  termsOfService: https://www.brevo.com/legal/termsofuse/
servers:
- url: https://api.brevo.com/v3
  description: Brevo Production API Server
security:
- apiKeyAuth: []
tags:
- name: WhatsApp Campaigns
  description: Create, manage, and send WhatsApp marketing campaigns.
paths:
  /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'
components:
  schemas:
    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
    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
    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.
    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'
  parameters:
    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
    limitParam:
      name: limit
      in: query
      description: Maximum number of results to return per request.
      schema:
        type: integer
        format: int64
        default: 50
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: Brevo API key passed in the api-key request header for authentication.
externalDocs:
  description: Brevo Contacts Documentation
  url: https://developers.brevo.com/docs/how-it-works