openapi: 3.1.0
info:
  title: MessageBird Integrations API
  description: >-
    The MessageBird Integrations API allows developers to create, fetch,
    and delete message templates for supported platforms. It currently
    supports template management for the WhatsApp platform, enabling
    developers to programmatically manage the templates required for
    sending WhatsApp Business notifications and messages. The API handles
    template submission, approval status tracking, and lifecycle management.
  version: '1.0'
  contact:
    name: MessageBird Support
    url: https://support.messagebird.com
  termsOfService: https://www.messagebird.com/en/terms
externalDocs:
  description: Integrations API Documentation
  url: https://developers.messagebird.com/api/integrations/
servers:
  - url: https://integrations.messagebird.com
    description: Production Server
tags:
  - name: Templates
    description: >-
      Operations for managing message templates on supported platforms.
security:
  - accessKey: []
paths:
  /v2/platforms/whatsapp/templates:
    get:
      operationId: listWhatsAppTemplates
      summary: List WhatsApp templates
      description: >-
        Retrieves a list of all WhatsApp message templates associated with
        the account.
      tags:
        - Templates
      parameters:
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: A list of templates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateList'
        '401':
          description: Unauthorized
    post:
      operationId: createWhatsAppTemplate
      summary: Create a WhatsApp template
      description: >-
        Creates a new WhatsApp message template and submits it for
        approval. Templates must be approved by WhatsApp before they
        can be used to send messages.
      tags:
        - Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateCreate'
      responses:
        '201':
          description: Template created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable entity
  /v2/platforms/whatsapp/templates/{templateName}:
    get:
      operationId: viewWhatsAppTemplate
      summary: View a WhatsApp template
      description: >-
        Retrieves the details of a specific WhatsApp template by its name.
      tags:
        - Templates
      parameters:
        - $ref: '#/components/parameters/templateNameParam'
      responses:
        '200':
          description: Template details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '401':
          description: Unauthorized
        '404':
          description: Template not found
    delete:
      operationId: deleteWhatsAppTemplate
      summary: Delete a WhatsApp template
      description: >-
        Deletes a WhatsApp message template by its name. This removes
        all language versions of the template.
      tags:
        - Templates
      parameters:
        - $ref: '#/components/parameters/templateNameParam'
      responses:
        '204':
          description: Template deleted
        '401':
          description: Unauthorized
        '404':
          description: Template not found
components:
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Access key authentication in the form of 'AccessKey {accessKey}'.
  parameters:
    templateNameParam:
      name: templateName
      in: path
      required: true
      description: >-
        The name of the WhatsApp template.
      schema:
        type: string
    offsetParam:
      name: offset
      in: query
      required: false
      description: >-
        The number of items to skip.
      schema:
        type: integer
        default: 0
    limitParam:
      name: limit
      in: query
      required: false
      description: >-
        The maximum number of items to return.
      schema:
        type: integer
        default: 20
  schemas:
    TemplateCreate:
      type: object
      required:
        - name
        - language
        - category
        - components
      properties:
        name:
          type: string
          description: >-
            The name of the template. Must be unique within the account.
          pattern: '^[a-z0-9_]+$'
          maxLength: 512
        language:
          type: string
          description: >-
            The language code for the template.
        category:
          type: string
          description: >-
            The category of the template.
          enum:
            - ACCOUNT_UPDATE
            - PAYMENT_UPDATE
            - PERSONAL_FINANCE_UPDATE
            - SHIPPING_UPDATE
            - RESERVATION_UPDATE
            - ISSUE_RESOLUTION
            - APPOINTMENT_UPDATE
            - TRANSPORTATION_UPDATE
            - TICKET_UPDATE
            - ALERT_UPDATE
            - AUTO_REPLY
        components:
          type: array
          description: >-
            The components that make up the template content.
          items:
            $ref: '#/components/schemas/TemplateComponent'
    TemplateComponent:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: >-
            The type of template component.
          enum:
            - HEADER
            - BODY
            - FOOTER
            - BUTTONS
        format:
          type: string
          description: >-
            The format of the component, applicable to HEADER type.
          enum:
            - TEXT
            - IMAGE
            - DOCUMENT
            - VIDEO
        text:
          type: string
          description: >-
            The text content of the component. Use {{n}} for variables.
        buttons:
          type: array
          description: >-
            Button definitions, applicable to BUTTONS type.
          items:
            type: object
            properties:
              type:
                type: string
                description: >-
                  The type of button.
                enum:
                  - PHONE_NUMBER
                  - URL
                  - QUICK_REPLY
              text:
                type: string
                description: >-
                  The button label text.
              phone_number:
                type: string
                description: >-
                  The phone number for PHONE_NUMBER buttons.
              url:
                type: string
                format: uri
                description: >-
                  The URL for URL buttons.
    Template:
      type: object
      properties:
        name:
          type: string
          description: >-
            The name of the template.
        language:
          type: string
          description: >-
            The language code.
        category:
          type: string
          description: >-
            The template category.
        components:
          type: array
          description: >-
            The template components.
          items:
            $ref: '#/components/schemas/TemplateComponent'
        status:
          type: string
          description: >-
            The approval status of the template.
          enum:
            - NEW
            - PENDING
            - APPROVED
            - REJECTED
        rejectedReason:
          type: string
          description: >-
            The reason for rejection, if applicable.
        createdAt:
          type: string
          format: date-time
          description: >-
            The date and time when the template was created.
        updatedAt:
          type: string
          format: date-time
          description: >-
            The date and time when the template was last updated.
    TemplateList:
      type: object
      properties:
        offset:
          type: integer
          description: >-
            The offset of the result set.
        limit:
          type: integer
          description: >-
            The limit applied.
        count:
          type: integer
          description: >-
            The number of items returned.
        totalCount:
          type: integer
          description: >-
            The total number of templates.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Template'