openapi: 3.1.0
info:
  title: Brevo Contacts Agent Status WhatsApp Templates 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 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:
  parameters:
    offsetParam:
      name: offset
      in: query
      description: Number of results to skip for pagination.
      schema:
        type: integer
        format: int64
        default: 0
    limitParam:
      name: limit
      in: query
      description: Maximum number of results to return per request.
      schema:
        type: integer
        format: int64
        default: 50
  schemas:
    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.
    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.
    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.
  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