openapi: 3.0.0
info:
  title: Keyboard Shortcuts
  description: The Keyboard Shortcuts API lets users fetch all shortcuts, customize defaults, add custom shortcuts, and reset custom shortcuts to defaults.
  contact: {}
  version: 1.0.0
externalDocs:
  description: Find out more about Zoho Cliq APIs V3
  url: https://www.zoho.com/cliq/help/restapi/v3/
servers:
  - url: https://cliq.zoho.com/api/v3
    description: Zoho Cliq US DC
tags:
  - name: keyboardshortcuts
    description: Keyboard Shortcuts Module
paths:
  /settings/keyboardshortcuts:
    get:
      summary: Fetch all keyboard shortcuts
      operationId: fetchKeyboardShortcuts
      description: |
        Retrieves all keyboard shortcuts for the authenticated user, including default shortcuts and any custom shortcuts. If the user does not have any custom shortcuts, all default shortcuts will be returned.
        <br><br>
        <p>
          <b>OAuth Scope</b>: ZohoCliq.Profile.READ<br>
          <b>Duration</b>: 5<br>
          <b>Threshold</b>: 20 requests per min per user<br>
          <b>Lock period</b>: 5 minutes<br>
        </p>
        <br><b>Possible Error Codes</b><br><br>
        <table style="border-collapse: collapse; width: 100%; font-family: inherit;">
          <tr>
            <th style="padding: 8px; text-align: center; border: 1px solid #ddd; font-family: inherit; min-width: 220px; word-break: break-word;">Error Code</th>
            <th style="padding: 8px; text-align: center; border: 1px solid #ddd; font-family: inherit;">Description</th>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>invalid_oauthtoken</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">The access token is invalid or expired.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>invalid_access</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">The user does not have access to this resource.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>operation_failed</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Unexpected server error while processing the request.</td>
          </tr>
        </table>
        <br><b>Error Response Format</b><br>
        <p style="font-family:inherit;">When an error occurs, the API returns a JSON response in this format:<br><br>
        <code>{"message": "A human-readable description of the error.", "code": "error_code"}</code><br><br>
        where <code>code</code> is the error identifier (as listed in the table above) and <code>message</code> is a human-readable explanation of what went wrong.</p>
      responses:
        '200':
          description: Keyboard shortcuts were fetched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/keyboard-shortcuts-response'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      security:
        - Cliq_Auth:
            - ZohoCliq.Profile.READ
      tags:
        - keyboardshortcuts
    put:
      summary: Update keyboard shortcuts
      operationId: updateKeyboardShortcuts
      description: |
        Updates default or custom keyboard shortcuts for the authenticated user. The shortcut details must be passed in JSON format.
        <br><br>
        <ul>
          <li><b>Default shortcuts:</b> Provide the category (e.g., <code>basic</code>, <code>composer</code>, <code>message_action</code>, <code>annotate</code>, <code>media</code>, <code>networks</code>), the shortcut name, and the OS key (<code>windows</code> or <code>mac</code>).</li>
          <li><b>Custom shortcuts:</b>
            <ul>
              <li><b>Chat / Widget:</b> Requires an <code>id</code> (chat ID or widget ID respectively) along with the OS key.</li>
              <li><b>Snippet:</b> Requires a <code>name</code> and <code>message</code> along with the OS key.</li>
            </ul>
          </li>
          <li><b>Overlap validation:</b> When updating, the new shortcut key is validated against existing shortcuts to prevent overlap. If the key is already mapped to another action, an error is returned.</li>
        </ul>
        <br>
        <p>
          <b>OAuth Scope</b>: ZohoCliq.Profile.UPDATE<br>
          <b>Duration</b>: 5<br>
          <b>Threshold</b>: 20 requests per min per user<br>
          <b>Lock period</b>: 5 minutes<br>
        </p>
        <br><b>Possible Error Codes</b><br><br>
        <table style="border-collapse: collapse; width: 100%; font-family: inherit;">
          <tr>
            <th style="padding: 8px; text-align: center; border: 1px solid #ddd; font-family: inherit; min-width: 220px; word-break: break-word;">Error Code</th>
            <th style="padding: 8px; text-align: center; border: 1px solid #ddd; font-family: inherit;">Description</th>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>shortcut_overlap</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Shortcut key is already mapped to another action.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>invalid_shortcut_payload</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Payload structure is invalid.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>invalid_widget_id</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Provided widget ID does not exist.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>invalid_chat_id</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Provided chat ID does not exist.</td>
          </tr>
        </table>
        <br><b>Error Response Format</b><br>
        <p style="font-family:inherit;">When an error occurs, the API returns a JSON response in this format:<br><br>
        <code>{"message": "A human-readable description of the error.", "code": "error_code"}</code><br><br>
        where <code>code</code> is the error identifier (as listed in the table above) and <code>message</code> is a human-readable explanation of what went wrong.</p>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-keyboard-shortcuts-request'
      responses:
        '200':
          description: Keyboard shortcuts were updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/no-response'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      security:
        - Cliq_Auth:
            - ZohoCliq.Profile.UPDATE
      tags:
        - keyboardshortcuts
    delete:
      summary: Delete keyboard shortcuts customization
      operationId: deleteKeyboardShortcuts
      description: |
        Resets all custom shortcuts to defaults, or deletes only the specific mappings provided in the request payload. To delete a single shortcut key, pass the same input structure as the update (PUT) request with the target shortcut details.
        <br><br>
        <p>
          <b>OAuth Scope</b>: ZohoCliq.Profile.DELETE<br>
          <b>Duration</b>: 5<br>
          <b>Threshold</b>: 20 requests per min per user<br>
          <b>Lock period</b>: 5 minutes<br>
        </p>
        <br><b>Possible Error Codes</b><br><br>
        <table style="border-collapse: collapse; width: 100%; font-family: inherit;">
          <tr>
            <th style="padding: 8px; text-align: center; border: 1px solid #ddd; font-family: inherit; min-width: 220px; word-break: break-word;">Error Code</th>
            <th style="padding: 8px; text-align: center; border: 1px solid #ddd; font-family: inherit;">Description</th>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>invalid_shortcut_payload</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Payload structure is invalid for targeted deletion.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>operation_failed</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Unexpected server error while deleting custom shortcuts.</td>
          </tr>
        </table>
        <br><b>Error Response Format</b><br>
        <p style="font-family:inherit;">When an error occurs, the API returns a JSON response in this format:<br><br>
        <code>{"message": "A human-readable description of the error.", "code": "error_code"}</code><br><br>
        where <code>code</code> is the error identifier (as listed in the table above) and <code>message</code> is a human-readable explanation of what went wrong.</p>
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-keyboard-shortcuts-request'
      responses:
        '204':
          description: Keyboard shortcuts reset/deletion completed successfully.
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      security:
        - Cliq_Auth:
            - ZohoCliq.Profile.DELETE
      tags:
        - keyboardshortcuts
