openapi: 3.0.0
info:
  title: Bots
  description: |
    <p>Bots are conversational assistants designed to automate repetitive tasks and manage simple user interactions. Their behavior is fully customizable through predefined Bot Handlers, which are activated by specific actions or through Webhooks that communicate with your own external server.</p> <p>For more information about Bots, please refer to the <b><a href="https://www.zoho.com/cliq/help/platform/bots.html" target="_blank">Bots Help Documentation</a></b>.</p> <p><b>Bot Handlers</b></p> <ul>
      <li>Bot Handlers are the building blocks of a bot's functionality. Each handler is associated with a specific trigger event, such as receiving a direct message, being @mentioned in a channel, or a user subscribing to the bot.</li>
      <li>When the trigger event occurs, the corresponding handler executes it's script to perform actions like sending messages, making API calls, or updating data.</li>
      <li>By configuring different handlers, you can create bots that respond intelligently to various user interactions and automate complex workflows within Zoho Cliq.</li>
    </ul> <p><b>Types of Bot Handlers</b></p> <table style="border-collapse: collapse; width: 100%;">
      <tr>
        <th style="padding: 8px; text-align: left; border: 1px solid #ddd;">Handler</th>
        <th style="padding: 8px; text-align: left; border: 1px solid #ddd;">Description</th>
      </tr>
      <tr>
        <td style="padding: 8px; border: 1px solid #ddd;">Menu Handler</td>
        <td style="padding: 8px; border: 1px solid #ddd;">Adds up to 5 quick-action items to the bot's chat menu. Triggered when a user interacts with the menu.</td>
      </tr>
      <tr>
        <td style="padding: 8px; border: 1px solid #ddd;">Message Handler</td>
        <td style="padding: 8px; border: 1px solid #ddd;">Triggered when the bot receives a message.</td>
      </tr>
      <tr>
        <td style="padding: 8px; border: 1px solid #ddd;">Welcome Handler</td>
        <td style="padding: 8px; border: 1px solid #ddd;">Defines the greeting message sent when a user subscribes to the bot.</td>
      </tr>
      <tr>
        <td style="padding: 8px; border: 1px solid #ddd;">Mention Handler</td>
        <td style="padding: 8px; border: 1px solid #ddd;">Triggered when the bot is @mentioned in a chat or channel.</td>
      </tr>
      <tr>
        <td style="padding: 8px; border: 1px solid #ddd;">Incoming Webhook Handler</td>
        <td style="padding: 8px; border: 1px solid #ddd;">Allows external services to post messages into the bot via outgoing webhooks.</td>
      </tr>
      <tr>
        <td style="padding: 8px; border: 1px solid #ddd;">Context Handler</td>
        <td style="padding: 8px; border: 1px solid #ddd;">Manages multi-turn conversations, maintaining context across a user's interaction with the bot.</td>
      </tr>
    </table> <p><b>What you can do with the Bots API?</b></p> <p>With the Bots API, you can retrieve information about a specific bot, list all bots within your organization, manage configurations specific to handlers, trigger bot calls programmatically, manage subscribers, and much more.</p> <p>Each bot has an <code>execution_type</code> that defines how its handlers run when a trigger event occurs. The Bots API allows developers to create two types of bots:</p> <p id="deluge-bots"><b>Deluge Bots (default)</b><br> Deluge bot executes handler logic using Zoho's Deluge scripting language, hosted entirely within the Zoho Cliq Developer platform, where no external server is required.</p> <ul>
      <li>If <code>execution_type</code> is not specified during bot creation, it defaults to deluge.</li>
      <li>Handler logic is defined as a script field (Deluge source code) when creating or updating handlers.</li>
      <li>Suitable for teams that want to build and manage bot logic entirely within Zoho's ecosystem.</li>
    </ul> <p id="webhook-bots"><b>Webhook Bots</b><br> A Webhook bot delegates all handler execution to your own external server. When a trigger event fires, Zoho Cliq sends an HTTP POST request to the <code>execution_url</code> you configure, and your server processes the event and returns a response.</p> <ul>
      <li>To create a Webhook bot, set <code>execution_type</code> to webhook during bot creation and provide the <code>execution_url</code> where event payloads should be sent.</li>
      <li>Your server must be publicly accessible and able to handle incoming POST requests from Zoho Cliq.</li>
      <li>Ideal for teams seeking complete control over bot logic and possessing the resources to manage an external server. Also suitable for integrations requiring access to external databases, third-party APIs, or custom business logic that cannot be executed in Deluge.</li>
    </ul>
  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: bots
    description: APIs related to managing bots, including creating, updating, retrieving details, and listing bots in the organization.
