brevo WhatsApp Templates API

openapi: 3.2.0
info:
  title: Brevo WhatsApp WhatsApp Templates 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/
servers:
- url: https://api.brevo.com/v3
  description: Brevo Production API Server
security:
- apiKeyAuth: []
tags:
- name: WhatsApp Templates
  description: Create and manage WhatsApp message templates that require Meta approval before use.
paths:
  /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:
  schemas:
    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.
    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.
  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
  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 WhatsApp Messages Documentation
  url: https://developers.brevo.com/docs/whatsapp-messages