openapi: 3.0.1
info:
  title: Modica WhatsApp Business Messaging API
  description: Developer Documentation for using the Modica WhatsApp Business Messaging
    API
  version: 1.3.1
  termsOfService: https://www.modicagroup.com/privacy-policy
  contact:
    name: API Support
    email: support@modicagroup.com
    url: https://www.modicagroup.com
  license:
    name: Modica API - Terms Of Use
    url: https://confluence.modicagroup.com/download/attachments/12386319/Modica%20Group%20-%20Terms%20of%20Use.pdf?version=1&modificationDate=1500544212144&api=v2
servers:
- url: "https://api.modicagroup.com/rest/wab/v1"
security:
- BasicAuth: []
tags:
  - name: messages
    description: WhatsApp Messaging endpoints.
  - name: media
    description: WhatsApp Media endpoints.
  - name: source
    description: WhatsApp Source registration endpoints.
  - name: status
    description: WhatsApp Status endpoints.
paths:
  /media:
    post:
      operationId: PostMedia
      tags:
        - media
      description: Uploading media
      parameters:
        - name: source
          in: query
          description: Source for the media upload
          required: true
          schema:
            type: string
            format: "^[1-9]{1}[0-9]*$"
            maxLength: 30
      requestBody:
        $ref: '#/components/requestBodies/RequestMediaPost'
      responses:
        '200':
          $ref: '#/components/responses/ResponseMediaPost'
        '401':
          $ref: '#/components/responses/Unauthorized'
        4XX:
          $ref: '#/components/responses/4XXError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      operationId: GetMedia
      tags:
        - media
      description: Download message media.
      parameters:
        - name: media_id
          in: query
          description: The ID for the media item.
          required: true
          schema:
            type: string
            pattern:  '^[a-zA-Z0-9]+$'
            maxLength: 255
        - name: source
          in: query
          description: The source - business phone number id.
          required: true
          schema:
            type: string
            pattern:  "^[a-zA-Z0-9]+$"
            maxLength: 255
      responses:
        '200':
          $ref: '#/components/responses/ResponseMediaGet'
        '401':
          $ref: '#/components/responses/Unauthorized'
        4XX:
          $ref: '#/components/responses/4XXError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /messages:
    post:
      operationId: PostMessages
      tags:
        - messages
      description: Send a message to a customer.
      requestBody:
        $ref: '#/components/requestBodies/RequestMessagesPost'
      responses:
        '202':
          $ref: '#/components/responses/ResponseMessagesPost'
        '401':
          $ref: '#/components/responses/Unauthorized'
        4XX:
          $ref: '#/components/responses/4XXError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      callbacks:
        messageCallback:
          '{$statusCallbackUrl}':
            post:
              description: Status/DLR callback. Sent when the status of a MT message is updated
              requestBody:
                $ref: '#/components/requestBodies/RequestMessageStatusCallback'
              responses:
                "200":
                  description: callback successfully processed
                  headers:
                    Content-Security-Policy:
                      $ref: "#/components/headers/Content-Security-Policy"
                    Strict-Transport-Security:
                      $ref: "#/components/headers/Strict-Transport-Security"
                    Cache-Control:
                      $ref: "#/components/headers/Cache-Control"
                    X-Frame-Options:
                      $ref: "#/components/headers/X-Frame-Options"
                    X-Content-Type-Options:
                      $ref: "#/components/headers/X-Content-Type-Options"
                "401":
                  $ref: "#/components/responses/Unauthorized"
                "429":
                  $ref: "#/components/responses/TooManyRequests"
                "500":
                  $ref: "#/components/responses/InternalServerError"
          '{$replyCallbackUrl}':
            post:
              description: Reply/MO callback. Sent when a MO message is received
              requestBody:
                $ref: '#/components/requestBodies/RequestMessageReplyCallback'
              responses:
                "200":
                  description: callback successfully processed
                  headers:
                    Content-Security-Policy:
                      $ref: "#/components/headers/Content-Security-Policy"
                    Strict-Transport-Security:
                      $ref: "#/components/headers/Strict-Transport-Security"
                    Cache-Control:
                      $ref: "#/components/headers/Cache-Control"
                    X-Frame-Options:
                      $ref: "#/components/headers/X-Frame-Options"
                    X-Content-Type-Options:
                      $ref: "#/components/headers/X-Content-Type-Options"
                '401':
                  $ref: '#/components/responses/Unauthorized'
                4XX:
                  $ref: '#/components/responses/4XXError'
                '429':
                  $ref: '#/components/responses/TooManyRequests'
                '500':
                  $ref: '#/components/responses/InternalServerError'
    patch:
      operationId: PatchMessages
      tags:
        - messages
      description: Update an existing message status e.g. mark as read.
      requestBody:
        $ref: '#/components/requestBodies/RequestMessagesPatch'
      responses:
        '200':
          description: OK
          headers:
            Content-Security-Policy:
              $ref: "#/components/headers/Content-Security-Policy"
            Strict-Transport-Security:
              $ref: "#/components/headers/Strict-Transport-Security"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-Frame-Options:
              $ref: "#/components/headers/X-Frame-Options"
            X-Content-Type-Options:
              $ref: "#/components/headers/X-Content-Type-Options"
        '401':
          $ref: '#/components/responses/Unauthorized'
        4XX:
          $ref: '#/components/responses/4XXError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      operationId: GetMessages
      tags:
        - messages
      description: Get a message by the message ID
      parameters:
        - name: id
          in: query
          description: The message ID
          required: true
          schema:
            $ref: '#/components/schemas/Uuid'
      responses:
        "200":
          $ref: "#/components/responses/ResponseMessageGet"
        "400":
          $ref: "#/components/responses/4XXError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/4XXError"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /messages/broadcast:
    post:
      operationId: messages_broadcast_post
      description: Send a broadcast message to customers.
      requestBody:
        $ref: '#/components/requestBodies/RequestMessagesBroadcastPost'
      responses:
        "202":
          $ref: "#/components/responses/ResponseMessagesBroadcastPost"
        "400":
          $ref: "#/components/responses/4XXError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/4XXError"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      callbacks:
        messageCallback:
          '{$statusCallbackUrl}':
            post:
              description: Status/DLR callback. Sent when the status of a MT message is updated
              requestBody:
                $ref: '#/components/requestBodies/RequestMessageStatusCallback'
              responses:
                "200":
                  description: callback successfully processed
                  headers:
                    Content-Security-Policy:
                      $ref: "#/components/headers/Content-Security-Policy"
                    Strict-Transport-Security:
                      $ref: "#/components/headers/Strict-Transport-Security"
                    Cache-Control:
                      $ref: "#/components/headers/Cache-Control"
                    X-Frame-Options:
                      $ref: "#/components/headers/X-Frame-Options"
                    X-Content-Type-Options:
                      $ref: "#/components/headers/X-Content-Type-Options"
                "401":
                  $ref: "#/components/responses/Unauthorized"
                "429":
                  $ref: "#/components/responses/TooManyRequests"
                "500":
                  $ref: "#/components/responses/InternalServerError"
          '{$replyCallbackUrl}':
            post:
              description: Reply/MO callback. Sent when a MO message is received
              requestBody:
                $ref: '#/components/requestBodies/RequestMessageReplyCallback'
              responses:
                "200":
                  description: callback successfully processed
                  headers:
                    Content-Security-Policy:
                      $ref: "#/components/headers/Content-Security-Policy"
                    Strict-Transport-Security:
                      $ref: "#/components/headers/Strict-Transport-Security"
                    Cache-Control:
                      $ref: "#/components/headers/Cache-Control"
                    X-Frame-Options:
                      $ref: "#/components/headers/X-Frame-Options"
                    X-Content-Type-Options:
                      $ref: "#/components/headers/X-Content-Type-Options"
                "401":
                  $ref: "#/components/responses/Unauthorized"
                "429":
                  $ref: "#/components/responses/TooManyRequests"
                "500":
                  $ref: "#/components/responses/InternalServerError"
      tags:
        - messages
  /source:
    post:
      operationId: PostSource
      tags:
        - source
      description: Adding a source
      requestBody:
        $ref: '#/components/requestBodies/RequestSourcePost'
      responses:
        '200':
          $ref: '#/components/responses/ResponseSourcePost'
        '401':
          $ref: '#/components/responses/Unauthorized'
        4XX:
          $ref: '#/components/responses/4XXError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters: {}
  schemas:
    APIErrorResponse:
      description: Top-level structure wrapping error objects.
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/APIError'
          maxItems: 50
    APIError:
      description: An API error structure.
      type: object
      properties:
        field:
          type: string
          maxLength: 100
          pattern: '^[ -_.a-zA-Z0-9]*$'
        code:
          type: string
          maxLength: 100
          pattern: '^[ -_.a-zA-Z0-9]*$'
        description:
          type: string
          maxLength: 100
          pattern: '^[ -_.a-zA-Z0-9!$^*()\\[\\]`+,\''\\\\]*$'
      additionalProperties: false
      required:
        - field
        - code
        - description
    MediaMimeType:
      description: Supported media mime types.
      type: string
      enum:
        - image/png
        - image/jpeg
        - text/plain
        - application/pdf
        - audio/mp3
        - video/mp4
    E164:
      description: The destination number in E.164 format.
      type: string
      maxLength: 16
      pattern: ^\+[1-9]\d{1,14}$
    Uuid:
      description: A string with UUID format.
      type: string
      maxLength: 36
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
    MessageDestination:
      description: Message destination fields.
      type: object
      properties:
        destination:
          $ref: '#/components/schemas/E164'
    BroadcastMessageDestination:
      description: Broadcast message destination fields.
      type: object
      properties:
        destination:
          description: Array of destination numbers in E.164 format.
          type: array
          items:
            $ref: '#/components/schemas/E164'
          maxItems: 1000
      required:
        - destination
    MessageCommon:
      description: Common message fields.
      type: object
      properties:
        source:
          description: The whatsapp business number id.
          type: string
          pattern: ^\[1-9]\d{1,19}$
          maxLength: 50
        scheduled:
          description: Allows scheduling of messages with an upper limit of 60 days.
          type: string
          format: date-time
          maxLength: 30
        type:
          type: string
          enum:
            - text
            - template
            - media
            - raw
        reference:
          type: string
          format: none
          maxLength: 255
      required:
        - type
        - source
    MessageText:
      description: Message of Text type.
      allOf:
        - $ref: '#/components/schemas/MessageDestination'
        - $ref: '#/components/schemas/MessageCommon'
        - type: object
          properties:
            text:
              type: object
              properties:
                body:
                  type: string
                  format: none
                  maxLength: 255
              required:
                - body
          required:
            - text
    MessageMedia:
      description: Message of Media type.
      allOf:
        - $ref: '#/components/schemas/MessageDestination'
        - $ref: '#/components/schemas/MessageCommon'
        - type: object
          properties:
            media:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - audio
                    - document
                    - image
                    - video
                url:
                  type: string
                  format: url
                  maxLength: 255
              required:
                - type
                - url
          required:
            - media
    MessageRaw:
      description: Message of Raw type.
      allOf:
        - $ref: "#/components/schemas/MessageDestination"
        - $ref: "#/components/schemas/MessageCommon"
        - type: object
          properties:
            raw:
              type: object
              properties:
                version:
                  type: string
                  format: none
                  maxLength: 10
                payload:
                  type: string
                  format: none
                  maxLength: 2000
              required:
                - payload
          required:
            - raw
    MessageTemplate:
      description: Message of Template type.
      allOf:
        - $ref: "#/components/schemas/MessageDestination"
        - $ref: "#/components/schemas/MessageCommon"
        - $ref: "#/components/schemas/Template"

    TemplateComponent:
      description: Component for message templates.
      type: object
      properties:
        type: 
          type: string
          enum:
            - body
            - header
            - button
        index:
          type: string
          nullable: true
          pattern: "^[0-9]+$"
          maxLength: 2
        sub_type:
          type: string
          nullable: true
          enum:
          - quick_reply
          - url
          - catalog
        parameters:
          type: array
          nullable: true
          items: 
            $ref: "#/components/schemas/TemplateParameter"
          maxItems: 50
      required:
        - type
    TemplateParameter:
      description: Component for message templates.
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum: [text, image, currency, date_time, button, document, video]
        parameter_name:
          type: string
          nullable: true
          format: none
          maxLength: 50
        text:
          type: string
          nullable: true
          format: none
          maxLength: 32768
        image:
          allOf:
            - $ref: '#/components/schemas/ImageParam'
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyParam'
        date_time:
          allOf:
            - $ref: '#/components/schemas/DateTimeParam'
        button:
          allOf:
            - $ref: '#/components/schemas/ButtonParam'
        document:
          allOf:
            - $ref: '#/components/schemas/DocumentParam'
    ButtonParam:
      description: Button parameter for template messages.
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum: [payload, text]
        text:
          type: string
          format: none
          maxLength: 255
        payload:
          type: string
          format: none
          maxLength: 255
      nullable: true
    CurrencyParam:
      description: Currency parameter for template messages.
      type: object
      required:
        - fallback_value
        - code
        - amount_1000
      properties:
        fallback_value:
          type: string
          format: none
          maxLength: 255
        code:
          type: string
          format: none
          maxLength: 3
        amount_1000:
          type: number
      nullable: true
    DateTimeParam:
      description: DateTime parameter for template messages.
      type: object
      required:
        - fallback_value
      properties:
        fallback_value:
          type: string
          format: none
          maxLength: 255
      nullable: true
    ImageParam:
      description: Image parameter for template messages.
      type: object
      properties:
        id:
          type: string
          format: none
          maxLength: 50
        link:
          type: string
          format: none
          maxLength: 255
      nullable: true
      # Exactly one of id or link must be present
      oneOf:
        - required: [id]
          not:
            required: [link]
        - required: [link]
          not:
            required: [id]
    DocumentParam:
      description: Document parameter for template messages.
      type: object
      properties:
        id:
          type: string
          format: none
          maxLength: 50
        link:
          type: string
          format: none
          maxLength: 255
      nullable: true
      # Exactly one of id or link must be present
      oneOf:
        - required: [id]
          not:
            required: [link]
        - required: [link]
          not:
            required: [id]
    Template:
      description: Template object for template messages.
      type: object
      properties:
        template:
          type: object
          properties:
            name:
              type: string
              format: none
              maxLength: 255
            language:
              type: string
              format: none
              default: en_US
              maxLength: 255
            components:
              type: array
              nullable: true
              items: 
                $ref: "#/components/schemas/TemplateComponent"
              maxItems: 50
            header_params:
              type: array
              nullable: true
              items:
                type: string
                format: none
                maxLength: 255
              maxItems: 15
            body_params:
              type: array
              nullable: true
              items:
                type: string
                format: none
                maxLength: 255
              maxItems: 15
            media:
              type: object
              nullable: true
              properties:
                type:
                  type: string
                  format: none
                  maxLength: 255
                url:
                  type: string
                  format: url
                  maxLength: 255
            buttons:
              type: array
              nullable: true
              items:
                type: object
                properties:
                  index:
                    type: number
                    format: int32
                  type:
                    type: string
                    format: none
                    maxLength: 255
                  payload:
                    type: string
                    format: none
                    maxLength: 255
              maxItems: 3
          required:
            - name
            - language
      required:
        - template
    BroadcastMessageText:
      description: Message of Text type.
      allOf:
        - $ref: '#/components/schemas/BroadcastMessageDestination'
        - $ref: '#/components/schemas/MessageCommon'
        - type: object
          properties:
            text:
              type: object
              properties:
                body:
                  type: string
                  format: none
                  maxLength: 255
              required:
                - body
          required:
            - text
    BroadcastMessageMedia:
      description: Message of Media type.
      allOf:
        - $ref: '#/components/schemas/BroadcastMessageDestination'
        - $ref: '#/components/schemas/MessageCommon'
        - type: object
          properties:
            media:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - audio
                    - document
                    - image
                    - video
                url:
                  type: string
                  format: url
                  maxLength: 255
              required:
                - type
                - url
          required:
            - media
    BroadcastMessageTemplate:
      description: Message of Template type.
      allOf:
        - $ref: '#/components/schemas/BroadcastMessageDestination'
        - $ref: '#/components/schemas/MessageCommon'
        - type: object
          properties:
            template:
              type: object
              properties:
                name:
                  type: string
                  format: none
                  maxLength: 255
                language:
                  type: string
                  format: none
                  default: en_US
                  maxLength: 255
                header_params:
                  type: array
                  items:
                    type: string
                    format: none
                    maxLength: 255
                  maxItems: 3
                body_params:
                  type: array
                  items:
                    type: string
                    format: none
                    maxLength: 255
                  maxItems: 3
                media:
                  type: object
                  properties:
                    type:
                      type: string
                      format: none
                      maxLength: 255
                    url:
                      type: string
                      format: url
                      maxLength: 255
                buttons:
                  type: array
                  items:
                    type: object
                    properties:
                      index:
                        type: number
                        format: int32
                      type:
                        type: string
                        format: none
                        maxLength: 255
                      payload:
                        type: string
                        format: none
                        maxLength: 255
                  maxItems: 3
              required:
                - name
                - language
          required:
            - template
    BroadcastMessageRaw:
      description: Message of Raw type.
      allOf:
        - $ref: "#/components/schemas/BroadcastMessageDestination"
        - $ref: "#/components/schemas/MessageCommon"
        - type: object
          properties:
            raw:
              type: object
              properties:
                version:
                  type: string
                  format: none
                  maxLength: 10
                payload:
                  type: string
                  format: none
                  maxLength: 2000
              required:
                - payload
          required:
            - raw
    StatusCallback:
      description: Status callback structure.
      type: object
      properties:
        id:
          type: string
          format: uuid
          maxLength: 36
        reference:
          type: string
          format: none
          maxLength: 255
        status:
          type: string
          enum:
            - accepted
            - submitted
            - sent
            - received
            - read
            - frozen
            - rejected
            - failed
            - dead
            - expired
    ReplyCallback:
      description: Reply callback structure.
      type: object
      properties:
        id:
          type: string
          format: uuid
          maxLength: 36
        source:
          description: The customer number
          type: string
          format: none
          maxLength: 255
        destination:
          description: The business number
          type: string
          format: none
          maxLength: 255
        content:
          $ref: '#/components/schemas/ReplyCallbackContent'
    ReplyCallbackContent:
      description: Reply callback content encoded as a JSON string.
      type: object
      properties:
        type:
          type: string
          enum:
            - audio
            - button
            - document
            - image
            - sticker
            - text
            - video
        audio:
          type: object
          properties:
            id:
              type: string
              format: none
              maxLength: 255
            mime_type:
              $ref: '#/components/schemas/MediaMimeType'
        button:
          type: object
          properties:
            payload:
              type: string
              format: none
              maxLength: 2048
            text:
              type: string
              format: none
              maxLength: 255
        document:
          type: object
          properties:
            caption:
              type: string
              format: none
              maxLength: 255
            filename:
              type: string
              format: none
              maxLength: 255
            sha256:
              type: string
              format: none
              maxLength: 255
            id:
              type: string
              format: none
              maxLength: 255
            mime_type:
              $ref: '#/components/schemas/MediaMimeType'
        image:
          type: object
          properties:
            caption:
              type: string
              format: none
              maxLength: 255
            sha256:
              type: string
              format: none
              maxLength: 255
            id:
              type: string
              format: none
              maxLength: 255
            mime_type:
              $ref: '#/components/schemas/MediaMimeType'
        sticker:
          type: object
          properties:
            sha256:
              type: string
              format: none
              maxLength: 255
            id:
              type: string
              format: none
              maxLength: 255
            mime_type:
              $ref: '#/components/schemas/MediaMimeType'
        text:
          type: object
          properties:
            body:
              type: string
              format: none
              maxLength: 255
            preview_url:
              type: string
              format: none
              maxLength: 255
        video:
          type: object
          properties:
            caption:
              type: string
              format: none
              maxLength: 255
            filename:
              type: string
              format: none
              maxLength: 255
            sha256:
              type: string
              format: none
              maxLength: 255
            id:
              type: string
              format: none
              maxLength: 255
            mime_type:
              $ref: '#/components/schemas/MediaMimeType'
    MessageDetails:
      description: Message details structure.
      type: object
      properties:
        id:
          type: string
          format: uuid
          maxLength: 36
        direction:
          type: string
          enum:
            - MO
            - MT
        source:
          description: The source for the message
          type: string
          pattern: ^[1-9]\d{1,50}$
          maxLength: 50
        destination:
          $ref: "#/components/schemas/E164"
        reference:
          description: A customer reference for the message
          type: string
          format: none
          maxLength: 255
        content:
          description: Message content encoded as a JSON string.
          type: string
          format: none
          maxLength: 5000
  headers:
    Content-Security-Policy:
      description: Content Security Policy to prevent certain types of attacks.
      schema:
        type: string
        pattern: "^['-_ a-zA-Z0-9]+$"
        maxLength: 255
        example: frame-ancestors 'none'
    Strict-Transport-Security:
      description: HSTS header to enforce HTTPS
      schema:
        type: string
        pattern: "^max-age=[0-9]+(; includeSubDomains)?(; preload)?$"
        maxLength: 255
        example: max-age=31536000; includeSubDomains; preload
    X-Content-Type-Options:
      description: To prevent MIME type sniffing 
      schema:
        type: string
        pattern: "nosniff"
        maxLength: 255
        example: nosniff
    X-Frame-Options:
      description: To indicate whether a browser should be allowed to render a page in a frame, iframe, embed or object
      schema:
        type: string
        pattern: "DENY|SAMEORIGIN"
        maxLength: 255
        example: DENY
    Cache-Control:
      description: To control caching in browsers and shared caches
      schema:
        type: string
        pattern: "^[a-zA-Z0-9\\-,\\s=]+$"
        maxLength: 255
        example: no-store
    RetryAfter:
      schema:
        type: integer
        format: int32
        maximum: 1000
        minimum: 10
      description: The number of seconds to wait before allowing a follow-up request.
  requestBodies:
    RequestMessageStatusCallback:
      description: Status callback payload
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusCallback'
          examples:
            received:
              value:
                id: 2af85f64-3645-1078-b3fc-2c963f66afa6
                reference: ref-abc123
                status: received
            read:
              value:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                reference: ref-def456
                status: read
    RequestMessageReplyCallback:
      description: Reply callback payload
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReplyCallback'
          examples:
            audio:
              value:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa7
                source: '64123456789'
                destination: '102046588645210'
                content:
                  audio:
                    id: abc123456
                    mime_type: audio/mp3
                  type: audio
            button:
              value:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                source: '64123456789'
                destination: '102046588645210'
                content:
                  button:
                    payload: 'YES'
                    text: Click to join
                  type: button
            document:
              value:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                source: '64123456789'
                destination: '102046588645210'
                content:
                  document:
                    id: abc123456
                    filename: cat.doc
                    caption: A document about a cat
                    mime_type: application/pdf
                    sha256: the_sha256
                  type: document
            image:
              value:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                source: '64123456789'
                destination: '102046588645210'
                content:
                  image:
                    id: abc123456
                    caption: An image of a cat
                    mime_type: image/jpeg
                    sha256: the_sha256
                  type: image
            text:
              value:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                source: '64123456789'
                destination: '102046588645210'
                content:
                  text:
                    body: Hello World
                  type: text
            video:
              value:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                source: '64123456789'
                destination: '102046588645210'
                content:
                  type: video
                  video:
                    id: abc123456
                    filename: cat.mp4
                    caption: A video about a cat
                    mime_type: video/mp4
                    sha256: the_sha256
    RequestMessagesPost:
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/MessageText'
              - $ref: '#/components/schemas/MessageTemplate'
              - $ref: '#/components/schemas/MessageMedia'
              - $ref: "#/components/schemas/MessageRaw"
          examples:
            text:
              value:
                destination: "+64123456789"
                type: text
                text:
                  body: Hello
                source: "1234567890"
            template-without-components:
              value:
                destination: "+64123456789"
                type: template
                source: "1234567890"
                template:
                  name: "simple_notification"
                  language: "en_US"
                  components: null
                  header_params:
                    - "John"
                  body_params:
                    - "December 23rd"
                    - "Flight AA1234"
                  media:
                    type: "image"
                    url: "https://example.com/boarding-pass.jpg"
                  buttons:
                    - index: 0
                      type: "quick_reply"
                      payload: "CONFIRM_FLIGHT"
            template-with-components:
              value:
                destination: "+64123456789"
                type: template
                source: "1234567890"
                template:
                  name: "flight_confirmation_v2"
                  language: "en_US"
                  components:
                    - type: header
                      parameters:
                        - type: image
                          image:
                            id: "boarding_pass_123"
                    - type: body
                      parameters:
                        - type: text
                          parameter_name: "passenger_name"
                          text: "John Smith"
                        - type: text
                          parameter_name: "flight_number"
                          text: "AA1234"
                        - type: currency
                          currency:
                            fallback_value: "$299.99 USD"
                            code: "USD"
                            amount_1000: 299990
                        - type: date_time
                          date_time:
                            fallback_value: "December 23rd, 2024 at 3:30 PM"
                    - type: button
                      sub_type: quick_reply
                      index: "0"
                      parameters:
                        - type: button
                          button:
                            type: payload
                            text: "Check-in Now"
                            payload: "CHECKIN_AA1234"
                  body_params: null
                  header_params: null
                  media: null
                  buttons: null
            media-image:
              value:
                destination: "+64123456789"
                type: media
                media:
                  type: image
                  url: "https://static.whatsapp.net/rsrc.php/v3/y7/r/DSxOAUB0raA.png"
                source: "1234567890"
            media-document:
              value:
                destination: "+64123456789"
                type: media
                media:
                  type: document
                  url: "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
                source: "1234567890"
            raw:
              value:
                destination: "+64220296000"
                source: "1234567890"
                type: raw
                raw:
                  version: "v22.0"
                  payload: "{\"messaging_product\": \"whatsapp\", \"to\": \"+64220296000\", \"type\": \"template\", \"template\": { \"name\": \"test_hello_template\", \"language\": { \"code\": \"en\" } } }"
    RequestMessagesPatch:
      content:
        application/json:
          schema:
            type: object
            properties:
              message_id:
                type: array
                maxItems: 20
                items:
                  $ref: "#/components/schemas/Uuid"
            required:
              - message_id
    RequestMessagesBroadcastPost:
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/components/schemas/BroadcastMessageText"
              - $ref: "#/components/schemas/BroadcastMessageTemplate"
              - $ref: "#/components/schemas/BroadcastMessageMedia"
              - $ref: "#/components/schemas/BroadcastMessageRaw"
          examples:
            text:
              value:
                destination: ["+64123456789", "+64223456788"]
                type: text
                text:
                  body: Hello
                source: "1234567890"
            template:
              value:
                destination: ["+64123456789", "+64223456788"]
                type: template
                template:
                  name: hello_world
                  language: en_US
                source: "1234567890"
            template-params:
              value:
                destination: ["+64123456789", "+64223456788"]
                type: template
                template:
                  name: sample_flight_confirmation
                  language: en_US
                  body_params:
                    - Home
                    - Away
                    - December 23rd
                  media:
                    type: document
                    url: "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
                source: "1234567890"
            media-image:
              value:
                destination: ["+64123456789", "+64223456789"]
                type: media
                media:
                  type: image
                  url: "https://static.whatsapp.net/rsrc.php/v3/y7/r/DSxOAUB0raA.png"
                source: "1234567890"
            media-document:
              value:
                destination: ["+64123456789", "+64223456789"]
                type: media
                media:
                  type: document
                  url: "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
                source: "1234567890"
    RequestMediaPost:
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              file:
                type: string
                format: base64
                maxLength: 1000000
          encoding:
            file:
              contentType: 'image/png, image/jpeg, text/plain, application/pdf, audio/mp4, video/mp4'
    RequestSourcePost:
      description: Source registration request payload
      content:
        application/json:
          schema:
            type: object
            properties:
              source:
                description: WhatsApp Business phone number ID
                type: string
                pattern: "^[1-9]{1}[0-9]*$"
                maxLength: 30
              waba_id:
                description: WhatsApp Business Account ID
                type: string
                pattern: "^[1-9]{1}[0-9]*$"
                maxLength: 30
              pin:
                description: Optional 6-digit PIN for 2FA
                type: string
                pattern: "^[0-9]{6}$"
                minLength: 6
                maxLength: 6
            required:
              - source
              - waba_id
          example:
            source: "64123456789"
            waba_id: "1234567890"
            pin: "123456"
  responses:
    Unauthorized:
      description: Unauthorized access error.
      headers:
        Content-Security-Policy:
          $ref: "#/components/headers/Content-Security-Policy"
        Strict-Transport-Security:
          $ref: "#/components/headers/Strict-Transport-Security"
        Cache-Control:
          $ref: "#/components/headers/Cache-Control"
        X-Frame-Options:
          $ref: "#/components/headers/X-Frame-Options"
        X-Content-Type-Options:
          $ref: "#/components/headers/X-Content-Type-Options"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIErrorResponse'
          example:
            message: Whatsapp Cloud API error
            statusCode: 401
            error: unauthorized error message
    TooManyRequests:
      description: Too many requests error.
      headers:
        Content-Security-Policy:
          $ref: "#/components/headers/Content-Security-Policy"
        Strict-Transport-Security:
          $ref: "#/components/headers/Strict-Transport-Security"
        Cache-Control:
          $ref: "#/components/headers/Cache-Control"
        X-Frame-Options:
          $ref: "#/components/headers/X-Frame-Options"
        X-Content-Type-Options:
          $ref: "#/components/headers/X-Content-Type-Options"
        Retry-After:
          $ref: "#/components/headers/RetryAfter"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIErrorResponse'
          example:
            message: Whatsapp Cloud API error
            statusCode: 429
            error: too many requests error message
    InternalServerError:
      description: Internal Server Error.
      headers:
        Content-Security-Policy:
          $ref: "#/components/headers/Content-Security-Policy"
        Strict-Transport-Security:
          $ref: "#/components/headers/Strict-Transport-Security"
        Cache-Control:
          $ref: "#/components/headers/Cache-Control"
        X-Frame-Options:
          $ref: "#/components/headers/X-Frame-Options"
        X-Content-Type-Options:
          $ref: "#/components/headers/X-Content-Type-Options"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIErrorResponse'
          example:
            message: Whatsapp Cloud API error
            statusCode: 500
            error: internal server error message
    4XXError:
      description: API Error Response.
      headers:
        Content-Security-Policy:
          $ref: "#/components/headers/Content-Security-Policy"
        Strict-Transport-Security:
          $ref: "#/components/headers/Strict-Transport-Security"
        Cache-Control:
          $ref: "#/components/headers/Cache-Control"
        X-Frame-Options:
          $ref: "#/components/headers/X-Frame-Options"
        X-Content-Type-Options:
          $ref: "#/components/headers/X-Content-Type-Options"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIErrorResponse'
          examples:
            bad_request:
              value:
                message: Whatsapp Cloud API error
                statusCode: 400
                error: bad request error message
            forbidden:
              value:
                message: Whatsapp Cloud API error
                statusCode: 403
                error: forbidden error message
            not_found:
              value:
                message: Whatsapp Cloud API error
                statusCode: 404
                error: not found error message
            unprocessable_entity:
              value:
                message: Whatsapp Cloud API error
                statusCode: 422
                error: unprocessable entity error message
    ResponseMediaGet:
      description: Get Media response structure.
      headers:
        Content-Security-Policy:
          $ref: "#/components/headers/Content-Security-Policy"
        Strict-Transport-Security:
          $ref: "#/components/headers/Strict-Transport-Security"
        Cache-Control:
          $ref: "#/components/headers/Cache-Control"
        X-Frame-Options:
          $ref: "#/components/headers/X-Frame-Options"
        X-Content-Type-Options:
          $ref: "#/components/headers/X-Content-Type-Options"
      content:
        application/octet-stream:
          schema:
            type: string
            format: binary
            maxLength: 2048
    ResponseMediaPost:
      description: Upload Media response structure.
      headers:
        Content-Security-Policy:
          $ref: "#/components/headers/Content-Security-Policy"
        Strict-Transport-Security:
          $ref: "#/components/headers/Strict-Transport-Security"
        Cache-Control:
          $ref: "#/components/headers/Cache-Control"
        X-Frame-Options:
          $ref: "#/components/headers/X-Frame-Options"
        X-Content-Type-Options:
          $ref: "#/components/headers/X-Content-Type-Options"
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: string
                format: string
                maxLength: 255
          example:
            id: abcd1234xyz
    ResponseMessageGet:
      description: Get Message response structure.
      headers:
        Content-Security-Policy:
          $ref: "#/components/headers/Content-Security-Policy"
        Strict-Transport-Security:
          $ref: "#/components/headers/Strict-Transport-Security"
        Cache-Control:
          $ref: "#/components/headers/Cache-Control"
        X-Frame-Options:
          $ref: "#/components/headers/X-Frame-Options"
        X-Content-Type-Options:
          $ref: "#/components/headers/X-Content-Type-Options"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageDetails'
          examples:
            message:
              value:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                direction: MO
                source: "+10123456789"
                destination: "109836123456789"
                reference: ""
                content: "{\"type\":\"text\",\"text\":{\"body\":\"This is an automated reply from the mock API\"},\"timestamp\":\"1767739600\"}"
    ResponseMessagesPost:
      description: Post Message response structure.
      headers:
        Content-Security-Policy:
          $ref: "#/components/headers/Content-Security-Policy"
        Strict-Transport-Security:
          $ref: "#/components/headers/Strict-Transport-Security"
        Cache-Control:
          $ref: "#/components/headers/Cache-Control"
        X-Frame-Options:
          $ref: "#/components/headers/X-Frame-Options"
        X-Content-Type-Options:
          $ref: "#/components/headers/X-Content-Type-Options"
      content:
        application/json:
          schema:
            type: object
            properties:
              message_id:
                $ref: '#/components/schemas/Uuid'
              status:
                type: string
                enum:
                  - accepted
          example:
            message_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            status: accepted
    ResponseMessagesBroadcastPost:
      description: Broadcast Message response structure.
      headers:
        Content-Security-Policy:
          $ref: "#/components/headers/Content-Security-Policy"
        Strict-Transport-Security:
          $ref: "#/components/headers/Strict-Transport-Security"
        Cache-Control:
          $ref: "#/components/headers/Cache-Control"
        X-Frame-Options:
          $ref: "#/components/headers/X-Frame-Options"
        X-Content-Type-Options:
          $ref: "#/components/headers/X-Content-Type-Options"
      content:
        application/json:
          schema:
            type: array
            maxItems: 1000
            items:
              type: object
              properties:
                destination:
                  $ref: "#/components/schemas/E164"
                id:
                  $ref: "#/components/schemas/Uuid"
                status:
                  type: string
                  enum:
                    - accepted
                message:
                  type: string
                  format: none
                  maxLength: 100
          examples:
            accepted:
              value:
                -
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  status: accepted
                -
                  id: 6fa85f64-5717-4562-b3fc-2c963f66afa6
                  status: accepted

    ResponseSourcePost:
      description: Post source response structure.
      headers:
        Content-Security-Policy:
          $ref: "#/components/headers/Content-Security-Policy"
        Strict-Transport-Security:
          $ref: "#/components/headers/Strict-Transport-Security"
        Cache-Control:
          $ref: "#/components/headers/Cache-Control"
        X-Frame-Options:
          $ref: "#/components/headers/X-Frame-Options"
        X-Content-Type-Options:
          $ref: "#/components/headers/X-Content-Type-Options"
  securitySchemes:
    BasicAuth:
      description: "Basic Authentication eg Basic base64encode(username:password)"
      type: apiKey
      name: Authorization
      in: header