openapi: 3.0.0
info:
  title: Bots
  description: >
    Bots are conversational assistants designed to automate and handle simple tasks, making your life easier by performing any monotonous job!

  contact: {}
  version: 1.0.0

servers:
  - url: 'https://cliq.zoho.com/api/v2'
    description: 'API Endpoint'

tags:
  - name: bots
    description: 'Bots Module'

paths:
  /bots/{BOT_UNIQUE_NAME}/subscribers:
    get:
      summary: 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>
        <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>: 10 minutes<br>
        Wait time before consecutive API requests.<br><br>

      parameters:

        - name: BOT_UNIQUE_NAME
          in: path
          required: true
          description: Unique identifier of the bot.
          schema:
            type: string   

        - name: appkey
          in: query
          required: false
          description: Mandatory if 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: string                    

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotSubscribersResponse'
      security:
        - Zoho_Auth:
            - ZohoCliq.Bots.READ

  /bots/{BOT_UNIQUE_NAME}/calls:
    post:   
      summary: Trigger Bot Calls
      description: |
        Utilize this API to send a voice alert to specific users via the bot.
        <br><br>
        <b>Threshold limit</b>: 10 calls for five minutes 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><br>
      
      parameters:

        - name: BOT_UNIQUE_NAME
          in: path
          required: true
          description: Unique identifier of the bot from which bot call needs to be triggered.
          schema:
            type: string  

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Trigger-Bot-Call-Request'    

      responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Bot-call-response'
      security:
          - Zoho_Auth:
              - ZohoCliq.Webhooks.CREATE

components:
  schemas:

    no-response:
      type: object
      properties:
        Response Code:
          type: string
          example: "204 No response"

    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:
            type: object
            properties:
              email_id:
                type: string
                example: "scott.fisher@zylker.com"
              user_id:
                type: string
                example: "19183988"
              name:
                type: string
                example: "Scott Fisher"
      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"

    Trigger-Bot-Call-Request:
      type: object
      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.
              <b>Limit:</b> 10 entries.
          items:
            type: string
        retry:
          type: integer
          maximum: 3
          description: >
              Number of retries if the user misses the call. System will retry after 2 minutes.
              <b>Maximum Attempts:</b> 3
        loop:
          type: integer
          maximum: 3
          description: >
              Number of times the message will be dictated.
              <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
            required:
              - label
              - action
            properties:
              label:
                type: string
                description: <b>label</b> - Text displayed on the button.
              icon:
                type: string
                description: <b>icon</b> - Icon for the button (can be URL or keyword).
              hint:
                type: string
                description: <b>hint</b> - Tooltip or additional message (optional).
              key:
                type: string
                description: <b>key</b> - Optional key reference.
              action:
                type: object
                required:
                  - type
                  - data
                properties:
                  type:
                    type: string
                    description: <b>type</b> - Defines the type of action.
                  data:
                    type: object
                    additionalProperties: true
                    description: <b>data</b> - Payload specific to the 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
      properties:
        user_ids:
          type: array
          description: List of user ZUIDs associated with the alert instance
          items:
            type: string
        id:
          type: string
          description: Unique ID of the alert instance
      example:
        user_ids:
          - "55622727"
          - "55743307"
        id: "dfb91610-296f-4f7a-b2b2-3b4436f2f5f0"
    

  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: 'https://accounts.zoho.com/oauth/v2/auth'
          scopes:
            ZohoCliq.Bots.READ: Read Bot Information
            