components:
  schemas:
    no-response:
      type: object
      properties:
        status:
          type: string
          example: success
    error-response:
      type: object
      properties:
        message:
          type: string
          description: Detailed error message.
      required:
        - message
    os-shortcut:
      type: object
      properties:
        windows:
          type: string
          description: Shortcut mapping for Windows.
        mac:
          type: string
          description: Shortcut mapping for Mac.
    custom-chat-or-widget-entry:
      type: object
      properties:
        windows:
          type: string
          description: Shortcut mapping for Windows.
        mac:
          type: string
          description: Shortcut mapping for Mac.
        id:
          type: string
          description: Chat or widget identifier.
      required:
        - id
    custom-snippet-entry:
      type: object
      properties:
        name:
          type: string
          description: Name of snippet shortcut.
        message:
          type: string
          description: Snippet content.
        windows:
          type: string
          description: Shortcut mapping for Windows.
        mac:
          type: string
          description: Shortcut mapping for Mac.
      required:
        - name
        - message
    keyboard-shortcuts-object:
      type: object
      additionalProperties: true
      properties:
        basic:
          type: object
          description: Basic navigation shortcuts (e.g., interacting with elements, moving sections, moving focus).
          additionalProperties:
            $ref: '#/components/schemas/os-shortcut'
        composer:
          type: object
          description: Message composer shortcuts (e.g., bold, italic, underline).
          additionalProperties:
            $ref: '#/components/schemas/os-shortcut'
        message_action:
          type: object
          description: Message action shortcuts (e.g., star message, add reaction, go to writing assistant).
          additionalProperties:
            $ref: '#/components/schemas/os-shortcut'
        annotate:
          type: object
          description: Annotation tool shortcuts (e.g., rectangle, add line, text).
          additionalProperties:
            $ref: '#/components/schemas/os-shortcut'
        media:
          type: object
          description: Media call shortcuts (e.g., mute/unmute, video on/off, temporary unmute).
          additionalProperties:
            $ref: '#/components/schemas/os-shortcut'
        networks:
          type: object
          description: Network navigation shortcuts (e.g., navigate between networks).
          additionalProperties:
            $ref: '#/components/schemas/os-shortcut'
        custom:
          type: object
          properties:
            chat:
              type: array
              items:
                $ref: '#/components/schemas/custom-chat-or-widget-entry'
            widget:
              type: array
              items:
                $ref: '#/components/schemas/custom-chat-or-widget-entry'
            snippet:
              type: array
              items:
                $ref: '#/components/schemas/custom-snippet-entry'
    keyboard-shortcuts-response:
      type: object
      properties:
        keyboard_shortcuts:
          $ref: '#/components/schemas/keyboard-shortcuts-object'
      required:
        - keyboard_shortcuts
    update-keyboard-shortcuts-request:
      type: object
      additionalProperties: true
      properties:
        basic:
          type: object
          description: Basic navigation shortcuts to update (e.g., interacting with elements, moving sections, moving focus).
          additionalProperties:
            $ref: '#/components/schemas/os-shortcut'
        composer:
          type: object
          description: Message composer shortcuts to update (e.g., bold, italic, underline).
          additionalProperties:
            $ref: '#/components/schemas/os-shortcut'
        message_action:
          type: object
          description: Message action shortcuts to update (e.g., star message, add reaction, go to writing assistant).
          additionalProperties:
            $ref: '#/components/schemas/os-shortcut'
        annotate:
          type: object
          description: Annotation tool shortcuts to update (e.g., rectangle, add line, text).
          additionalProperties:
            $ref: '#/components/schemas/os-shortcut'
        media:
          type: object
          description: Media call shortcuts to update (e.g., mute/unmute, video on/off, temporary unmute).
          additionalProperties:
            $ref: '#/components/schemas/os-shortcut'
        networks:
          type: object
          description: Network navigation shortcuts to update (e.g., navigate between networks).
          additionalProperties:
            $ref: '#/components/schemas/os-shortcut'
        custom:
          type: object
          description: |
            Custom shortcuts to update. To update a custom shortcut, provide the complete details of the shortcut (including the new key mapping and associated chat/widget/snippet information). Partial updates are not supported for custom shortcuts.
            <b>Allowed custom shortcut types:</b>
            <ul>
              <li><code>chat</code>: Requires an <code>id</code> (chat ID) along with the new shortcut key mapping.</li>
              <li><code>widget</code>: Requires an <code>id</code> (widget ID) along with the new shortcut key mapping.</li>
              <li><code>snippet</code>: Requires a <code>name</code>, <code>message</code>, and the new shortcut key mapping.</li>
            </ul>
          additionalProperties: true
  securitySchemes:
    Cliq_Auth:
      type: oauth2
      x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoCliq.Profile.READ: Read user profile settings
            ZohoCliq.Profile.UPDATE: Update user profile settings
            ZohoCliq.Profile.DELETE: Delete user profile settings
