Vonage Themes API

openapi: 3.2.0
info:
  title: Vonage Themes API
  version: 0.1.7
  x-metaDescription: Find quick answers to questions about the Vonage Meetings API in this reference guide. Learn more in Vonage's API documentation.
  x-metaTitle: Vonage Meetings API Reference | Vonage API Documentation
  x-noIndex: true
  description: 'Operations tagged Themes across 2 of this provider''s published API definitions: vonage-meetings-openapi.json, vonage-meetings-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api-eu.vonage.com/v1/meetings
tags:
- name: Themes
paths:
  /themes:
    get:
      summary: Get application themes
      operationId: getThemes
      description: An application is limited to a thousand themes. Trying to create more themes will result in a 403 response.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Theme'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '403':
          description: Maximum number of themes for owner (1000) exceeded
      tags:
      - Themes
    post:
      summary: Create a theme
      operationId: createTheme
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateThemeDetails'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Theme'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '403':
          description: exceeded maximum theme limit
        '409':
          description: short_company_url already exist or theme_name already exist in application
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictError'
      tags:
      - Themes
    servers:
    - url: https://api-eu.vonage.com/v1/meetings
  /themes/:theme_id:
    get:
      summary: Get theme by theme id
      operationId: getThemeById
      security:
      - bearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Theme'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      tags:
      - Themes
    delete:
      summary: Delete a theme
      operationId: deleteTheme
      security:
      - bearerAuth: []
      parameters:
      - name: force
        in: query
        description: force delete - delete theme even if theme is used by rooms or as application default theme
        schema:
          type: boolean
      responses:
        '204':
          description: No Content
        '400':
          description: Theme is used by rooms or application
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      tags:
      - Themes
    patch:
      summary: Update theme by id
      operationId: updateTheme
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                update_details:
                  $ref: '#/components/schemas/UpdateThemeDetails'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Theme'
        '400':
          description: Invalid main_color or Invalid short_company_url or update_details must have at least 1 key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '404':
          description: Theme not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '409':
          description: short_company_url already exist or theme_name already exist in application
      tags:
      - Themes
    servers:
    - url: https://api-eu.vonage.com/v1/meetings
  /themes/:theme_id/finalizeLogos:
    put:
      summary: Change given logo to be permanent
      operationId: finalizeLogosForTheme
      security:
      - bearerAuth: []
      description: Use the theme ID of the theme you wish to update, along with the key used in the previous step, to link the logo with the theme that you wish to update. You can even make multiple upload calls, and then pass multiple keys to the theme update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinalizeThemeLogosRequestBody'
      responses:
        '200':
          description: OK
        '400':
          description: Logos has invalid property or Keys not found in bucket
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidLogoError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      tags:
      - Themes
    servers:
    - url: https://api-eu.vonage.com/v1/meetings
  /themes/logos-upload-urls:
    get:
      summary: Get URLs that can be used to upload logos for a theme via a POST
      operationId: getUploadUrlsForTheme
      security:
      - bearerAuth: []
      description: Use a GET on this API to retrieve the credentials needed for upload. The response will contain objects for each favicon, light logo, and colored logo. The Policy will be your JWT. Grab the values for the image type you wish to upload.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: list of S3 pre-signed URLs
                items:
                  $ref: '#/components/schemas/UploadUrlForTheme'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
      tags:
      - Themes
    servers:
    - url: https://api-eu.vonage.com/v1/meetings
  /themes/:themeId/rooms:
    get:
      summary: Get rooms associated with the theme
      operationId: getRoomsByThemeId
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/start_id_parameter'
      - $ref: '#/components/parameters/end_id_parameter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  page_size:
                    $ref: '#/components/schemas/PageSize'
                  total_items:
                    $ref: '#/components/schemas/TotalItems'
                  _embedded:
                    type: array
                    items:
                      $ref: '#/components/schemas/Room'
                  _links:
                    $ref: '#/components/schemas/HAL'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      tags:
      - Themes
    servers:
    - url: https://api-eu.vonage.com/v1/meetings
