8x8 Management API

openapi: 3.2.0
info:
  title: 8x8 Management Management API
  contact:
    name: 8x8 Inc
    url: https://cpaas.8x8.com
    email: cpaas-support@8x8.com
  termsOfService: https://cpaas.8x8.com/sg/terms-and-conditions/
  version: '1.0'
  description: 'Operations tagged Management API across 2 of this provider''s published API definitions: 8x8-connect-business-messaging-api.json, 8x8-connect-video-interaction-api.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://chatapps.8x8.com
  description: Asia-Pacific region
- url: https://chatapps.us.8x8.com
  description: North America region
- url: https://chatapps.8x8.uk
  description: Europe region
- url: https://chatapps.8x8.id
  description: Indonesia region
- url: https://video-agent.8x8.com/
tags:
- name: Management API
paths:
  /api/v1/accounts/{accountId}/channels/{channelId}/templates:
    parameters:
    - $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1webhooks/parameters/0'
    - in: path
      name: channelId
      required: true
      description: Channel identifier
      schema:
        type: string
    servers:
    - url: https://chatapps.8x8.com
      description: Asia-Pacific region
    - url: https://chatapps.us.8x8.com
      description: North America region
    - url: https://chatapps.8x8.uk
      description: Europe region
    - url: https://chatapps.8x8.id
      description: Indonesia region
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                title: Register template response
                properties:
                  templates:
                    type: array
                    items:
                      type: object
                      title: Registered template
                      properties:
                        channelId:
                          type: string
                          format: uuid
                          example: ec36a867-3dd4-e911-814a-02d85f55fce8
                          description: Channel ID
                        channelName:
                          type: string
                          maxLength: 36
                          description: Channel User-friendly name
                          example: My WhatsApp Instance
                        templateName:
                          type: string
                          maxLength: 200
                          example: test1
                          description: Template name
                        language:
                          type: string
                          maxLength: 5
                          example: en_US
                          description: Template languate code
                        languageName:
                          type: string
                          example: English (US)
                          description: User-friendly language name
                        components:
                          type: array
                          description: Template components
                          items:
                            type: object
                            title: Registered template component
                            properties:
                              type:
                                type: string
                                default: BODY
                                description: Component type
                                enum:
                                - HEADER
                                - BODY
                                - FOOTER
                                - BUTTONS
                              format:
                                type: string
                                enum:
                                - Text
                                - Image
                                - Video
                                - Document
                                - Location
                                example: Image
                                description: 'Component type.

                                  Required for HEADER component type.'
                              text:
                                type: string
                                example: You can pickup your delivery at {{1}}
                                description: Component text. Required for BODY and FOOTER types
                              buttons:
                                type: array
                                items:
                                  $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1channels~1%7BchannelId%7D~1templates/post/requestBody/content/application~1json/schema/properties/components/items/properties/buttons/items'
                              example:
                                title: registered-template-component-examples
                                x-stoplight:
                                  id: x007v2ojjyybi
                                type: object
                                description: Example data provided for the template
                                properties:
                                  headerText:
                                    type: array
                                    description: Header text examples
                                    items:
                                      type: string
                                  bodyText:
                                    type: array
                                    description: Body text examples
                                    items:
                                      type: string
                                  headerHandle:
                                    type: array
                                    description: Header images, docs or videos examples
                                    items:
                                      type: string
                            required:
                            - type
                        category:
                          type: string
                          example: UTILITY
                          description: template category enumeration
                        categoryName:
                          type: string
                          example: Utility
                          description: User-friendly category name
                        status:
                          type: string
                          example: APPROVED
                          description: Template status enumeration
                        statusName:
                          type: string
                          example: Approved
                          description: User-friendly status name
                        createdAt:
                          type: string
                          format: date-time
                          example: '2019-08-26T04:50:47.38Z'
                          description: Template creation timestamp
                        updatedAt:
                          type: string
                          format: date-time
                          example: '2019-09-26T04:50:47.38Z'
                          description: Template last update timestamp
              examples:
                response:
                  value:
                    templates:
                    - channelId: ec36a867-3dd4-e911-814a-02d85f55fce8
                      channelName: My WhatsApp instance
                      templateName: ticket_created
                      language: en
                      languageName: English
                      components:
                      - type: BODY
                        text: Hi, your booking have been confirmed. Here is your new booking information {{1}}
                      category: UTILITY
                      categoryName: Utility
                      status: APPROVED
                      statusName: Approved
                      createdAt: '2019-11-19T07:51:38.09Z'
                      updatedAt: '2019-11-28T02:16:42.82Z'
                    - channelId: ec36a867-3dd4-e911-814a-02d85f55fce8
                      channelName: My WhatsApp instance
                      templateName: ticket_closed
                      language: en
                      languageName: English
                      components:
                      - type: HEADER
                        format: Image
                      - type: BODY
                        text: Your ticket {{1}} was closed.
                      - type: FOOTER
                        text: Support Team
                      category: UTILITY
                      categoryName: Utility
                      status: APPROVED
                      statusName: Approved
                      createdAt: '2019-11-14T07:17:57.16Z'
                      updatedAt: '2019-11-28T02:16:42.82Z'
        '401':
          $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1webhooks/get/responses/401'
        '500':
          $ref: '#/paths/~1files~1%7Bfilename%7D/get/responses/500'
      summary: Get WhatsApp templates
      operationId: get-whatsapp-templates
      tags:
      - Management API
      description: "This endpoint is used to get your registered WhatsApp message template and their approval status. \n\nWhatsApp Message Templates are message formats for common reusable messages a business may want to send. \nBusinesses must use Message Templates for sending notifications to customers.\nAny message sent outside the 24h customer service window, needs to be a template message, to be delivered. \nAdvertising, marketing, or promotional messages are not permitted."
      security:
      - apiKey: []
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1webhooks/get/responses/400'
        '401':
          $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1webhooks/get/responses/401'
        '409':
          description: Template name cannot be reused within 30 days of deletion
          content:
            application/json:
              schema:
                $ref: '#/paths/~1api~1v1~1subaccounts~1%7BsubAccountId%7D~1messages~1%7Bumid%7D/delete/responses/400/content/application~1json/schema'
              example:
                code: 3060
                message: New Indonesian content can't be added while the existing Indonesian content is being deleted. Try again in 4 weeks or consider creating a new message template.
                errorId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                timestamp: '2024-02-16T10:30:00.00Z'
        '500':
          $ref: '#/paths/~1files~1%7Bfilename%7D/get/responses/500'
      summary: Add WhatsApp template
      operationId: add-whatsapp-template
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                language:
                  type: string
                  example: en_US
                  description: Template language code
                name:
                  type: string
                  example: ticket_update_en_US
                  description: Template name
                category:
                  type: string
                  description: 'Template category.


                    Templates containing a `VOICE_CALL` button are only allowed in `MARKETING` or `UTILITY` categories.'
                  example: UTILITY
                components:
                  type: array
                  description: Registered template components
                  items:
                    type: object
                    title: Registered template component
                    properties:
                      type:
                        type: string
                        default: BODY
                        description: Component type
                        enum:
                        - HEADER
                        - BODY
                        - FOOTER
                        - BUTTONS
                        - CAROUSEL
                        - CALL_PERMISSION_REQUEST
                        - REQUEST_CONTACT_INFO
                      format:
                        type: string
                        enum:
                        - Text
                        - Image
                        - Gif
                        - Video
                        - Document
                        - Location
                        example: Image
                        description: 'Component type.

                          Required for HEADER component type.<br/>Note: Gifs are currently only available for Marketing Messages API for WhatsApp.'
                      text:
                        type: string
                        example: You can pickup your delivery at {{1}}
                        description: Component text. Required for BODY and FOOTER types
                      buttons:
                        type: array
                        items:
                          type: object
                          description: The parameters related to the button component
                          properties:
                            type:
                              type: string
                              enum:
                              - PHONE_NUMBER
                              - URL
                              - QUICK_REPLY
                              - OTP
                              - COPY_CODE
                              - FLOW
                              - VOICE_CALL
                              - REQUEST_CONTACT_INFO
                              description: Button type
                            text:
                              type: string
                              description: The text to be displayed on the button (except `VOICE_CALL`, where it is optional).
                              minLength: 1
                              maxLength: 20
                            phoneNumber:
                              type: string
                              description: 'Required for type "PHONE_NUMBER".


                                The phone number that will be called on clicking the button.'
                            country:
                              type: string
                              description: Optional country code of phone number (ISO 3166-1 alpha-2). Required if the phone number in the national format.
                              minLength: 2
                              maxLength: 2
                              example: US
                            url:
                              type: string
                              description: 'Required for type "URL".


                                The URL that will be visited on clicking the button

                                Variables can be used to create dynamic links.'
                              format: uri
                              example: https://website.com/{{1}}
                            example:
                              type: array
                              description: 'To help WhatsApp moderators during the review and approval process, you can include example data. This can help WhatsApp understand what kind of message you plan to send and showcase the customer experience.


                                For example, you could include an image that could represent a customer''s profile picture to personalize the experience.


                                Make sure these are examples and do not include any confidential or personal information.'
                              items:
                                type: string
                            flowId:
                              type: string
                              description: 'Required for type "FLOW".


                                The ID of the WhatsApp Flow to launch when the button is clicked.'
                              example: '859504979861628'
                            flowAction:
                              type: string
                              description: 'Optional for type "FLOW".


                                The action to perform when launching the flow. Defaults to "navigate" if not provided.'
                              enum:
                              - navigate
                              - data_exchange
                              default: navigate
                              example: navigate
                            navigateScreen:
                              type: string
                              description: 'Optional for type "FLOW".


                                The screen ID to navigate to when launching the flow. Used when flowAction is "navigate". Defaults to "FIRST_ENTRY_SCREEN" if not provided.'
                              default: FIRST_ENTRY_SCREEN
                              example: RECOMMEND
                            ttlMinutes:
                              type: integer
                              description: 'Optional property for type "VOICE_CALL" only.


                                The time-to-live in minutes for the voice call button. If provided, must be between 1440 mins (1 day) and 43200 mins (30 days), inclusive.'
                              minimum: 1440
                              maximum: 43200
                              example: 1440
                          required:
                          - type
                          - text
                      examples:
                        type: array
                        description: 'To help WhatsApp moderators during the review and approval process, you can include example data. This can help WhatsApp understand what kind of message you plan to send and showcase the customer experience.


                          For example, you could include an image that could represent a customer''s profile picture to personalize the experience.


                          Make sure these are examples and do not include any confidential or personal information.'
                        items:
                          type: string
                      add_security_recommendation:
                        type: boolean
                        description: Only for BODY component with AUTHENTICATION template category
                      code_expiration_minutes:
                        type: integer
                        default: 5
                        description: Only for FOOTER component with AUTHENTICATION template category
                      cards:
                        type: array
                        description: Required only for CAROUSEL type. You can create up to 10 cards.
                        items:
                          type: object
                          title: Registered template card component.
                          description: Each card should have a HEADER, BODY, BUTTONS components.
                          properties:
                            type:
                              type: string
                              default: BODY
                              description: Component type
                              enum:
                              - HEADER
                              - BODY
                              - BUTTONS
                            format:
                              type: string
                              enum:
                              - Image
                              - Video
                              example: Image
                              description: 'Component type.

                                Required for HEADER component type.'
                            text:
                              type: string
                              example: You can pickup your delivery at {{1}}
                              description: Component text. Required for BODY and FOOTER types
                            buttons:
                              type: array
                              items:
                                type: object
                                description: The parameters related to the button component
                                properties:
                                  type:
                                    type: string
                                    enum:
                                    - PHONE_NUMBER
                                    - URL
                                    - QUICK_REPLY
                                    - OTP
                                    - COPY_CODE
                                    description: Button type
                                  text:
                                    type: string
                                    description: The text to be displayed on the button.
                                    minLength: 1
                                    maxLength: 20
                                  phoneNumber:
                                    type: string
                                    description: 'Required for type "PHONE_NUMBER".


                                      The phone number that will be called on clicking the button.'
                                  country:
                                    type: string
                                    description: Optional country code of phone number (ISO 3166-1 alpha-2). Required if the phone number in the national format.
                                    minLength: 2
                                    maxLength: 2
                                    example: US
                                  url:
                                    type: string
                                    description: 'Required for type "URL".


                                      The URL that will be visited on clicking the button

                                      Variables can be used to create dynamic links.'
                                    format: uri
                                    example: https://website.com/{{1}}
                                  example:
                                    type: array
                                    description: 'To help WhatsApp moderators during the review and approval process, you can include example data. This can help WhatsApp understand what kind of message you plan to send and showcase the customer experience.


                                      For example, you could include an image that could represent a customer''s profile picture to personalize the experience.


                                      Make sure these are examples and do not include any confidential or personal information.'
                                    items:
                                      type: string
                                required:
                                - type
                                - text
                            examples:
                              type: array
                              description: 'To help WhatsApp moderators during the review and approval process, you can include example data. This can help WhatsApp understand what kind of message you plan to send and showcase the customer experience.


                                For example, you could include an image that could represent a customer''s profile picture to personalize the experience.


                                Make sure these are examples and do not include any confidential or personal information.'
                              items:
                                type: string
                          required:
                          - type
                    required:
                    - type
                allow_category_change:
                  type: boolean
                  example: false
                  description: set to true to allow whatsapp to automatically assign a category. If omitted, the template may be rejected due to mis-categorization.
                  default: true
                message_send_ttl_seconds:
                  type: integer
                  example: 300
                  description: 'Custom time-to-live (TTL) for message delivery in seconds. If a message cannot be delivered within this time, it will be dropped.<br/>Valid ranges: Authentication templates (30-900 seconds or -1 for 30 days), Utility templates (30-43200 seconds or -1 for 30 days), Marketing templates (43200-2592000 seconds).<br/>Default TTL: Authentication=10 minutes (600 seconds), Utility/Marketing=30 days.'
              required:
              - language
              - name
              - category
              - components
              title: Register template request
              description: Register template request
            examples:
              whatsAppMediaCarouselTemplate:
                summary: Add WhatsApp Media Carousel Template with 3 cards
                value:
                  language: en_US
                  name: <Insert Template Name>
                  allow_category_change: true
                  category: MARKETING
                  components:
                  - type: body
                    text: Rare succulents for sale! {{1}}, add these unique plants to your collection. Each of these rare succulents are {{2}} if you checkout using code {{3}}. Shop now and add some unique and beautiful plants to your collection!
                    examples:
                    - Pablo
                    - 30%
                    - 30OFF
                  - type: carousel
                    cards:
                    - components:
                      - type: header
                        format: image
                        examples:
                        - https://www.example.com/image.jpg
                      - type: body
                        text: Add a touch of elegance to your collection with the beautiful Aloe Blue Elf succulent. Its deep blue-green leaves have a hint of pink around the edges.
                      - type: buttons
                        buttons:
                        - type: quick_reply
                          text: Send me more like this!
                        - type: url
                          text: Shop
                          url: https://www.example.com/rare-succulents/{{1}}
                          examples:
                          - BLUE_ELF
                    - components:
                      - type: header
                        format: image
                        examples:
                        - https://www.example.com/image.jpg
                      - type: body
                        text: The Crassula Buddha Temple is sure to be a conversation starter with its tiny temple shaped leaves, intricate details, and lacy texture.
                      - type: buttons
                        buttons:
                        - type: quick_reply
                          text: Send me more like this!
                        - type: url
                          text: Shop
                          url: https://www.example.com/rare-succulents{{1}}
                          examples:
                          - BUDDHA
                    - components:
                      - type: header
                        format: image
                        examples:
                        - https://www.example.com/image.jpg
                      - type: body
                        text: The Echeveria Black Prince is a stunning succulent, with near-black leaves, adorned with a hint of green around the edges, giving it its striking appearance.
                      - type: buttons
                        buttons:
                        - type: quick_reply
                          text: Send me more like this!
                        - type: url
                          text: Shop
                          url: https://www.example.com/rare-succulents{{1}}
                          examples:
                          - BLACK_PRINCE
              whatsAppFlowTemplate:
                summary: Add WhatsApp Template with Flow Button
                value:
                  name: template_with_flow
                  category: MARKETING
                  language: en
                  components:
                  - type: BODY
                    text: Share your preferences with us to receive personalized recommendations.
                  - type: BUTTONS
                    buttons:
                    - type: FLOW
                      text: Share Info
                      flowId: '123456789876543'
                      flowAction: navigate
                      navigateScreen: RECOMMEND
              whatsAppCallPermissionTemplate:
                summary: Add WhatsApp Template with Call Permission Request
                value:
                  name: cpr_template_sample
                  category: MARKETING|UTILITY
                  language: en
                  components:
                  - type: HEADER
                    text: Customer Service Request
                  - type: BODY
                    text: We would like to call you to help resolve your recent inquiry faster and provide personalized assistance.
                  - type: FOOTER
                    text: Talk to you soon!
                  - type: CALL_PERMISSION_REQUEST
              whatsAppRequestContactInfoTemplate:
                summary: Add WhatsApp Template with Request Contact Info
                value:
                  name: template_request_call_info_v001
                  category: UTILITY
                  language: en
                  components:
                  - type: BODY
                    text: We request you to kindly share your contact info for further processing.
                  - type: BUTTONS
                    buttons:
                    - type: REQUEST_CONTACT_INFO
              whatsAppVoiceCallTemplate:
                summary: Add WhatsApp Template with Voice Call Button
                value:
                  name: template_with_voice_call
                  language: en_US
                  category: MARKETING|UTILITY
                  allow_category_change: true
                  components:
                  - type: HEADER
                    format: TEXT
                    text: Appointment Reminder
                  - type: BODY
                    text: 'You have an upcoming appointment scheduled with us.


                      If you need to reschedule or have any questions about your appointment, please call us directly using the button below.


                      Thank you!'
                  - type: FOOTER
                    text: We look forward to seeing you
                  - type: BUTTONS
                    buttons:
                    - type: VOICE_CALL
                      text: Call to Reschedule
                      ttlMinutes: 1440
        x-examples:
          application/json:
            language: en_US
            name: ticket_update_image_en_US
            category: UTILITY
            components:
            - type: HEADER
              format: IMAGE
            - type: BODY
              text: Your ticket {{1}} was closed.
            - type: FOOTER
              text: Support Team
      tags:
      - Management API
      description: "This endpoint is used to register new WhatsApp message template.\n\nPlease note that special html entities should be unescaped.\n\nWhatsApp Message Templates are message formats for common reusable messages a business may want to send. \nBusinesses must use Message Templates for sending notifications to customers.\nAny message sent outside the 24h customer service window, needs to be a template message, to be delivered. \nAdvertising, marketing, or promotional messages are not permitted."
      security:
      - apiKey: []
  /api/v1/accounts/{accountId}/channels/{channelId}/templates/{templateName}:
    parameters:
    - name: accountId
      in: path
      required: true
      schema:
        type: string
    - name: channelId
      in: path
      required: true
      schema:
        type: string
    - name: templateName
      in: path
      required: true
      schema:
        type: string
    servers:
    - url: https://chatapps.8x8.com
      description: Asia-Pacific region
    - url: https://chatapps.us.8x8.com
      description: North America region
    - url: https://chatapps.8x8.uk
      descripti

# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/8x8/refs/heads/main/openapi/8x8-management-api-api-openapi.yml