paths:
  /bots:
    post:
      summary: Create a bot
      operationId: create_a_new_bot
      description: |
        Create a new bot in Cliq by specifying the bot's display name, description, and access level (organization or team). Upon creation, Cliq auto-assigns a <code>unique_name</code> as a permanent identifier for the bot - this cannot be changed even if the display name is updated later.<br><br>After creation, add handlers to define the bot's behaviour for each trigger event.<br>
        With this API, you can create both <a href="/cliq/help/restapi/v3/bots/#deluge-bots">Deluge bots</a> (which run handler logic within Zoho's platform) and <a href="/cliq/help/restapi/v3/bots/#webhook-bots">Webhook bots</a> (which delegate execution to your own server).
        <p>
          <b>Threshold limit</b>: 10 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 5 minutes<br>Wait time before consecutive API requests.<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>bot_creation_limit_exceeded</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Organization has reached the maximum number of bots.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>bot_name_already_exists</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">A bot with this name already exists.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>invalid_inputs</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Request body validation failed.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>execution_url_required</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>execution_url</code> is required when <code>execution_type</code> is set to <code>webhook</code>.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>execution_url_not_allowed</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>execution_url</code> is not allowed when <code>execution_type</code> is set to <code>deluge</code>.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>invalid_scope</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">The provided <code>scope</code> value is invalid. Allowed values are <code>organization</code>, <code>team</code>, and <code>personal</code>.</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:
        description: Creates a bot. Provide `name` (display name) and `description`; use `scope` and optional fields to control visibility and behavior. The `unique_name` is auto-assigned by Cliq as a permanent identifier and cannot be provided or changed.
        content:
          application/json:
            examples:
              deluge_bot:
                summary: Deluge Bot - Internal client care assistant
                value:
                  name: Clientcare Bot
                  description: Your client care co-pilot streamlining support by providing instant customer context and easy access to critical resources.
                  scope: team
                  team_ids:
                    - 12345678
                  status_messages:
                    - Here to help you with client support!
                  channel_participation:
                    - send_message
                  calls: enabled
              webhook_bot:
                summary: Webhook Bot - CI/CD pipeline alert bot
                value:
                  name: Pipeline Alert Bot
                  description: Sends real-time CI/CD pipeline status alerts to engineering teams. Triggered by your external build server via webhook on each build, test, or deployment event.
                  scope: team
                  team_ids:
                    - 98765432
                  execution_type: webhook
                  execution_url: https://ci.zylker.com/cliq-webhook/pipeline-alerts
                  status_messages:
                    - Monitoring your pipelines 24/7
                  channel_participation:
                    - listen_message
                    - send_message
                  calls: enabled
            schema:
              $ref: '#/components/schemas/BotCreate'
        required: true
      responses:
        '200':
          description: Bot created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotCreateResponse'
              examples:
                deluge_bot:
                  summary: Deluge Bot response
                  value:
                    url: /api/v3/bots
                    type: bot
                    data:
                      unique_name: clientcarebot
                      name: Clientcare Bot
                      id: '53719000002124012'
                      description: Your client care co-pilot streamlining support by providing instant customer context and easy access to critical resources.
                      scope: team
                      team_ids:
                        - 12345678
                      status_messages:
                        - Here to help you with client support!
                      channel_participation:
                        - send_message
                      calls: enabled
                      handlers: []
                      creator:
                        name: James
                        id: '65113112'
                      execution_type: deluge
                      status: enabled
                      type: custom
                      default: false
                      subscriber_count: 1
                webhook_bot:
                  summary: Webhook Bot response
                  value:
                    url: /api/v3/bots
                    type: bot
                    data:
                      unique_name: pipelinealertbot
                      name: Pipeline Alert Bot
                      id: '53719000002198034'
                      description: Sends real-time CI/CD pipeline status alerts to engineering teams. Triggered by your external build server via webhook on each build, test, or deployment event.
                      scope: team
                      team_ids:
                        - 98765432
                      status_messages:
                        - Monitoring your pipelines 24/7
                      channel_participation:
                        - listen_message
                        - send_message
                      calls: enabled
                      handlers: []
                      creator:
                        name: James
                        id: '65113112'
                      execution_type: webhook
                      execution_url: https://ci.zylker.com/cliq-webhook/pipeline-alerts
                      status: enabled
                      type: custom
                      default: false
                      subscriber_count: 1
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Bots.CREATE
      tags:
        - bots
    get:
      summary: List all bots
      operationId: list_all_bots
      description: |
        Retrieves a paginated list of all Bots available to the user.<br><br>
        Use <b>limit</b> and <b>next_token</b> for cursor-based pagination, <b>sync_token</b> for incremental sync, and <b>search</b> and <b>scope</b> to filter results when browsing the Marketplace catalogue.
        <br>
        <p>
          <b>Threshold limit</b>: 30 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 5 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      parameters:
        - name: limit
          in: query
          description: |
            Size of the set to be fetched.<br>
            Default value is <b>20</b> and maximum allowed value is <b>50</b>.
          required: false
          schema:
            type: integer
        - name: sync_token
          in: query
          description: |
            To fetch the bots which recently got added or updated after the previous request was made. 
          required: false
          schema:
            type: string
        - name: next_token
          in: query
          description: |
            Pagination token to fetch the next set of bots.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: List of bots returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotListResponse'
              example:
                url: /api/v3/bots
                type: bot
                next_token: NTB8MTc1NjM2MjA5MzQ5OHw1MzcxOTAwMDAwMTYyMDAwMw==
                sync_token: NTB8MTc3NzM0MjEyNzQ3OHw1MzcxOTAwMDAwMTg3ODAxMQ==
                data:
                  - unique_name: supportbot
                    name: Support Bot
                    id: '53719000001878011'
                    description: Handles support workflows
                    scope: organization
                    channel_participation:
                      - listen_message
                      - send_message
                      - auto_follow_thread
                    handlers:
                      - type: call_handler
                      - type: welcome_handler
                      - type: context_handler
                      - type: message_handler
                      - type: menu_handler
                        id: '53719000001878017'
                        name: Action
                        icon: wand/627282
                        position: 1
                        sub_actions:
                          - name: Sub Action
                            icon: wand/627282
                    creator:
                      name: James
                      id: '65113112'
                    execution_type: deluge
                    status: enabled
                    type: custom
                    default: false
                    subscriber_count: 1
                    calls: disabled
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Bots.READ
      tags:
        - bots
  /bots/{BOT_ID}:
    patch:
      summary: Update an existing bot
      operationId: update_an_existing_bot
      description: |
        Update the details and configuration of an existing bot. You can change the bot's display name, description, access level (organization-wide, team, or personal), and logo.<br>
        <br><b>Note:</b>
        <ul>
          <li>The bot's <code>unique_name</code> is auto-assigned by Cliq upon creation and serves as a permanent identifier. It cannot be changed even if the display name is updated.</li>
          <li>For <b>Webhook bots</b>, the <code>execution_url</code> can be updated independently - you can point the bot to a new server endpoint without changing any other configuration.</li>
        </ul>
        <br>
        <p>
          <b>Threshold limit</b>: 10 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 5 minutes<br>Wait time before consecutive API requests.<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>bot_not_found</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Bot with the specified ID does not exist.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>bot_name_already_exists</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Another bot with this name already exists.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>bot_permission_denied</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Insufficient permissions to edit this bot.</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>
      parameters:
        - name: BOT_ID
          in: path
          required: true
          description: |
            Unique numeric identifier of the bot.<br>
            To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#BOT_ID">BOT_ID</a> in the Glossary page.
          schema:
            type: string
            example: b-1901318000009075007
      requestBody:
        description: |
          Updates a bot's configuration. Provide the bot ID in the path and the fields to update in the request body. The <code>unique_name</code> is a permanent identifier auto-assigned by Cliq and cannot be changed, even after updating the display name. For Webhook bots, you can update the <code>execution_url</code> alone to point to a new server endpoint.
        content:
          application/json:
            examples:
              deluge_bot:
                summary: Deluge Bot - update display name and description
                value:
                  name: CRM Bot
                  description: Your CRM co-pilot providing instant access to customer data and insights within Cliq.
                  scope: organization
                  status_messages:
                    - Here to help you with CRM support!
                  channel_participation:
                    - listen_message
                  calls: enabled
              webhook_bot:
                summary: Webhook Bot - update execution URL
                value:
                  execution_url: https://example.com/new-webhook
            schema:
              $ref: '#/components/schemas/BotEdit'
        required: true
      responses:
        '200':
          description: Bot updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotUpdateResponse'
              examples:
                deluge_bot:
                  summary: Deluge Bot - update response
                  value:
                    url: /api/v3/bots/b-53719000002124012
                    type: bot
                    data:
                      unique_name: crmbot
                      name: CRM Bot
                      id: '53719000002124012'
                      description: Your CRM co-pilot providing instant access to customer data and insights within Cliq.
                      scope: organization
                      status_messages:
                        - Here to help you with CRM support!
                      channel_participation:
                        - listen_message
                      calls: enabled
                      handlers:
                        - type: welcome_handler
                      creator:
                        name: James
                        id: '65113112'
                      execution_type: deluge
                      status: enabled
                      type: custom
                      default: false
                      subscriber_count: 1
                webhook_bot:
                  summary: Webhook Bot - execution URL updated response
                  value:
                    url: /api/v3/bots/b-73829000004567890
                    type: bot
                    data:
                      unique_name: cicdbot
                      name: CI/CD Alert Bot
                      id: '73829000004567890'
                      description: Sends real-time CI/CD pipeline alerts and deployment notifications to your team channels.
                      scope: organization
                      execution_url: https://example.com/new-webhook
                      execution_type: webhook
                      status: enabled
                      type: custom
                      default: false
                      subscriber_count: 5
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Bots.UPDATE
      tags:
        - bots
    get:
      summary: Retrieve details of a specific bot
      operationId: get_details_of_a_specific_bot
      description: |
        Retrieves the full configuration and details of a specific bot, including its name, description, unique name, access level, and handler summary.<br>
        Use the <code>fields</code> query parameter to fetch additional details such as subscriber count or handler code.
        <br><br>
        <p>
          <b>Threshold limit</b>: 30 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 5 minutes<br>Wait time before consecutive API requests.<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>bot_not_found</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Bot with the specified 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>
      parameters:
        - name: BOT_ID
          in: path
          required: true
          description: |
            Unique numeric identifier of the bot.<br>
            To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#BOT_ID">BOT_ID</a> in the Glossary page.
          schema:
            type: string
          example: b-1901318000009075007
        - name: fields
          in: query
          description: |
            Additonal field to be fetched in the response. By default, the API returns basic details of the bot along with a summary of its handlers (type and count).
            <br>
            <b>Allowed value</b><br>
            <ul>
              <li>subscription_details - Returns the list of subscribers along with their details like name, email, etc.</li>
            </ul>
          required: false
          schema:
            type: string
          example: subscription_details
      responses:
        '200':
          description: Bot details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotGetResponse'
              example:
                url: /api/v3/bots/b-53719000001878011
                type: bot
                data:
                  unique_name: supportbot
                  name: Support Bot
                  id: '53719000001878011'
                  description: Handles support workflows
                  scope: organization
                  channel_participation:
                    - listen_message
                    - send_message
                    - auto_follow_thread
                  handlers:
                    - type: call_handler
                    - type: welcome_handler
                    - type: context_handler
                    - type: message_handler
                    - type: menu_handler
                      id: '53719000001878017'
                      name: Action
                      icon: wand/627282
                      position: 1
                      sub_actions:
                        - name: Sub Action
                          icon: wand/627282
                  creator:
                    name: James
                    id: '65113112'
                  execution_type: deluge
                  status: enabled
                  type: custom
                  default: false
                  subscriber_count: 1
                  calls: disabled
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Bots.READ
      tags:
        - bots
    delete:
      summary: Delete a specific bot
      operationId: delete_a_specific_bot
      description: |
        Permanently delete a bot and all its associated handlers and configuration. All subscribers will lose access to the bot and any channel associations will be removed. This action is irreversible.
        <br><br>
        <p>
          <b>Threshold limit</b>: 10 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 5 minutes<br>Wait time before consecutive API requests.<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>bot_not_found</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Bot with the specified ID does not exist.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>bot_permission_denied</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Insufficient permissions to delete this bot.</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>
      parameters:
        - name: BOT_ID
          in: path
          required: true
          description: |
            Unique numeric identifier of the bot.
            <b>How to retrieve BOT_ID?</b><br>
            To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#BOT_ID">BOT_ID</a> in the Glossary page.
          schema:
            type: string
            example: BOT_ID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Bots.DELETE
      tags:
        - bots
  /bots/{BOT_UNIQUE_NAME}/message:
    post:
      summary: Send a bot message
      operationId: send_a_bot_message
      description: |
        Send a message from the bot to specific users, a channel, or all subscribers.
        <br><br>
        <p>
          <b>Threshold limit</b>: 50 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<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>botmessage_sending_failed</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Bot message sending failed.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>botmessage_no_valid_users</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">No valid users found for the bot message.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>bot_unauthorized_message_access</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Bot does not have permission to message these users.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>bot_message_forbidden</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Bot message access is forbidden.</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>
      parameters:
        - name: BOT_UNIQUE_NAME
          in: path
          required: true
          description: |
            Unique name of the bot to send the message from.<br>
            To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#BOT_UNIQUE_NAME">BOT_UNIQUE_NAME</a> in the Glossary page.
          schema:
            type: string
            example: zylker_sales
        - name: EXTENSION_KEY
          in: query
          description: Encrypted application key for authentication.
          required: false
          schema:
            type: string
        - name: CHANNEL_UNIQUE_NAME
          in: query
          description: |
            Channel unique name to deliver the bot message.<br>
            To find the unique name of a channel, refer to <a href="/cliq/help/restapi/v3/glossary/#CHANNEL_UNIQUE_NAME">CHANNEL_UNIQUE_NAME</a> in the Glossary page.
          required: false
          schema:
            type: string
        - name: user_ids
          in: query
          description: Comma-separated user IDs to send the message to.
          required: false
          schema:
            type: string
      requestBody:
        description: |
          Message payload. Provide at least one of <code>text</code>, <code>card</code>, or <code>slides</code>.
          Use <code>user_ids</code> or <code>broadcast</code> to control the target recipients - these fields override the equivalent query parameters when both are supplied.
        content:
          application/json:
            examples:
              card_message:
                summary: Modern inline card message to specific users
                value:
                  text: A critical support ticket has been escalated and requires immediate attention.
                  card:
                    theme: modern-inline
                    title: Ticket Escalated - Payment Gateway Timeout
                  slides:
                    - type: table
                      title: Ticket Details
                      data:
                        headers:
                          - Field
                          - Value
                        rows:
                          - Field: Ticket ID
                            Value: '#TKT-00892'
                          - Field: Priority
                            Value: Critical
                          - Field: Reported By
                            Value: olivia.palmer@zylker.com
                          - Field: Open Since
                            Value: 2026-04-16 09:14 AM
                  buttons:
                    - label: Assign to Me
                      action:
                        type: invoke.function
                        data:
                          name: assign_ticket
                    - label: View Ticket
                      action:
                        type: open.url
                        data:
                          web: https://desk.zoho.com/tickets/TKT-00892
                  user_ids: 55743307,55622727
                  notify_edit: false
              thread_message:
                summary: Bot message posted into an existing thread
                value:
                  text: The deployment pipeline for v3.6.1 completed successfully. All health checks passed.
                  thread_chat_id: CT_1207124526552602256_60002085329-T-1291567019566818579
                  post_in_parent: false
                  user_ids: '55743307'
                  sync_message: true
            schema:
              $ref: '#/components/schemas/BotMessage'
        required: true
      responses:
        '200':
          description: Bot message delivered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoResponse'
      security:
        - Cliq_Auth:
            - ZohoCliq.Webhooks.CREATE
      tags:
        - bots
  /bots/{BOT_UNIQUE_NAME}/incoming:
    post:
      summary: Send an incoming webhook message to a bot
      operationId: send_an_incoming_webhook_message
      description: |
        Post a message to a bot using its incoming webhook URL. This endpoint allows external systems to push notifications into Cliq through a bot.
        <br><br>
        <b>Note:</b> Up to 50 additional custom parameters can be passed as query parameters (max 10,000 characters each).
        <br><br>
        <p>
          <b>Threshold limit</b>: 50 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<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>botmessage_sending_failed</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Incoming webhook message delivery failed.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>botmessage_no_valid_users</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">No valid users found for delivery.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>bot_unauthorized_message_access</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Bot does not have permission to message these users.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>bot_message_forbidden</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Bot message access is forbidden.</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>
      parameters:
        - name: BOT_UNIQUE_NAME
          in: path
          required: true
          description: Unique name of the bot. To learn how to retrieve this, see <a href="/cliq/help/restapi/v3/glossary/#BOT_UNIQUE_NAME">BOT_UNIQUE_NAME</a> in the Glossary page.
          schema:
            type: string
            example: zylker_sales
        - name: user_ids
          in: query
          description: |
            Comma-separated user IDs to send the message to.<br>
            <b>Maxium 100 user IDs allowed.</b><br>
            Refer to <a href="/cliq/help/restapi/v3/glossary/#USER_ID">USER_ID</a> in the Glossary page for more details.
          required: false
          schema:
            type: string
        - name: EXTENSION_KEY
          in: query
          description: |
            Encrypted application key for the bot, used as an authentication alternative to OAuth.<br>
            Refer to <a href="/cliq/help/restapi/v3/glossary/#EXTENSION_KEY">EXTENSION_KEY</a> in the Glossary page.'
          required: false
          schema:
            type: string
      requestBody:
        description: |
          Custom parameters to pass to the bot's incoming webhook handler. All fields are user-defined - there are no fixed keys. Each parameter name and value is passed directly to the handler's Deluge script as part of the webhook payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BotIncomingWebhookRequest'
            example:
              alert_type: deployment
              environment: production
              service_name: payment-gateway
              severity: critical
              triggered_by: CI/CD pipeline
        required: true
      responses:
        '200':
          description: Webhook message delivered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotIncomingWebhookResponse'
              example:
                user_ids:
                  - '55743307'
                  - '55622727'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Webhooks.CREATE
            - ZohoCliq.BotMessages.CREATE
      tags:
        - bots
  /bots/{BOT_UNIQUE_NAME}/calls:
    post:
      summary: Trigger Bot Calls
      operationId: Trigger Bot Calls
      description: |
        Utilize this API to send a voice alert to specific users via the bot.
        <br><br>
        <p>
          <b>Threshold limit</b>: 10 requests per 5 min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 30 minutes<br>Wait time before consecutive API requests.<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>bot_alert_not_enabled</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Voice call or alert is not enabled for this bot.</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>
      parameters:
        - name: BOT_UNIQUE_NAME
          in: path
          required: true
          description: Unique identifier of the bot from which bot call needs to be triggered. To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#BOT_UNIQUE_NAME">BOT_UNIQUE_NAME</a> in the Glossary page.
          schema:
            type: string
            example: zylker_sales
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Trigger-Bot-Call-Request'
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bot-call-response'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Webhooks.CREATE
  /bots/{BOT_ID}/handlers:
    post:
      summary: Create a handler for a specific bot
      operationId: create_a_handler_for_a_bot
      description: |
        <a id="create_a_handler_for_a_bot"></a>
        <p>
          Create a handler for a specific bot by providing the handler type and the execution logic for that event.<br>
          Handlers define the bot's behavior for different trigger events. Refer <b><a href="https://www.zoho.com/cliq/help/platform/bots.html">introduction to bot handlers</a></b> in the documentation for more details on each handler type and when it is triggered.
        </p>
        <p>
          The way you define a handler depends on the bot's execution type:
        </p>
        <ul>
          <li><b>Deluge bot</b>: Provide the <code>script</code> attribute containing the Deluge source code to execute when the handler fires.</li>
          <li><b>Webhook bot</b>: Provide the <code>permissions</code> attribute - an array of data attributes that your external server needs to receive in the webhook payload when the handler is triggered. These define what contextual information Zoho Cliq includes in the POST request sent to your <code>execution_url</code>.</li>
        </ul>
        <p><b>Webhook Bots - Using <code>permissions</code></b></p>
        <p>
          For <b>Webhook bots</b>, the <code>permissions</code> array controls what contextual data Zoho Cliq appends to the POST request sent to your server when a handler fires. Only include permissions that are relevant to your server's logic.<br>
          <b>Maximum:</b> 5 permissions per handler.
        </p>
        <p><b>Allowed values for <code>permissions</code></b></p>
        <table style="border-collapse: collapse; width: 100%; font-family: inherit;">
          <tr>
            <th style="padding: 8px; text-align: left; border: 1px solid #ddd; font-family: inherit;">Permission</th>
            <th style="padding: 8px; text-align: left; border: 1px solid #ddd; font-family: inherit;">Data provided to your webhook</th>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd;"><code>chat</code></td>
            <td style="padding: 8px; border: 1px solid #ddd;">Chat context (chat ID, type, participants)</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd;"><code>message</code></td>
            <td style="padding: 8px; border: 1px solid #ddd;">Message content and metadata</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd;"><code>user</code></td>
            <td style="padding: 8px; border: 1px solid #ddd;">Sender's user profile details</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd;"><code>location</code></td>
            <td style="padding: 8px; border: 1px solid #ddd;">Sender's location data</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd;"><code>attachments</code></td>
            <td style="padding: 8px; border: 1px solid #ddd;">Attachment metadata and download info</td>
          </tr>
        </table>
        <p>
          <b>Permissions availability per handler type</b><br>
          Not all permissions are applicable to every handler. Passing a permission marked <code>-</code> will result in a validation error.
        </p>
        <table style="border-collapse: collapse; width: 100%; font-family: inherit;">
          <tr>
            <th style="padding: 8px; text-align: left; border: 1px solid #ddd; font-family: inherit;">Handler</th>
            <th style="padding: 8px; text-align: center; border: 1px solid #ddd; font-family: inherit;"><code>attachments</code></th>
            <th style="padding: 8px; text-align: center; border: 1px solid #ddd; font-family: inherit;"><code>chat</code></th>
            <th style="padding: 8px; text-align: center; border: 1px solid #ddd; font-family: inherit;"><code>location</code></th>
            <th style="padding: 8px; text-align: center; border: 1px solid #ddd; font-family: inherit;"><code>message</code></th>
            <th style="padding: 8px; text-align: center; border: 1px solid #ddd; font-family: inherit;"><code>user</code></th>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd;"><code>welcome_handler</code></td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd;"><code>message_handler</code></td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd;"><code>mention_handler</code></td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd;"><code>context_handler</code></td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd;"><code>incoming_webhook_handler</code></td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd;"><code>participation_handler</code></td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd;"><code>menu_handler</code></td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">✓</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd;"><code>alert_handler</code></td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">-</td>
            <td style="padding: 8px; text-align: center; border: 1px solid #ddd;">&#10003;</td>
          </tr>
        </table>
        <p><b>Bot Menu Actions (<code>menu_handler</code>)</b></p>
        <p>
          Both Deluge and Webhook bots support menu handlers, which add quick-action items to the bot's chat menu. When creating a <code>menu_handler</code>, two additional fields apply regardless of execution type:
        </p>
        <ul>
          <li><code>name</code> (required): Label shown in the menu. Max 15 characters.</li>
          <li><code>icon</code> (optional): Icon in <code>{icon-name}/{HEX_COLOR}</code> format. Example: <code>wand/FF5733</code>.</li>
        </ul>
        <p>
          <b>Threshold limit</b>: 10 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 5 minutes<br>
          Wait time before consecutive API requests.
        </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>execution_handler_create_failed</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Failed to create the execution handler.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>execution_handler_data_required</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Required handler data is missing.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>execution_handler_data_invalid</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Provided handler data is invalid.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>invalid_inputs</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Invalid handler type or malformed request body.</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>
      parameters:
        - name: BOT_ID
          in: path
          required: true
          description: Unique numeric identifier of the bot. To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#BOT_ID">BOT_ID</a> in the Glossary page.
          schema:
            type: string
            example: BOT_ID
      requestBody:
        description: |
          Creates a bot handler. The required fields differ by bot execution type:<br>
          <ul>
            <li><b>Deluge bots</b>: Provide <code>type</code> and <code>script</code> - the Deluge source code to execute when the handler fires.</li>
            <li><b>Webhook bots</b>: Provide <code>type</code> and <code>permissions</code> - an array of data attributes that your external server needs to receive in the webhook payload. Do not pass <code>script</code>.</li>
          </ul>
          For <code>menu_handler</code>, also include <code>name</code> (required) and optionally <code>icon</code>, regardless of execution type.
        content:
          application/json:
            examples:
              message_handler_webhook:
                summary: Message Handler (Webhook bot) - forward chat and user context
                value:
                  type: message_handler
                  permissions:
                    - chat
                    - user
              message_handler_deluge:
                summary: Message Handler (Deluge bot) - intent-based support reply
                value:
                  type: message_handler
                  script: |-
                    response = Map();
                    userMessage = message.get("text").toLowerCase();
                    if(userMessage.contains("ticket")) {
                      response.put("text", "Sure! Please provide a brief description of your issue and I'll raise a ticket right away.");
                    } else if(userMessage.contains("status")) {
                      response.put("text", "Current system status:\n\u2705 API: Operational\n\u2705 Database: Operational\n\u26a0\ufe0f Notifications: Degraded");
                    } else {
                      response.put("text", "I didn't catch that. You can ask me about *status* or type *ticket* to raise a support request.");
                    }
                    return response;
              menu_handler_webhook:
                summary: Menu Handler (Webhook bot) - forward chat and message context
                value:
                  type: menu_handler
                  name: My Menu
                  icon: emoji-name/FF5733
                  permissions:
                    - chat
                    - message
              menu_handler_deluge:
                summary: Menu Handler (Deluge bot) - prompt card to create a support ticket
                value:
                  type: menu_handler
                  name: My Menu
                  icon: emoji-name/FF5733
                  script: |-
                    response = Map();
                    card = Map();
                    card.put("theme", "prompt");
                    card.put("title", "Create a new support ticket for this conversation?");
                    confirmBtn = Map();
                    confirmBtn.put("label", "Create Ticket");
                    confirmAction = Map();
                    confirmAction.put("type", "invoke.function");
                    confirmActionData = Map();
                    confirmActionData.put("name", "create_ticket");
                    confirmAction.put("data", confirmActionData);
                    confirmBtn.put("action", confirmAction);
                    cancelBtn = Map();
                    cancelBtn.put("label", "Cancel");
                    cancelAction = Map();
                    cancelAction.put("type", "invoke.function");
                    cancelActionData = Map();
                    cancelActionData.put("name", "cancel_action");
                    cancelAction.put("data", cancelActionData);
                    cancelBtn.put("action", cancelAction);
                    response.put("card", card);
                    response.put("buttons", {confirmBtn, cancelBtn});
                    return response;
            schema:
              $ref: '#/components/schemas/HandlerCreate'
        required: true
      responses:
        '200':
          description: Bot handler created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotHandlerCreateResponse'
              examples:
                message_handler_webhook:
                  summary: Message Handler (Webhook bot) response
                  value:
                    url: /api/v3/bots/b-53719000001878011/handlers/message_handler
                    type: execution_handler
                    data:
                      type: message_handler
                      id: '53719000001878022'
                      permissions:
                        - chat
                        - user
                message_handler_deluge:
                  summary: Message Handler (Deluge bot) response
                  value:
                    url: /api/v3/bots/b-53719000001878011/handlers/message_handler
                    type: execution_handler
                    data:
                      type: message_handler
                      id: '53719000001878022'
                menu_handler_webhook:
                  summary: Menu Handler (Webhook bot) response
                  value:
                    url: /api/v3/bots/b-53719000001878011/handlers/menu_handler
                    type: execution_handler
                    data:
                      type: menu_handler
                      id: '53719000001878027'
                      display_props:
                        name: My Menu
                        icon: emoji-name/FF5733
                        position: 1
                      permissions:
                        - chat
                        - message
                menu_handler_deluge:
                  summary: Menu Handler (Deluge bot) response
                  value:
                    url: /api/v3/bots/b-53719000001878011/handlers/menu_handler
                    type: execution_handler
                    data:
                      type: menu_handler
                      id: '53719000001878027'
                      display_props:
                        name: My Menu
                        icon: emoji-name/FF5733
                        position: 1
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Bots.UPDATE
      tags:
        - bots
  /bots/{BOT_ID}/handlers/{HANDLER_TYPE}:
    patch:
      summary: Update a handler for a specific bot
      operationId: update_a_handler_for_a_bot
      description: |
        <p>
          Update a handler for a specific bot by providing the handler type and the revised execution logic or configuration to apply for that event.<br>
          Handlers define the bot's behavior for different trigger events. Refer <b><a href="https://www.zoho.com/cliq/help/platform/bots.html">introduction to bot handlers</a></b> in the documentation for more details on each handler type and when it is triggered.
        </p>
        <p>
          What you can update depends on the bot's execution type:
        </p>
        <ul>
          <li><b>Deluge bot</b>: Update the <code>script</code> attribute with the revised Deluge source code to execute when the handler fires.</li>
          <li><b>Webhook bot</b>: Update the <code>permissions</code> attribute - the array of data attributes your external server needs to receive in the webhook payload. This replaces the existing permissions for the handler.</li>
          <li><b>Menu handler (both types)</b>: Update the <code>name</code> and/or <code>icon</code> display properties. Use the optional <code>handler_id</code> query parameter to target a specific variant of a multi-variant menu handler.</li>
        </ul>
        <p>
          <b>Threshold limit</b>: 10 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 5 minutes<br>
          Wait time before consecutive API requests.
        </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>execution_handler_update_failed</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Failed to update the execution handler.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>execution_handler_not_found</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Specified handler was not found for this bot.</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>
      parameters:
        - name: BOT_ID
          in: path
          required: true
          description: Unique numeric identifier of the bot. To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#BOT_ID">BOT_ID</a> in the Glossary page.
          schema:
            type: string
          example: '53719000001878011'
        - name: HANDLER_TYPE
          in: path
          required: true
          description: |
            Type of the handler to be updated. Determines the event or trigger that will use the revised handler script or configuration.<br>
            <b>Allowed values</b>:
            <ul>
              <li><code>welcome_handler</code>: Executes when a user subscribes to the bot.</li>
              <li><code>message_handler</code>: Executes when the bot receives a message.</li>
              <li><code>mention_handler</code>: Executes when the bot is mentioned in a message.</li>
              <li><code>context_handler</code>: Executes based on specific contextual triggers defined by the bot.</li>
              <li><code>participation_handler</code>: Executes when the bot is added to or removed from a channel.</li>
              <li><code>incoming_webhook_handler</code>: Executes when a message is received via an incoming webhook.</li>
              <li><code>menu_handler</code>: Executes when a user interacts with a menu action associated with the bot.</li>
              
              <li><code>call_handler</code>: Executes on bot call state events (e.g., ringing, answered, ended).</li>
            </ul>
          schema:
            type: string
            enum:
              - message_handler
              - mention_handler
              - welcome_handler
              - context_handler
              - participation_handler
              - incoming_webhook_handler
              - menu_handler
              - call_handler
          example: menu_handler
        - name: handler_id
          in: query
          description: ID of the handler. Used for menu handler alone, to target a specific variant of a multi-variant menu handler.
          required: false
          schema:
            type: integer
          example: 1901318000009075000
      requestBody:
        description: |
          Updates a bot handler. What you provide depends on the bot's execution type and what you want to change:<br>
          <ul>
            <li><b>Deluge bot</b>: Provide <code>script</code> with the revised Deluge source code.</li>
            <li><b>Webhook bot</b>: Provide <code>permissions</code> with the updated array of data attributes to forward in the webhook payload.</li>
            <li><b>Menu handler</b>: Provide <code>name</code> and/or <code>icon</code> to update the menu action display properties.</li>
          </ul>
        content:
          application/json:
            examples:
              update_script_deluge:
                summary: Update script (Deluge bot)
                value:
                  script: |-
                    response = Map();
                    response.put("text", "Updated");
                    return response;
              update_permissions_webhook:
                summary: Update permissions (Webhook bot)
                value:
                  permissions:
                    - chat
                    - user
                    - message
              update_menu_handler:
                summary: Update menu handler display properties
                value:
                  name: Updated Menu
                  icon: emoji-name/FF5733
            schema:
              $ref: '#/components/schemas/HandlerEdit'
        required: true
      responses:
        '200':
          description: Bot handler updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotHandlerResponse'
              examples:
                update_script_deluge:
                  summary: Update script (Deluge bot) response
                  value:
                    url: /api/v3/bots/b-53719000001878011/handlers/message_handler
                    type: execution_handler
                    data:
                      type: message_handler
                      id: '53719000001878022'
                update_permissions_webhook:
                  summary: Update permissions (Webhook bot) response
                  value:
                    url: /api/v3/bots/b-53719000001878011/handlers/message_handler
                    type: execution_handler
                    data:
                      type: message_handler
                      id: '53719000001878022'
                      permissions:
                        - chat
                        - user
                        - message
                update_menu_handler:
                  summary: Update menu handler display properties response
                  value:
                    url: /api/v3/bots/b-53719000001878011/handlers/menu_handler
                    type: execution_handler
                    data:
                      type: menu_handler
                      id: '53719000001878027'
                      display_props:
                        name: Updated Menu
                        icon: emoji-name/FF5733
                        position: 1
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Bots.UPDATE
      tags:
        - bots
    get:
      summary: Get details of a specific bot handler
      operationId: get_details_of_a_specific_bot_handler
      description: |
        Retrieve the details and configuration of a specific handler for a bot, including the Deluge source code and any associated menu action configuration. 
        <br><br>
        <p>
          <b>Threshold limit</b>: 10 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 5 minutes<br>Wait time before consecutive API requests.<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>execution_handler_get_failed</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Failed to fetch the execution handler.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>execution_handler_not_found</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Specified handler was not found for this bot.</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>
      parameters:
        - name: BOT_ID
          in: path
          required: true
          description: Unique numeric identifier of the bot. To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#BOT_ID">BOT_ID</a> in the Glossary page.
          schema:
            type: string
            example: BOT_ID
        - name: HANDLER_TYPE
          in: path
          required: true
          description: |
            Type of the handler to fetch details for. Determines the event or trigger associated with the handler script.<br>
            <b>Allowed values</b>:
            <ul>
              <li><code>welcome_handler</code>: Executes when a user subscribes to the bot.</li>
              <li><code>message_handler</code>: Executes when the bot receives a message.</li>
              <li><code>mention_handler</code>: Executes when the bot is mentioned in a message.</li>
              <li><code>context_handler</code>: Executes based on specific contextual triggers defined by the bot.</li>
              <li><code>participation_handler</code>: Executes when the bot is added to or removed from a channel.</li>
              <li><code>incoming_webhook_handler</code>: Executes when a message is received via an incoming webhook.</li>
              <li><code>menu_handler</code>: Executes when a user interacts with a menu action associated with the bot.</li>
              
              <li><code>call_handler</code>: Executes on bot call state events (e.g., ringing, answered, ended).</li>
            </ul>
          schema:
            type: string
            enum:
              - message_handler
              - mention_handler
              - welcome_handler
              - context_handler
              - participation_handler
              - incoming_webhook_handler
              - menu_handler
              - call_handler
          example: message_handler
        - name: handler_id
          in: query
          description: ID of the handler. Used for menu handler alone, to target a specific variant of a multi-variant menu handler.
          required: false
          schema:
            type: integer
          example: 1901318000009075000
      responses:
        '200':
          description: Bot handler details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotHandlerDetailsResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Bots.READ
      tags:
        - bots
    delete:
      summary: Delete a handler from a specific bot
      operationId: delete_a_handler_from_a_bot
      description: |
        Permanently remove a handler from a bot. Once deleted, the associated Deluge code and configuration are lost and the handler will no longer respond to its trigger event.
        <br><br>
        <p>
          <b>Threshold limit</b>: 10 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 5 minutes<br>Wait time before consecutive API requests.<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>execution_handler_delete_failed</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Failed to delete the execution handler.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>default_handler_delete_not_allowed</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Default handlers cannot be deleted.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>execution_handler_not_found</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Specified handler was not found for this bot.</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>
      parameters:
        - name: BOT_ID
          in: path
          required: true
          description: Unique numeric identifier of the bot. To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#BOT_ID">BOT_ID</a> in the Glossary page.
          schema:
            type: string
            example: BOT_ID
        - name: HANDLER_TYPE
          in: path
          required: true
          description: |
            Type of the handler to be deleted. Determines the event or trigger associated with the handler script.<br>
            <b>Allowed values</b>:
            <ul>
              <li><code>welcome_handler</code>: Executes when a user subscribes to the bot.</li>
              <li><code>message_handler</code>: Executes when the bot receives a message.</li>
              <li><code>mention_handler</code>: Executes when the bot is mentioned in a message.</li>
              <li><code>context_handler</code>: Executes based on specific contextual triggers defined by the bot.</li>
              <li><code>participation_handler</code>: Executes when the bot is added to or removed from a channel.</li>
              <li><code>incoming_webhook_handler</code>: Executes when a message is received via an incoming webhook.</li>
              <li><code>menu_handler</code>: Executes when a user interacts with a menu action associated with the bot.</li>
              
              <li><code>call_handler</code>: Executes on bot call state events (e.g., ringing, answered, ended).</li>
            </ul>
          schema:
            type: string
            enum:
              - message_handler
              - mention_handler
              - welcome_handler
              - context_handler
              - participation_handler
              - incoming_webhook_handler
              - menu_handler
              - call_handler
          example: message_handler
        - name: handler_id
          in: query
          description: ID of the handler. Used for menu handler alone, to target a specific variant of a multi-variant menu handler.
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Handler deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Bots.UPDATE
      tags:
        - bots
  /bots/{BOT_UNIQUE_NAME}/associate:
    post:
      summary: Associate bot to a channel
      operationId: associate_bot_to_channel
      description: |
        Add a bot to a specific channel by providing the bot's unique name and the target channel ID. Once associated, the bot can interact with users in that channel based on its configured handlers and permissions.
        <br><br>
        <p>
          <b>Threshold limit</b>: 5 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 5 minutes<br>Wait time before consecutive API requests.<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>bot_not_found</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Bot with the specified ID or unique name does not exist.</td>
          </tr>
          <tr>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;"><code>bot_already_member</code></td>
            <td style="padding: 8px; border: 1px solid #ddd; word-break: break-word; white-space: normal;">Bot is already a member of the target channel.</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>
      parameters:
        - name: BOT_UNIQUE_NAME
          in: path
          required: true
          description: Unique name of the bot. To learn how to retrieve this, see <a href="/cliq/help/restapi/v3/glossary/#BOT_UNIQUE_NAME">BOT_UNIQUE_NAME</a> in the Glossary page.
          schema:
            type: string
          example: supportbot
        - name: EXTENSION_KEY
          in: query
          description: |
            Encrypted application key for authentication. Required if the bot belongs to an extension. For bots created within the organization, this parameter is not needed.
            <br>To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#EXTENSION_KEY">EXTENSION_KEY</a> in the Glossary page.
          required: false
          schema:
            type: string
      requestBody:
        description: Channel association payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BotAssociateChannelRequest'
        required: true
      responses:
        '200':
          description: Bot successfully associated to channel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoResponse'
      security:
        - Cliq_Auth:
            - ZohoCliq.Channels.UPDATE
      tags:
        - bots
  /bots/{BOT_ID_OR_UNIQUE_NAME}/subscribers:
    get:
      summary: List all subscribers of a specific bot
      operationId: list_all_subscribers_of_a_bot
      description: |
        Retrieve a paginated list of users who have subscribed to a specific bot, identified by its bot ID or unique bot name. Access to bot subscribers is limited to the bot creator or the administrator of the organization.<br><br>
        Use <b>limit</b> and <b>next_token</b> for cursor-based pagination. Use <b>sync_token</b> for incremental sync to receive only changes since the last request. 
        <br><br>
        <p>
          <b>Threshold limit</b>: 100 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 5 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      parameters:
        - name: BOT_ID_OR_UNIQUE_NAME
          in: path
          required: true
          description: |
            Either the numeric bot ID (e.g. <code>b-1901318000009075007</code>) or the bot's unique name (e.g. <code>supportbot</code>).<br>
            To learn more, see <a href="/cliq/help/restapi/v3/glossary/#BOT_ID">BOT_ID</a> or <a href="/cliq/help/restapi/v3/glossary/#BOT_UNIQUE_NAME">BOT_UNIQUE_NAME</a> in the Glossary page.
          schema:
            type: string
            example: zylker_sales
        - name: limit
          in: query
          description: Maximum number of subscribers to return.
          required: false
          schema:
            type: integer
        - name: next_token
          in: query
          description: Pagination token to fetch the next set of subscribers.
          required: false
          schema:
            type: string
        - name: sync_token
          in: query
          description: Token to fetch only the subscribers who were added or updated after the previous request was made.
          required: false
          schema:
            type: string
        - name: EXTENSION_KEY
          in: query
          description: |
            Encrypted application key for authentication. Required if the bot belongs to an extension. For bots created within the organization, this parameter is not needed.
            <br>To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#EXTENSION_KEY">EXTENSION_KEY</a> in the Glossary page.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Bot subscriber list returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotSubscribersResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Bots.READ
      tags:
        - bots
components:
  schemas:
    BotIncomingWebhookRequest:
      type: object
      description: |
        Request body for the incoming webhook endpoint. Accepts any number of custom key-value parameters that are passed directly to the bot's <code>incoming_webhook_handler</code> Deluge script. Up to 50 additional parameters are supported, each with a maximum value length of 10,000 characters. There are no fixed or required fields.
      properties:
        custom_parameters:
          type: object
          description: |
            Pass additional key-value pairs in the request body to provide context to the bot's handler. These parameters are user-defined and can carry any metadata relevant to your integration.
            <br><br>
            <b>Rules for Custom Parameters</b>
            <ul>
              <li>Up to 50 custom parameters are supported per request.</li>
              <li>Each parameter value can be up to 10,000 characters.</li>
              <li>All values must be of type string.</li>
              <li>Parameter keys should be unique to avoid overwriting values in the bot handler.</li>
            </ul>
            <b>Common Use Cases</b>
            <ul>
              <li>Webhook Verification: Some platforms send a challenge_key during webhook registration to confirm that the endpoint is reachable. Your bot handler should echo it back in the response to complete the handshake.</li>
              <li>CI/CD & Monitoring:  Pass parameters like alert_type, build_status, or environment to notify teams about pipeline failures or infrastructure incidents in real time.</li>
              <li>CRM & E-commerce: Send deal updates, order status changes, and customer activity metadata to keep sales and support teams informed without manual intervention.</li>
            </ul>
      additionalProperties:
        type: string
      example:
        alert_type: deployment
        environment: production
        service_name: payment-gateway
        severity: critical
        triggered_by: CI/CD pipeline
    BotIncomingWebhookResponse:
      type: object
      description: Response returned after a successful incoming webhook message delivery. Contains the list of user IDs that received the message.
      properties:
        user_ids:
          type: array
          description: List of user IDs to whom the bot message was successfully delivered.
          items:
            type: string
          example:
            - '55743307'
            - '55622727'
      example:
        user_ids:
          - '55743307'
          - '55622727'
    NoResponse:
      type: object
      description: Represents an empty successful response where no payload is returned.
      properties:
        Response Code:
          type: string
          description: HTTP response code indicating no content is returned.
          example: 204 No response
    BotGetResponse:
      type: object
      description: Response returned when retrieving the details of a specific bot.
      properties:
        url:
          type: string
          description: API endpoint URL for the retrieved bot resource.
          example: /api/v3/bots/b-53719000001878011
        type:
          type: string
          description: Resource type.
          example: bot
        data:
          type: object
          description: Full configuration and details of the bot.
          properties:
            unique_name:
              type: string
              description: Unique identifier of the bot.
              example: supportbot
            name:
              type: string
              description: Display name of the bot.
              example: Support Bot
            id:
              type: string
              description: Numeric ID of the bot.
              example: '53719000001878011'
            description:
              type: string
              description: Description of the bot.
              example: Handles support workflows
            scope:
              type: string
              description: Access level of the bot.
              example: organization
            channel_participation:
              type: array
              description: Channel interaction capabilities of the bot.
              items:
                type: string
              example:
                - listen_message
                - send_message
                - auto_follow_thread
            handlers:
              type: array
              description: Handlers configured for the bot.
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: Handler type.
                    example: menu_handler
                  id:
                    type: string
                    description: Unique ID of the handler (present for menu_handler).
                    example: '53719000001878017'
                  name:
                    type: string
                    description: Display name of the menu action (present for menu_handler).
                    example: Action
                  icon:
                    type: string
                    description: Icon reference for the menu action (present for menu_handler).
                    example: wand/627282
                  position:
                    type: integer
                    description: Display position of the menu action (present for menu_handler).
                    example: 1
                  sub_actions:
                    type: array
                    description: Sub-actions under the menu handler.
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: Sub Action
                        icon:
                          type: string
                          example: wand/627282
            creator:
              type: object
              description: User who created the bot.
              properties:
                name:
                  type: string
                  description: Name of the creator.
                  example: James
                id:
                  type: string
                  description: ZUID of the creator.
                  example: '65113112'
            execution_type:
              type: string
              description: Script execution engine used by the bot.
              example: deluge
            status:
              type: string
              description: Current operational status of the bot.
              example: enabled
            type:
              type: string
              description: Bot category. Always custom for user-created bots.
              example: custom
            default:
              type: boolean
              description: Indicates whether this is the default bot.
              example: false
            subscriber_count:
              type: integer
              description: Number of users subscribed to the bot.
              example: 1
            calls:
              type: string
              description: Indicates whether bot calls are enabled or disabled.
              example: disabled
    BotCreateResponse:
      type: object
      description: Response returned after successfully creating a bot.
      properties:
        url:
          type: string
          description: API endpoint URL for the created bot resource.
          example: /api/v3/bots
        type:
          type: string
          description: Resource type.
          example: bot
        data:
          type: object
          description: The created bot object.
          properties:
            unique_name:
              type: string
              description: System-generated unique identifier for the bot (derived from name, cannot be changed).
              example: clientcarebot
            name:
              type: string
              description: Display name of the bot as provided in the request.
              example: Clientcare Bot
            id:
              type: string
              description: Unique numeric ID assigned to the bot.
              example: '53719000002124012'
            description:
              type: string
              description: Description of the bot as provided in the request.
              example: Your client care co-pilot streamlining support by providing instant customer context and easy access to critical resources.
            scope:
              type: string
              description: Access level of the bot as provided in the request.
              example: team
            team_ids:
              type: array
              description: Team IDs mapped to the bot (present when scope is team).
              items:
                type: integer
              example:
                - 12345678
            status_messages:
              type: array
              description: Status messages assigned to the bot.
              items:
                type: string
              example:
                - Here to help you with client support!
            channel_participation:
              type: array
              description: Channel interaction capabilities of the bot.
              items:
                type: string
              example:
                - send_message
            calls:
              type: string
              description: Indicates whether bot calls are enabled or disabled.
              example: enable
            handlers:
              type: array
              description: List of handlers configured for the bot. Empty at creation time.
              items:
                type: object
            creator:
              type: object
              description: Details of the user who created the bot.
              properties:
                name:
                  type: string
                  description: Name of the creator.
                  example: James
                id:
                  type: string
                  description: ZUID of the creator.
                  example: '65113112'
            execution_type:
              type: string
              description: Script execution engine used by the bot.
              example: deluge
            status:
              type: string
              description: Current operational status of the bot.
              example: enabled
            type:
              type: string
              description: Bot category. Always custom for user-created bots.
              example: custom
            default:
              type: boolean
              description: Indicates whether this is the default bot for the organization.
              example: false
            subscriber_count:
              type: integer
              description: Number of users subscribed to the bot.
              example: 1
    GenericResponse:
      type: object
      description: Generic successful response envelope used for bot APIs where detailed payload schema varies.
      properties:
        url:
          type: string
          description: Endpoint URL associated with the response.
        type:
          type: string
          description: Resource type returned by the API.
        data:
          type: object
          description: Resource payload.
          additionalProperties: true
      additionalProperties: true
    BotListResponse:
      type: object
      description: Response schema for listing bots.
      properties:
        url:
          type: string
          description: API endpoint URL for the listed resources.
          example: /api/v3/bots
        type:
          type: string
          description: Resource type.
          example: bot
        next_token:
          type: string
          description: Pagination token to fetch the next page of results.
          example: NTB8MTc1NjM2MjA5MzQ5OHw1MzcxOTAwMDAwMTYyMDAwMw==
        sync_token:
          type: string
          description: Token used for incremental synchronization to fetch changes since the last sync.
          example: NTB8MTc3NzM0MjEyNzQ3OHw1MzcxOTAwMDAwMTg3ODAxMQ==
        deleted:
          type: array
          description: IDs of deleted bots returned during incremental sync.
          items:
            type: string
        data:
          type: array
          description: List of bot objects.
          items:
            type: object
            properties:
              unique_name:
                type: string
                description: Unique identifier of the bot.
                example: supportbot
              name:
                type: string
                description: Display name of the bot.
                example: Support Bot
              id:
                type: string
                description: Numeric ID of the bot.
                example: '53719000001878011'
              description:
                type: string
                description: Description of the bot.
                example: Handles support workflows
              scope:
                type: string
                description: Access level of the bot.
                example: organization
              channel_participation:
                type: array
                description: Channel interaction capabilities of the bot.
                items:
                  type: string
                example:
                  - listen_message
                  - send_message
                  - auto_follow_thread
              handlers:
                type: array
                description: Handlers configured for the bot.
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      description: Handler type.
                      example: menu_handler
                    id:
                      type: string
                      description: Unique ID of the handler (present for menu_handler).
                      example: '53719000001878017'
                    name:
                      type: string
                      description: Display name of the menu action (present for menu_handler).
                      example: Action
                    icon:
                      type: string
                      description: Icon reference for the menu action (present for menu_handler).
                      example: wand/627282
                    position:
                      type: integer
                      description: Display position of the menu action (present for menu_handler).
                      example: 1
                    sub_actions:
                      type: array
                      description: Sub-actions under the menu handler.
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            example: Sub Action
                          icon:
                            type: string
                            example: wand/627282
              creator:
                type: object
                description: User who created the bot.
                properties:
                  name:
                    type: string
                    description: Name of the creator.
                    example: James
                  id:
                    type: string
                    description: ZUID of the creator.
                    example: '65113112'
              execution_type:
                type: string
                description: Script execution engine used by the bot.
                example: deluge
              status:
                type: string
                description: Current operational status of the bot.
                example: enabled
              type:
                type: string
                description: Bot category. Always custom for user-created bots.
                example: custom
              default:
                type: boolean
                description: Indicates whether this is the default bot.
                example: false
              subscriber_count:
                type: integer
                description: Number of users subscribed to the bot.
                example: 1
              calls:
                type: string
                description: Indicates whether bot calls are enabled or disabled.
                example: disabled
    BotHandlerCreateResponse:
      type: object
      description: Response schema returned when a new bot handler is created successfully.
      properties:
        url:
          type: string
          description: Endpoint URL of the newly created handler resource.
        type:
          type: string
          description: Resource type identifier.
          example: execution_handler
        data:
          type: object
          description: Configuration details of the created handler.
          properties:
            script:
              type: string
              description: Deluge source code of the handler.
            return_type:
              type: string
              description: Return type expected from the handler script.
              example: MAP
            params:
              type: array
              description: List of runtime parameters passed to the handler script.
              items:
                type: object
                properties:
                  param_name:
                    type: string
                    description: Name of the parameter.
                  param_type:
                    type: string
                    description: Data type of the parameter (e.g., MAP, STRING, BOOLEAN).
          additionalProperties: true
      example:
        url: /api/v3/bots/b-53719000001887001/handlers
        type: execution_handler
        data:
          script: |-
            response = Map();
            response.put("text", "Welcome! I'm your assistant bot. Send me a message to get started.");
            return response;
          return_type: MAP
          params:
            - param_name: access
              param_type: MAP
            - param_name: environment
              param_type: MAP
            - param_name: user
              param_type: MAP
            - param_name: newuser
              param_type: BOOLEAN
    BotHandlerDetailsResponse:
      type: object
      description: Response schema returned when fetching the full details of a specific bot handler.
      properties:
        url:
          type: string
          description: Endpoint URL of the handler resource.
        type:
          type: string
          description: Resource type identifier.
          example: execution_handler
        data:
          type: object
          description: Full configuration and metadata of the handler.
          properties:
            script:
              type: string
              description: Deluge source code of the handler.
            handler_id:
              type: string
              description: Unique identifier of the handler.
            name:
              type: string
              description: Display name of the handler (used for menu-type handlers).
            type:
              type: string
              description: Type of the handler.
              enum:
                - welcome_handler
                - message_handler
                - mention_handler
                - context_handler
                - participation_handler
                - incoming_webhook_handler
                - menu_handler
                - call_handler
            icon:
              type: string
              description: Icon reference for the handler, applicable for menu handlers.
            return_type:
              type: string
              description: Return type expected from the handler script.
              example: MAP
            params:
              type: array
              description: List of parameters passed to the handler script at runtime.
              items:
                type: object
                properties:
                  param_name:
                    type: string
                    description: Name of the parameter.
                  param_type:
                    type: string
                    description: Data type of the parameter (e.g., MAP, STRING).
          additionalProperties: true
      example:
        url: /api/v3/bots/b-53719000001887001/handlers/menu_handler
        type: execution_handler
        data:
          script: |-
            response = Map();
            response.put("text", "👋 Hi! Choose an option below to get started with the IT Help Desk bot.");
            return response;
          handler_id: '53719000002155003'
          name: IT Help Desk
          type: menu_handler
          icon: wand/627282
          return_type: MAP
          params:
            - param_name: access
              param_type: MAP
            - param_name: environment
              param_type: MAP
            - param_name: chat
              param_type: MAP
            - param_name: user
              param_type: MAP
            - param_name: location
              param_type: MAP
            - param_name: sub_action
              param_type: STRING
    BotHandlerResponse:
      type: object
      description: Response schema for bot handler create, update, and fetch operations.
      properties:
        url:
          type: string
          description: Endpoint URL for the handler resource.
        type:
          type: string
          description: Resource type.
          example: execution_handler
        data:
          type: object
          description: Handler payload.
          additionalProperties: true
      example:
        url: /api/v3/bots/b-4000000010001/handlers/menu
        type: execution_handler
        data:
          display_props:
            position: 2
            name: a123
            icon: wand/627282
          id: '53719000001973033'
    BotHandlerLogsResponse:
      type: object
      description: Response schema for bot handler execution logs.
      properties:
        url:
          type: string
          description: Endpoint URL for the execution log resource.
        type:
          type: string
          description: Resource type.
          example: execution_handler
        data:
          type: object
          properties:
            logs:
              type: array
              description: Execution logs containing debug information.
              items:
                type: object
                properties:
                  debugInfo:
                    type: array
                    description: Debug information entries as serialized JSON strings.
                    items:
                      type: string
                      description: Serialized JSON string containing debug trace information with timestamp and message details.
                additionalProperties: true
          additionalProperties: true
      example:
        url: /api/v3/commands/4000000011005/handlers/welcome/logs
        type: execution_handler
        data:
          logs:
            - debugInfo:
                - '{"time":1772868058306,"message":{"mentions":[],"text":"asf","type":"text","content":{"text":"asf"}}}'
    ErrorResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
    BotSubscribersResponse:
      type: object
      description: Represents the response structure for fetching subscribers of a specific bot. Contains metadata and a list of subscriber details.
      properties:
        url:
          type: string
          description: The API endpoint URL to retrieve the list of subscribers for the specified bot.
          example: /api/v3/bots/{BOT_UNIQUE_NAME}/subscribers
        type:
          type: string
          description: The type of the response object. Typically indicates the resource or entity being described.
          example: bot_subscriber
        sync_token:
          type: string
          description: A token used to synchronize and track the state of the subscribers list across requests.
          example: NTB8MTcyMjcwMDXwxNzIyNzA5MzQ0NDM5
        data:
          type: array
          description: An array containing subscriber details associated with the bot.
          items:
            $ref: '#/components/schemas/BotSubscriber'
    BotSubscriber:
      type: object
      description: Detailed information about an individual subscriber of the bot.
      properties:
        email_id:
          type: string
          description: The email address of the subscriber, used for identification and communication.
          example: scott.fisher@zylker.com
        user_id:
          type: string
          description: A unique identifier assigned to the subscriber within the system.
          example: '19183988'
        name:
          type: string
          description: The full name of the subscriber.
          example: Scott Fisher
    Trigger-Bot-Call-Request:
      type: object
      description: Represents the request body for triggering a bot call with a message, recipients, retries, loops, and optional actions.
      required:
        - text
      properties:
        text:
          type: string
          maxLength: 500
          description: |
            The message to be dictated during the call.<br> <b>Limit:</b> 500 characters.
        user_ids:
          type: array
          maxItems: 10
          description: |
            List of user ZUIDs or emails.<br> <b>Limit:</b> 10 entries.
          items:
            type: string
            description: User identifier, which can be either a ZUID or an email address.
        retry:
          type: integer
          maximum: 3
          description: |
            Number of retries if the user misses the call. System will retry after 2 minutes.<br> <b>Maximum Attempts:</b> 3
        loop:
          type: integer
          maximum: 3
          description: |
            Number of times the message will be dictated.<br> <b>Maximum:</b> 3
        actions:
          type: array
          maxItems: 5
          description: |
            List of actions to be displayed as buttons during the call. <br>Each action includes a label, icon, and a specific action with its associated data. <br><b>Limit:</b> 5
          items:
            type: object
            description: Defines the structure of an action button shown during the bot call.
            required:
              - label
              - action
            properties:
              label:
                type: string
                description: |
                  Text displayed on the button.<br>
                  <b>Maximum Length:</b> 20 characters.
              icon:
                type: string
                description: |
                  Icon identifier for the button. Can be an image URL or a supported icon keyword (e.g., <code>tick</code>, <code>preview</code>, <code>url</code>).
                  <a href="../icons/#overview">View supported icons</a>
              hint:
                type: string
                maxLength: 100
                description: |
                  Tooltip or additional message (optional).<br>
                   <b>Maximum Length:</b> 100 characters.
              key:
                type: string
                maxLength: 100
                description: |
                  Optional key reference.
                  This can be used to identify the button in the bot handler when the action is triggered.
                  <b>Maximum Length:</b> 100 characters.
              action:
                type: object
                description: |
                  An object containing the type of action the button should perform.
                required:
                  - type
                  - data
                properties:
                  type:
                    type: string
                    description: |
                      The action type for a button.<br>Refer to <a href="../buttons/#message-card-buttons">Message Card Buttons</a> for allowed action types and their corresponding data requirements.
                  data:
                    type: object
                    additionalProperties: true
                    description: |
                      An object with properties for each action type. The required properties depend on the action type specified.<br>
                      Refer to <a href="../buttons/#message-card-buttons">Message Card Buttons</a> for details on the expected data structure for each action type.
      example:
        text: We've detected an issue with Zylker Servers. Our team is working to resolve it at the earliest.
        user_ids:
          - '55743327'
          - '55642727'
        retry: 3
        loop: 2
        actions:
          - label: View details
            icon: url
            action:
              type: open.url
              data:
                web: https://cliq.zoho.com
          - label: Acknowledge
            icon: tick
            hint: ''
            action:
              type: invoke.function
              data:
                name: test
            key: ''
          - label: Delegate
            icon: preview
            hint: ''
            action:
              type: system.api
              data:
                api: audiocall/1234
    Bot-call-response:
      type: object
      description: Represents the response returned after triggering a bot call, including the alert instance ID and associated users.
      properties:
        user_ids:
          type: array
          description: List of user ZUIDs associated with the alert instance
          items:
            type: string
            description: User identifier represented as a ZUID.
        id:
          type: string
          description: Unique ID of the alert instance
      example:
        user_ids:
          - '55622727'
          - '55743307'
        id: dfb91610-296f-4f7a-b2b2-3b4436f2f5f0
    BotCreate:
      type: object
      description: Payload for creating a new bot.
      required:
        - name
        - description
      properties:
        execution_type:
          type: string
          enum:
            - deluge
            - webhook
          description: |
            Defines how the created bot will execute its handlers. The execution type determines the scripting environment for the bot's logic.<br>
            <b>Allowed values</b>:
            <ul>
              <li><code>deluge</code>: Bot handlers will be implemented using Deluge scripts, allowing for complex logic and integration with Zoho services.</li>
              <li><code>webhook</code>: Bot handlers will trigger external webhooks, enabling integration with third-party services and custom backend logic.</li>
            </ul>
            <b>Default value</b>: deluge
          example: deluge
        execution_url:
          type: string
          description: |
            Required if <b>execution_type</b> is set to <code>webhook</code>. 
            <ul>
              <li>The URL that will be called when the bot's handlers are triggered.</li>
              <li>This should be a publicly accessible endpoint that can receive POST requests from the Cliq platform.</li>
            </ul>
          example: https://api.example.com/webhooks/messages
        name:
          type: string
          maxLength: 20
          description: |
            Display name of the bot. Must be unique across the platform and can be updated later.<br>
            <b>Note:</b> The <code>unique_name</code> (used to identify the bot in API calls) is auto-assigned by Cliq on creation and cannot be changed, even if the display name is updated.<br>
            <b>Maximum Length</b>: 20 characters.
          example: Clientcare Bot
        description:
          type: string
          maxLength: 300
          description: |
            Description of the bot. Provides details about the bot's functionality and purpose.<br>
            <b>Maximum Length</b>: 300 characters.
          example: Your client care co-pilot streamlining support by providing instant customer context and easy access to critical resources.
        scope:
          type: string
          enum:
            - organization
            - team
            - personal
          description: |
            Access level for the bot. Determines the visibility and availability of the bot within the organization.<br>
            <b>Allowed values</b>:
            <ul>
              <li><code>organization</code>: Bot is available to all users in the organization.</li>
              <li><code>team</code>: Bot is available only to specified teams within the organization.</li>
              <li><code>personal</code>: Bot is available only to the creator but can be shared with other users.</li>
            </ul>
          example: team
        team_ids:
          type: array
          maxItems: 4
          description: |
            List of <a href="/cliq/help/restapi/v3/glossary/#TEAM_ID">team_ids</a> that are allowed to access the bot when <code>scope</code> is set to <code>team</code>.<br>
            <b>Maximum limit</b>: 4 team IDs can be provided, and this is mandatory when the bot's <b>scope</b> is set to <code>team</code>.
          items:
            type: integer
            example: 12345678
        status_messages:
          type: array
          maxItems: 10
          description: |
            Status messages shown for the bot. These messages will be displayed in the bot's profile or when users interact with the bot.<br>
            <b>Maximum limit</b>: 10 messages.
          items:
            type: string
            maxLength: 50
            example: Here to help you with client support!
        image:
          type: string
          description: |
            Base64-encoded avatar image for the bot. This image will represent the bot in conversations and the list of bots.<br>
          example: https://www.zoho.com/cliq/help/restapi/images/poll_icon.png
        channel_participation:
          type: array
          maxItems: 10
          description: |
            Channel participation capabilities of the bot. Defines how the bot can interact in channels.<br>
            <b>Maximum limit</b>: 3.<br>
            <b>Allowed values</b>:
            <ul>
              <li><code>listen_message</code>: Bot can listen to messages in channels.</li>
              <li><code>send_message</code>: Bot can send messages to channels.</li>
              <li><code>auto_follow_thread</code>: Bot will automatically follow threads it participates in.</li>
            </ul>
          items:
            type: string
            enum:
              - listen_message
              - send_message
              - auto_follow_thread
            example: send_message
        calls:
          type: string
          enum:
            - enable
            - disable
          description: |
            Enables or disables the Bot Calls feature for this bot. Bot Calls let the bot initiate voice alerts to targeted users for urgent, high-priority notifications.
            When set to <code>enabled</code>, the bot's <b>Call Handler</b> becomes active and triggers on call state events: <code>ringing</code>, <code>answered</code>, <code>ended</code>, <code>declined</code>, <code>missed</code>, <code>offline</code>, and <code>busy</code>.<br><br>
            <b>Allowed values</b>:
            <ul>
              <li><code>enabled</code>: Bot can initiate voice calls to users. Bot calls override the recipient's Do Not Disturb setting, ensuring delivery of critical alerts.</li>
              <li><code>disabled</code>: Bot cannot initiate voice calls.</li>
            </ul>
            <b>Notes</b>:
            <ul>
              <li>Individual subscribers can toggle bot calls on or off from their own Bots and Tools settings.</li>
              <li>Organization admins can override and lock this setting for all users via Resource Management in the Admin Panel.</li>
              <li>When <code>calls</code> is <code>enabled</code>, you can optionally add a <code>call_handler</code> to the bot to handle call state events programmatically.</li>
            </ul>
          example: enable
    BotUpdateResponse:
      type: object
      description: Response returned after successfully updating a bot.
      properties:
        url:
          type: string
          description: API endpoint URL for the updated bot resource.
          example: /api/v3/bots/b-53719000002124012
        type:
          type: string
          description: Resource type.
          example: bot
        data:
          type: object
          description: The updated bot object reflecting all applied changes.
          properties:
            unique_name:
              type: string
              description: Unique identifier of the bot (cannot be changed after creation).
              example: crmbot
            name:
              type: string
              description: Updated display name of the bot.
              example: CRM Bot
            id:
              type: string
              description: Numeric ID of the bot.
              example: '53719000002124012'
            description:
              type: string
              description: Updated description of the bot.
              example: Your CRM co-pilot providing instant access to customer data and insights within Cliq.
            scope:
              type: string
              description: Updated access level of the bot.
              example: organization
            status_messages:
              type: array
              description: Updated status messages for the bot.
              items:
                type: string
              example:
                - Here to help you with CRM support!
            channel_participation:
              type: array
              description: Updated channel interaction capabilities.
              items:
                type: string
              example:
                - listen_message
            calls:
              type: string
              description: Indicates whether bot calls are enabled or disabled.
              example: enable
            handlers:
              type: array
              description: Handlers currently configured for the bot.
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: Handler type.
                    example: welcome_handler
            creator:
              type: object
              description: User who created the bot.
              properties:
                name:
                  type: string
                  description: Name of the creator.
                  example: James
                id:
                  type: string
                  description: ZUID of the creator.
                  example: '65113112'
            execution_type:
              type: string
              description: Script execution engine used by the bot.
              example: deluge
            status:
              type: string
              description: Current operational status of the bot.
              example: enabled
            type:
              type: string
              description: Bot category. Always custom for user-created bots.
              example: custom
            default:
              type: boolean
              description: Indicates whether this is the default bot.
              example: false
            subscriber_count:
              type: integer
              description: Number of users subscribed to the bot.
              example: 1
    BotEdit:
      type: object
      description: Payload for updating an existing bot. All fields are optional.
      properties:
        name:
          type: string
          maxLength: 20
          description: |
            Updated display name of the bot. Must be unique across the platform.<br>
            <b>Note:</b> Updating the display name does not affect the <code>unique_name</code>, which is permanently assigned by Cliq and cannot be changed.<br>
            <b>Maximum length:</b> 20 characters.
          example: CRM Bot
        description:
          type: string
          maxLength: 300
          description: |
            Updated bot description.<br>
            <b>Maximum length:</b> 300 characters.
          example: Your CRM co-pilot providing instant access to customer data and insights within Cliq.
        scope:
          type: string
          enum:
            - organization
            - team
            - personal
          description: |
            Updated access level.<br>
            <b>Allowed values</b>:
            <ul>
              <li><code>organization</code>: Bot is available to all users in the organization.</li>
              <li><code>team</code>: Bot is available only to specified teams within the organization.</li>
              <li><code>personal</code>: Bot is available only to the creator but can be shared with other users.</li>  
            </ul> 
          example: organization
        team_ids:
          type: array
          maxItems: 4
          description: |
            List of <a href="/cliq/help/restapi/v3/glossary/#TEAM_ID">team_ids</a> that are allowed to access the bot when <code>scope</code> is set to <code>team</code>.<br>
            <b>Maximum limit:</b> 4 team IDs can be provided, and this is mandatory when the bot's scope is set to <code>team</code>.
          items:
            type: integer
        status_messages:
          type: array
          maxItems: 10
          description: |
            Status messages shown for the bot. These messages will be displayed in the bot's profile or when users interact with the bot.<br>
            <b>Maximum limit:</b> 10 messages.
            <b>Maximum length:</b> Each message can be up to 50 characters long.
          items:
            type: string
            maxLength: 50
            example: Here to help you with CRM support!
        image:
          type: string
          description: |
            Updated Base64-encoded avatar image.
          example: https://www.zoho.com/cliq/help/restapi/images/poll_icon.png
        channel_participation:
          type: array
          maxItems: 10
          description: |
            Updated channel participation capabilities of the bot. Defines how the bot can interact in channels.<br>
            <b>Maximum limit</b>: 3.<br>
            <b>Allowed values</b>:
            <ul>
              <li><code>listen_message</code>: Bot can listen to messages in channels.</li>
              <li><code>send_message</code>: Bot can send messages to channels.</li>
              <li><code>auto_follow_thread</code>: Bot will automatically follow threads it participates in.</li>
            </ul>
          items:
            type: string
            enum:
              - listen_message
              - send_message
              - auto_follow_thread
        execution_url:
          type: string
          format: uri
          description: |
            The server URL where the bot's webhook events are sent. Applicable only for <b>Webhook bots</b>.<br>
            This field can be updated independently to redirect the bot to a new endpoint without modifying any other configuration.
          example: https://example.com/webhook/bot-handler
        calls:
          type: string
          enum:
            - enabled
            - disabled
          description: |
            Enables or disables the Bot Calls feature for this bot. When set to <code>enable</code>, the bot can initiate voice alerts to users and its <b>Call Handler</b> becomes active, firing on call state events: <code>ringing</code>, <code>answered</code>, <code>ended</code>, <code>declined</code>, <code>missed</code>, <code>offline</code>, and <code>busy</code>.<br><br>
            <b>Allowed values</b>:
            <ul>
              <li><code>enabled</code>: Bot can initiate voice calls. Calls override the recipient's Do Not Disturb setting.</li>
              <li><code>disabled</code>: Bot cannot initiate voice calls.</li>
            </ul>
            <b>Notes</b>:
            <ul>
              <li>Individual subscribers can toggle bot calls on or off from their Bots and Tools settings.</li>
              <li>Org admins can override and lock this setting for all users via the Admin Panel.</li>
            </ul>
      example:
        name: CRM Bot
        description: Your CRM co-pilot providing instant access to customer data and insights within Cliq.
        scope: organization
        status_messages:
          - Here to help you with CRM support!
        image: https://www.zoho.com/cliq/help/restapi/images/poll_icon.png
        channel_participation:
          - listen_message
        calls: enabled
    HandlerCreate:
      type: object
      description: Payload for creating a new handler.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - welcome_handler
            - message_handler
            - mention_handler
            - context_handler
            - participation_handler
            - incoming_webhook_handler
            - menu_handler
            - call_handler
          description: |
            Handler type to create.<br>
            <b>Allowed values</b>:
            <ul>
              <li><code>welcome_handler</code>: Executes when a user subscribes to the bot, providing a personalized greeting or onboarding message.</li>
              <li><code>message_handler</code>: Triggers on incoming messages to the bot, enabling dynamic responses based on message content.</li>
              <li><code>mention_handler</code>: Fires when the bot is mentioned in a conversation, allowing it to respond contextually.</li>
              <li><code>context_handler</code>: Executes based on specific contextual triggers defined by the bot's logic.</li>
              <li><code>participation_handler</code>: Activates when users interact with the bot in channels, such as joining or leaving.</li>
              <li><code>incoming_webhook_handler</code>: Handles events from external systems via incoming webhooks.</li>
              <li><code>menu_handler</code>: Defines custom menu actions for the bot, providing interactive options to users.</li>
              <li><code>call_handler</code>: Responds to bot call events, such as ringing, answered, ended, etc.</li> 
            </ul>
        script:
          type: string
          description: |
            Deluge script source code to execute for the handler.<br>
            <b>Maximum size is 250KB.</b><br>
            <b>Note:</b> Applicable only for <b>Deluge bots</b>. Do not pass <code>script</code> for Webhook bots - use <code>permissions</code> instead.
          maxLength: 2147483648
        permissions:
          type: array
          maxItems: 5
          description: |
            List of data attributes to forward to your server in the webhook payload when the handler fires.<br>
            <b>Note:</b> Applicable only for <b>Webhook bots</b>. Do not pass <code>permissions</code> for Deluge bots - use <code>script</code> instead.<br>
            <b>Maximum:</b> 5 permissions per handler.<br>
            <b>Allowed values</b>:
            <ul>
              <li><code>chat</code>: Chat context (chat ID, type, participants).</li>
              <li><code>message</code>: Message content and metadata.</li>
              <li><code>user</code>: Sender's user profile details.</li>
              <li><code>location</code>: Sender's location data.</li>
              <li><code>attachments</code>: Attachment metadata and download info.</li>
            </ul>
            Not all permissions are valid for every handler type. Refer to the permissions availability table in the <a href="#create_a_handler_for_a_bot">Create a handler</a> endpoint description.
          items:
            type: string
            enum:
              - chat
              - message
              - user
              - location
              - attachments
        name:
          type: string
          maxLength: 15
          description: |
            Display name for the menu action, where this name will be shown as the menu action label.<br>
            <b>Maximum length:</b> 15 characters.<br>
            <b>Note:</b> Applicable only for <code>menu_handler</code> type.
                
        icon:
          type: string
          description: |
            <ul>
              <li>Custom icon reference for bot menu actions. This icon will be displayed alongside the menu action in the UI.</li>
              <li>Refer to <b><a href="icons/#overview">icons</a></b> for supported menu action icons that can be used to enhance the UI of the handler's menu action.</li>
            </ul> 
            <b>Note:</b> Applicable only for <code>menu_handler</code> type.
        sub_actions:
          type: array
          maxItems: 5
          description: |
            List of sub-actions for menu handlers.
            <ul>
            <li>Sub-actions allow you to create nested menu options under a main menu action, providing a structured and organized way to present multiple related actions to users.</li>
            <li><b>Maximum limit:</b> 5 sub-actions can be defined for a menu handler.</li>
            <li>Each sub-action includes a name, optional icon, and its own action definition, allowing for complex interaction flows within the bot's menu system.</li>
            </ul>
            <b>Note:</b> Applicable only for <code>menu_handler</code> type.
          items:
            $ref: '#/components/schemas/SubAction'
      example:
        name: Bot Menu Action
        icon: wand/#FFFFFF
        script: |-
          response = Map();
          response.put("text","This is a bot menu action");
          return response;
        sub_actions:
          - name: Sub Action 1
            icon: wand/#FFFFFF
    SubAction:
      type: object
      description: Sub-action definition for menu handlers.
      required:
        - name
      properties:
        name:
          type: string
          maxLength: 15
          description: |
            Sub-action name.<br>
            <b>Maximum length:</b> 15 characters.
        icon:
          type: string
          description: |
            Custom icon reference for the sub-action.<br>
            Refer to <b><a href="icons/#overview">icons</a></b> for supported icons that can be used to enhance the UI of the sub-action.
    HandlerEdit:
      type: object
      description: Payload for updating an existing handler.
      properties:
        script:
          type: string
          description: |
            Updated Deluge script source code for the handler.<br>
            <b>Maximum size is 250KB.</b><br>
            <b>Note:</b> Applicable only for <b>Deluge bots</b>.
        permissions:
          type: array
          maxItems: 5
          description: |
            Updated list of data attributes to forward to your server in the webhook payload.<br>
            <b>Note:</b> Applicable only for <b>Webhook bots</b>.<br>
            <b>Maximum:</b> 5 permissions per handler.<br>
            <b>Allowed values</b>: 
            <ul>
              <li><code>chat</code>: Chat context (chat ID, type, participants).</li>
              <li><code>message</code>: Message content and metadata.</li>
              <li><code>user</code>: Sender's user profile details.</li>
              <li><code>location</code>: Sender's location data.</li>
              <li><code>attachments</code>: Attachment metadata and download info.</li>
            </ul>
            Not all permissions are valid for every handler type. Refer to the permissions availability table in the <a href="#create_a_handler_for_a_bot">Create a handler</a> endpoint description.
          items:
            type: string
            enum:
              - chat
              - message
              - user
              - location
              - attachments
        name:
          type: string
          maxLength: 15
          description: |
            Updated display name for the menu action.<br>
            <b>Maximum length:</b> 15 characters.<br>
            <b>Note:</b> Applicable only for <code>menu_handler</code> type.
        icon:
          type: string
          description: |
            Updated custom icon reference for menu handler variants.<br>
            <b>Note:</b> Applicable only for <code>menu_handler</code> type.
        sub_actions:
          type: array
          maxItems: 5
          description: |
            Updated list of sub-actions for menu handlers.
            <ul>
            <li>Sub-actions allow you to create nested menu options under a main menu action, providing a structured and organized way to present multiple related actions to users.</li>
            <li><b>Maximum limit:</b> 5 sub-actions can be defined for a menu handler.</li>
            <li>Each sub-action includes a name, optional icon, and its own action definition, allowing for complex interaction flows within the bot's menu system.</li>
            </ul>
            <b>Note:</b> Applicable only for <code>menu_handler</code> type.
          items:
            $ref: '#/components/schemas/SubAction'
      example:
        script: |-
          response = Map();
          response.put("text", "👋 Welcome to the IT Help Desk! Select an option to get started.");
          return response;
        name: IT Help Desk
        icon: wand/627282
        sub_actions:
          - name: Raise Ticket
            icon: wand/627290
          - name: Track Status
            icon: wand/627291
          - name: Request Access
            icon: wand/627292
    BotAssociateChannelRequest:
      type: object
      description: Payload to associate bot with a channel.
      properties:
        channel_unique_name:
          type: string
          description: |
            Unique name of the channel to associate with the bot. This is the identifier used in API calls to specify the channel for bot association.<br>
            To retrieve the unique name of a channel, refer to <a href="/cliq/help/restapi/v3/glossary/#CHANNEL_UNIQUE_NAME">CHANNEL_UNIQUE_NAME</a> in the Glossary.
      additionalProperties: true
      example:
        channel_unique_name: announcements
    BotMessage:
      type: object
      description: |
        Payload for sending a message from a bot. At least one of <code>text</code>, <code>card</code>, or <code>slides</code> must be provided.
        To target specific recipients, include <code>user_ids</code> (comma-separated user IDs, up to 100) or set <code>broadcast: true</code> to reach all subscribers.
      properties:
        text:
          type: string
          description: |
            Plain-text or rich-text message content.<br>
            <b>Maximum length:</b> 5000 characters.
          minLength: 1
          maxLength: 5000
          example: Hello! Here's your daily summary.
        buttons:
          type: array
          description: |
            Array of action buttons attached to the message. Each button executes an action when clicked.<br>
            <b>Maximum:</b> 5 buttons.<br>
            For the full button object structure and supported action types, refer to the <a href="/cliq/help/restapi/v3/buttons/#overview"><b>Buttons documentation</b></a>.
          maxItems: 5
          items:
            type: object
            additionalProperties: true
          example:
            - label: View Report
              action:
                type: open.url
                data:
                  web: https://reports.zylker.com/latest
            - label: Acknowledge
              action:
                type: invoke.function
                data:
                  name: ack_alert
        slides:
          type: array
          description: |
            Array of structured content blocks (slides) rendered below the card inside the message.
            Sits at the top level alongside <code>text</code> and <code>card</code> - not nested inside <code>card</code>.
            Most commonly paired with the <code>modern-inline</code> card theme.
            Maximum 20 slides. Maximum total size: 10,000 characters.
            <br><br><b>Supported slide types:</b>
            <ul>
              <li><b>table</b> - Renders a data table. Requires <code>data.headers</code> (array of strings) and <code>data.rows</code> (array of objects).</li>
              <li><b>list</b> - Renders a bulleted list. <code>data</code> is an array of strings.</li>
              <li><b>label</b> - Renders labelled key-value pairs. <code>data</code> is an array of objects with <code>label</code> and <code>value</code>.</li>
              <li><b>images</b> - Renders images inline. <code>data</code> is an array of image URL strings.</li>
            </ul>
          maxItems: 20
          items:
            type: object
            required:
              - type
            properties:
              type:
                type: string
                description: |
                  Slide content type.
                  <br><b>Allowed values</b>: <code>table</code> | <code>list</code> | <code>label</code> | <code>images</code> | <code>text</code>
                enum:
                  - table
                  - list
                  - label
                  - images
                  - text
                example: table
              title:
                type: string
                description: Optional heading displayed above the slide content.
                example: Ticket Details
              data:
                description: |
                  Content payload for the slide. Structure depends on <code>type</code>:
                  <ul>
                    <li><b>table</b>: Object with <code>headers</code> (array of strings) and <code>rows</code> (array of objects).</li>
                    <li><b>list</b>: Array of strings.</li>
                    <li><b>label</b>: Array of objects, each with <code>label</code> and <code>value</code>.</li>
                    <li><b>images</b>: Array of image URL strings.</li>
                    <li><b>text</b>: A string containing the text content to display.</li>
                  </ul>
                example:
                  headers:
                    - Field
                    - Value
                  rows:
                    - Field: Build
                      Value: '#42'
                    - Field: Status
                      Value: Passed
          example:
            - type: table
              title: Build Summary
              data:
                headers:
                  - Field
                  - Value
                rows:
                  - Field: Build
                    Value: '#42'
                  - Field: Status
                    Value: Passed
        card:
          type: object
          description: |
            Message card object. Use to render a structured interactive card - poll, modern-inline, or prompt.
            For the full card object structure, available themes, and field definitions, refer to the <a href="/cliq/help/restapi/v3/messagecards/#overview"><b>Message Cards documentation</b></a>.
          additionalProperties: true
          example:
            theme: modern-inline
            title: Deployment v3.6.1 - Approval Required
        bot:
          type: object
          description: |
            Custom sender details to override the bot's default display name and avatar for this message.
          properties:
            name:
              type: string
              description: Display name shown as the message sender instead of the bot's default name.
              example: Deployment Bot
            image:
              type: string
              description: Publicly accessible HTTPS URL of the avatar image to use for this message.
              example: https://example.com/bot-avatar.png
          example:
            name: Deployment Bot
            image: https://example.com/bot-avatar.png
        styles:
          type: object
          description: |
            Style settings for the message. Controls visual rendering such as background highlight colour and markdown processing.
          properties:
            background:
              type: string
              description: |
                Background highlight colour for the message bubble.
                <br><b>Allowed values</b>: <code>red</code> | <code>yellow</code> | <code>green</code> | <code>blue</code> | <code>grey</code>
              enum:
                - red
                - yellow
                - green
                - blue
                - grey
              example: yellow
            markdown:
              type: boolean
              description: |
                Set to <code>true</code> to enable Markdown parsing in the <code>text</code> field.
              example: true
          example:
            background: yellow
            markdown: true
        user_ids:
          type: string
          description: |
            Comma-separated list of user ZUIDs or emails to send the message to specific recipients.<br>
            <b>Maximum 100 user IDs can be provided.</b>
          example: 55743307,55622727
        reply_to:
          type: string
          description: |
            Message ID to reply to. The new message will be posted as a reply to the specified message.<br>
            <b>Maximum length:</b> 100 characters.
          example: 1709038327622%2029706114886
        notify_edit:
          type: boolean
          description: |
            Set to <code>true</code> to send a notification to recipients if the message is edited after being sent.
          example: false
        message_topic:
          type: string
          description: |
            Topic string used as the thread title when a thread is created from this message. Maximum length: 255 characters.
          maxLength: 255
          example: Daily Standup Updates
        mark_as_read:
          type: boolean
          description: |
            Set to <code>true</code> to automatically mark this message as read for the recipient.
          example: false
        sync_message:
          type: boolean
          description: |
            Set to <code>true</code> to send the message synchronously. The response will include <code>chat_id</code> and <code>message_id</code>.
          example: false
        thread_chat_id:
          type: string
          description: |
            Chat ID of an existing thread to post the message into. Maximum length: 100 characters.
          maxLength: 100
          example: CT_1207124526552602256_60002085329-T-1291567019566818579
        thread_message_id:
          type: string
          description: |
            Message UID from which a thread has been originated. Used to associate the message with a specific thread.
          example: 1727333520582%2047588994306224
        post_in_parent:
          type: boolean
          description: |
            Set to <code>true</code> to also post the message in the parent chat or channel when sending to a thread.
          example: false
        thread_title:
          type: string
          description: |
            Custom title for a newly created thread.<br>
            <b>Maximum length:</b> 100 characters.
          maxLength: 100
          example: PROCESS_DOWN alert thread
      example:
        text: Hello! Here's your daily summary.
        broadcast: false
        user_ids: 55743307,55622727
        sync_message: 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.Bots.READ: Read Bot Information
            ZohoCliq.Bots.CREATE: Create Bots
            ZohoCliq.Bots.UPDATE: Update Bots
            ZohoCliq.Bots.DELETE: Delete Bots
            ZohoCliq.Webhooks.CREATE: Post messages to conversations via webhooks
            ZohoCliq.BotMessages.CREATE: Send messages via bot incoming webhooks
            ZohoCliq.Channels.UPDATE: Update Channel Settings