components:
  schemas:
    CreateThemeDetails:
      type: object
      required:
      - main_color
      - brand_text
      properties:
        theme_name:
          $ref: '#/components/schemas/Theme_Name'
        main_color:
          $ref: '#/components/schemas/Theme_MainColor'
        brand_text:
          $ref: '#/components/schemas/Theme_BrandText'
        short_company_url:
          $ref: '#/components/schemas/Theme_ShortCompanyUrl'
    Theme_BrandText:
      type: string
      example: Brand
      maxLength: 200
      description: The text that will appear on the meeting homepage, in the case that there is no brand image
    JoinApprovalLevel:
      type: string
      enum:
      - none
      - after_owner_only
      - explicit_approval
      description: The level of approval needed to join the meeting in the room. When set to "after_owner_only" the participants will join the meeting only after the host joined. When set to "explicit_approval" the participants will join the waiting room and the host will deny/approve them.
    Theme_ShortCompanyUrl:
      type: string
      maxLength: 128
      pattern: ^(?=.*[a-zA-Z_~-])([a-zA-Z0-9_~-]+)$
      example: short-url
      description: The URL that will represent every meeting room with this theme. The value must be unique across Vonage
    Room_Type:
      type: string
      description: The type of meeting which can be instant or long term. An instant is active for 10 minutes until the first participant joins the roo, and remains active for 10 minutes after the last participant leaves. A long term room expires after a specific date
      default: instant
      enum:
      - instant
      - long_term
    Room_ExpiresAt:
      type: string
      format: date
      example: '2023-06-06T06:55:07.134Z'
      description: The time for when the room will be expired, expressed in ISO 8601 format. The value must be greater than 10 minutes from now
    Theme_Id:
      type: string
      format: uuid
      description: The theme UUID
      example: ef2b46f3-8ebb-437e-a671-272e4990fbc8
    Theme_Domain:
      type: string
      enum:
      - VCP
      - VBC
      example: VCP
      description: The domain of the theme
    Room_CreatedAt:
      type: string
      format: date
      example: '2023-06-06T06:45:07.135Z'
      description: The time for when the room was created, expressed in ISO 8601 format
    HAL:
      type: object
      description: Represents HAL links for navigation purposes
      properties:
        first:
          type: object
          description: Provides a link to the first element
          properties:
            href:
              type: string
              example: https://api-eu.vonage.com/v1/meetings/rooms?page_size=50
        self:
          type: object
          description: Provides a link to the current element
          properties:
            href:
              type: string
              example: https://api-eu.vonage.com/v1/meetings/rooms?page_size=50&start_id=2293905
        next:
          type: object
          description: Provides a link to the next element
          properties:
            href:
              type: string
              example: https://api-eu.vonage.com/v1/meetings/rooms?page_size=50&start_id=2293906
        prev:
          type: object
          description: Provides a link to the previous element
          properties:
            href:
              type: string
              example: https://api-eu.vonage.com/v1/meetings/rooms?page_size=50&start_id=2293904
    ConflictError:
      type: object
      properties:
        message:
          type: string
          example: short_company_url already exists
        name:
          type: string
          example: ConflictError
        status:
          type: integer
          example: 409
    InvalidLogoError:
      properties:
        status:
          type: integer
          enum:
          - 400
        name:
          type: string
          enum:
          - BadRequestError
        message:
          type: string
          enum:
          - could not finalize logos
        errors:
          type: array
          description: each error has logoKey, code and invalidProperty if it is invalid logo property error
          items:
            type: object
            properties:
              logoKey:
                type: string
              code:
                type: string
                enum:
                - invalid_logo_properties
                - key_not_found
              invalidProperty:
                type: string
                enum:
                - exceeds_size
                - type
                - dimensions
                - transparent_bg
    Room_GuestUrl:
      type: object
      description: The link to join the meeting as participant, using the meeting code
      properties:
        href:
          type: string
          example: https://meetings.vonage.com/280674154
    BadRequestError:
      type: object
      properties:
        message:
          type: string
          example: Explanation about why validation failed.
        name:
          type: string
          example: InputValidationError
        status:
          type: integer
          example: 400
    CallbackUrls:
      type: object
      description: Provides callback URLs to listen to events
      properties:
        rooms_callback_url:
          type: string
          description: Callback url for rooms events, overrides application level rooms callback url.
          pattern: ^https?:\\/\\/.*$
          example: https://example.com/rooms
        sessions_callback_url:
          type: string
          description: Callback url for sessions events, overrides application level sessions callback url.
          pattern: ^https?:\\/\\/.*$
          example: https://example.com/sessions
        recordings_callback_url:
          type: string
          description: Callback url for recordings events, overrides application level recordings callback url.
          pattern: ^https?:\\/\\/.*$
          example: https://example.com/recordings
    UploadUrlForTheme:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: Storage system URL
          example: https://storage-url.com
        fields:
          type: object
          description: Fields property has to be part of the POST request's body
          properties:
            Content-Type:
              type: string
              example: image/png
            key:
              type: string
              example: auto-expiring-temp/logos/white/ca63a155-d5f0-4131-9903-c59907e53df0
              description: Logo's key in storage system
            logoType:
              type: string
              enum:
              - white
              - colored
              - favicon
              example: favicon
            bucket:
              type: string
              description: Bucket name to upload to
              example: roomservice-whitelabel-logos-prod
            X-Amz-Algorithm:
              type: string
              example: AWS4-HMAC-SHA256
            X-Amz-Credential:
              type: string
              example: ASSCSSQSAMKJISDGBW/20220410/us-east-1/s3/aws4_request
            X-Amz-Date:
              type: string
              example: 20220410T200246Z
            X-Amz-Security-Token:
              type: string
              example: IQoJb3JpZ2luX2VjEBIaCXVzLWVhc3QtMSJHMEUCIDMxvPG4
            Policy:
              type: string
              example: eyJleHBpcmF0aW9uIjoiMjAyMy0wNi0wN1QxMjo0Njo0MFo
            X-Amz-Signature:
              type: string
              example: fcb46c1adfa98836f0533aadebedc6fb1edbd90aa583f3264c0ae5bb63d83123
    AuthenticationError:
      type: object
      properties:
        title:
          type: string
          example: Missing Auth
        detail:
          type: string
          example: Auth header is required
    PageSize:
      type: integer
      example: 25
      description: The number of results returned on this page
    Room_IsAvailable:
      type: boolean
      description: Once a room becomes unavailable, no new sessions can be created under it
      default: true
    AccountId:
      type: string
      example: 123ab4cd
      description: The applications account id (ApiKey)
    Theme_Name:
      type: string
      maxLength: 200
      example: Theme1
      description: The name of the theme (must be unique). If null, a UUID will automatically be generated
    UpdateThemeDetails:
      type: object
      properties:
        theme_name:
          $ref: '#/components/schemas/Theme_Name'
        main_color:
          $ref: '#/components/schemas/Theme_MainColor'
        brand_text:
          $ref: '#/components/schemas/Theme_BrandText'
        short_company_url:
          $ref: '#/components/schemas/Theme_ShortCompanyUrl'
    InitialJoinOptions:
      type: object
      description: Sets the default options for participants
      properties:
        microphone_state:
          type: string
          enum:
          - 'on'
          - 'off'
          - default
          default: default
          description: Set the default microphone option for users in the pre-join screen of this room.
          example: 'on'
    Room_ExpiresAfterUse:
      type: boolean
      description: Close the room after a session ends. Only relevant for long_term rooms
      default: false
      example: true
    Theme:
      type: object
      properties:
        theme_id:
          $ref: '#/components/schemas/Theme_Id'
        theme_name:
          $ref: '#/components/schemas/Theme_Name'
        domain:
          $ref: '#/components/schemas/Theme_Domain'
        account_id:
          $ref: '#/components/schemas/AccountId'
        application_id:
          $ref: '#/components/schemas/ApplicationId'
        main_color:
          $ref: '#/components/schemas/Theme_MainColor'
        short_company_url:
          $ref: '#/components/schemas/Theme_ShortCompanyUrl'
        brand_text:
          $ref: '#/components/schemas/Theme_BrandText'
        brand_image_colored:
          type: string
          description: Colored logo's key in storage system
          example: branded-image-colored
        brand_image_white:
          type: string
          description: White logo's key in storage system
          example: branded-image-white
        branded_favicon:
          type: string
          description: Favicon key in storage system
          example: branded-favicon
        brand_image_colored_url:
          type: string
          description: Colored logo's link
          example: branded-image-colored-url
        brand_image_white_url:
          type: string
          description: White logo's link
          example: branded-image-white-url
        branded_favicon_url:
          type: string
          description: Favicon link
          example: branded-favicon-url
    FinalizeThemeLogosRequestBody:
      type: object
      properties:
        keys:
          type: array
          description: List of temporary theme's logos to make permanent
          example:
          - logo-key1
          - logo-key2
          items:
            type: object
            properties:
              key:
                type: string
                description: Key used for uploading a logo
    Room_Name:
      type: string
      maxLength: 200
      description: The name of the meeting room
      example: My custom room
    ApplicationId:
      type: string
      format: uuid
      example: 921a6f5b-1f94-49f4-8107-26f0c75fc6e7
      description: The application Id
    UiSettings:
      type: object
      description: Provides options to customize the user interface
      properties:
        language:
          type: string
          enum:
          - ar
          - ca
          - de
          - en
          - es
          - fr
          - he
          - it
          - pt-br
          - zh-tw
          - zh-cn
          description: The desired language of the UI. The default is English.
          default: en
          example: es
    AvailableFeatures:
      type: object
      properties:
        is_recording_available:
          type: boolean
          default: true
          description: Determine if recording feature is available in the UI.
        is_chat_available:
          type: boolean
          default: true
          description: Determine if chat feature is available in the UI.
        is_whiteboard_available:
          type: boolean
          default: true
          description: Determine if whiteboard feature is available in the UI.
        is_locale_switcher_available:
          type: boolean
          default: true
          description: Determine if the locale switcher is available in the UI.
        is_captions_available:
          type: boolean
          default: false
          description: Determine if captions are available in the UI.
    Room:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Room_Id'
        display_name:
          $ref: '#/components/schemas/Room_Name'
        metadata:
          $ref: '#/components/schemas/Room_Metadata'
        type:
          $ref: '#/components/schemas/Room_Type'
        recording_options:
          $ref: '#/components/schemas/RecordingOptions'
        meeting_code:
          $ref: '#/components/schemas/Room_MeetingCode'
        is_available:
          $ref: '#/components/schemas/Room_IsAvailable'
        theme_id:
          $ref: '#/components/schemas/Theme_Id'
        created_at:
          $ref: '#/components/schemas/Room_CreatedAt'
        expires_at:
          $ref: '#/components/schemas/Room_ExpiresAt'
        expire_after_use:
          $ref: '#/components/schemas/Room_ExpiresAfterUse'
        join_approval_level:
          $ref: '#/components/schemas/JoinApprovalLevel'
        initial_join_options:
          $ref: '#/components/schemas/InitialJoinOptions'
        callback_urls:
          $ref: '#/components/schemas/CallbackUrls'
        available_features:
          $ref: '#/components/schemas/AvailableFeatures'
        ui_settings:
          $ref: '#/components/schemas/UiSettings'
        _links:
          type: object
          description: Provides links to join the meeting room
          properties:
            guest_url:
              $ref: '#/components/schemas/Room_GuestUrl'
            host_url:
              $ref: '#/components/schemas/Room_HostUrl'
    NotFoundError:
      type: object
      properties:
        message:
          type: string
          example: Failed to fetch resource with id 50da57f5-0aaf-4ac5-804c-2114afc89197
        name:
          type: string
          example: NotFoundError
        status:
          type: integer
          example: 404
    Room_Id:
      type: string
      format: uuid
      description: The room UUID
      example: 9f6fe8ae-3458-4a72-b532-8276d5533e97
    Theme_MainColor:
      maxLength: 7
      type: string
      pattern: '#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$'
      example: '#12f64e'
      description: The main color that will be used for the meeting room.
    Room_Metadata:
      maxLength: 500
      type: string
      description: Free text that can be attached to a room. This will be passed in the form of a header in events related to this room.
      example: Welcome to my custom room
    RecordingOptions:
      type: object
      description: An object containing various meeting recording options
      properties:
        auto_record:
          type: boolean
          description: Automatically record all sessions in this room. Recording cannot be stopped when this is set to `true`.
          default: false
        record_only_owner:
          type: boolean
          description: Record only the owner screen or any share screen of the video.
          default: false
    Room_MeetingCode:
      type: string
      pattern: ^\d+$
      example: '280674154'
      minLength: 9
      description: The meeting PIN number
    Room_HostUrl:
      type: object
      description: The link to join the meeting as host, using the meeting code
      properties:
        href:
          type: string
          example: https://meetings.vonage.com/?room_token=280674154&participant_token=eyJhbGciOiJIUzI1NiIsInR5cC
    TotalItems:
      type: integer
      example: 30
      description: The overall number of results
  parameters:
    start_id_parameter:
      name: start_id
      in: query
      schema:
        type: integer
      example: 13
      required: false
      description: The room serial number to filter from - This number is not the room Id
    end_id_parameter:
      name: end_id
      in: query
      schema:
        type: integer
      example: 13
      required: false
      description: The room serial number to filter to (excluding end_id itself) - This number is not the room Id
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- vonage-meetings-openapi.json
- vonage-meetings-openapi.yml
x-errors:
  validation:
    description: The provided payload is invalid
    resolution: 'Modify your request to provide a valid payload.

      * Minimum 8 characters

      * Maximum 25 characters

      * Minimum 1 lower case character

      * Minimum 1 upper case character

      * Minimum 1 digit

      '
    link:
      text: View API reference
      url: /api/account#createAPISecret
  delete-last-secret:
    description: You can not delete your only API secret
    resolution: Add another API secret before deleting this one