openapi: 3.0.0
info:
  title: Bots
  version: 1.0.0
  description: |
    Bots are conversational assistants designed to automate and handle simple tasks, making your life easier by performing any monotonous job!
servers:
  - url: https://cliq.zoho.com/api/v2
    description: Zoho Cliq US DC
tags:
  - name: bots
    description: APIs related to bot subscribers and bot voice call alerts.
paths:
  /bots/{BOT_UNIQUE_NAME}/subscribers:
    get:
      summary: Retrieve Bot Subscribers
      operationId: retrieve_bot_subscribers
      description: |
        Use these APIs to obtain the list of users currently subscribed to a bot. Access to bot subscribers is limited to the bot creator or administrator of the organization.
        <br><br>
        <i>Quota Limit</i><br>
        The quota limit for this API is <b>100 requests per minute</b>
      parameters:
        - name: BOT_UNIQUE_NAME
          in: path
          required: true
          description: Unique name of the bot.
          schema:
            type: string
          example: BOT_UNIQUE_NAME
        - name: appkey
          in: query
          required: false
          description: Mandatory if the given bot is from an extension.
          schema:
            type: string
        - name: next_token
          in: query
          required: false
          description: To fetch the next immediate list of user details.
          schema:
            type: string
        - name: sync_token
          in: query
          required: false
          description: To fetch the users who recently subscribed to the bot after the previous request was made.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Size of the set to be fetched.
          schema:
            type: integer
      responses:
        '200':
          description: Bot subscriber list returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotSubscribersResponse'
              example:
                url: /api/v2/bots/{BOT_UNIQUE_NAME}/subscribers
                type: bot_subscriber
                sync_token: NTB8MTcyMjcwMDXwxNzIyNzA5MzQ0NDM5
                data:
                  - email_id: scott.fisher@zylker.com
                    user_id: '19183988'
                    name: Scott Fisher
      security:
        - Cliq_Auth:
            - ZohoCliq.Bots.READ
      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>
      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/v2/glossary/#BOT_UNIQUE_NAME">BOT_UNIQUE_NAME</a> in the Glossary page.
          schema:
            type: string
          example: BOT_UNIQUE_NAME
      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
      tags:
        - bots
components:
  schemas:
    BotSubscribersResponse:
      type: object
      properties:
        url:
          type: string
          example: /api/v2/bots/{BOT_UNIQUE_NAME}/subscribers
        type:
          type: string
          example: bot_subscriber
        sync_token:
          type: string
          example: NTB8MTcyMjcwMDXwxNzIyNzA5MzQ0NDM5
        data:
          type: array
          items:
            $ref: '#/components/schemas/BotSubscriber'
    BotSubscriber:
      type: object
      properties:
        email_id:
          type: string
          example: scott.fisher@zylker.com
        user_id:
          type: string
          example: '19183988'
        name:
          type: string
          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
  securitySchemes:
    Cliq_Auth:
      type: oauth2
      x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          x-tokenUrl: https://accounts.zoho.com/oauth/v2/token
          scopes:
            ZohoCliq.Bots.READ: Read Bot Information
            ZohoCliq.Webhooks.CREATE: Post messages to your conversations directly or by using incoming webhooks
