openapi: 3.0.0
info:
  title: User Status
  description: |
    Use the user status API to create, retrieve, update, or delete your status on Cliq. Additionally, you can check the status of another user by providing their User ID. For more information about user status in Cliq, please refer to our help guide. 
  contact: {}
  version: 1.0.0
externalDocs:
  description: Find out more about Zoho Cliq APIs V2
  url: https://www.zoho.com/cliq/help/restapi/v2/
servers:
  - url: https://cliq.zoho.com/api/v2
    description: Zoho Cliq US DC
tags:
  - name: usersstatus
    description: User Status Module
paths:
  /statuses:
    post:
      summary: Add a new status
      operationId: Add a new status
      description: |
        Use this API to add a new status in Cliq.
        <br><br> 
        <p>
          <b>Threshold limit</b>: 20 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>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPresenceUpdateRequest'
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceUpdateResponse'
        '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.Profile.CREATE
      tags:
        - usersstatus
    get:
      summary: Retrieve all statuses
      operationId: Retrieve all statuses
      description: |
        Use this API to retrieve the list of all your statuses in Cliq.
        Note: This API does not return default status. You'll get the list of all the custom statuses you've set on Cliq.
        <br><br> 
        <p>
          <b>Threshold limit</b>: 20 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>
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceMessagesResponse'
        '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.Profile.READ
      tags:
        - usersstatus
  /statuses/ephemeral:
    put:
      summary: Add a transient status
      operationId: Add a transient status
      description: |
        Use this API to add a temporary status in Cliq.
        <br><br> 
        <p>
          <b>Threshold limit</b>: 20 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>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemporaryStatusUpdateRequest'
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/empty-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.Profile.UPDATE
      tags:
        - usersstatus
    delete:
      summary: Delete transient status
      operationId: Delete transient status
      description: |
        Use this API to delete a status in Cliq.
        <br><br> 
        <p>
          <b>Threshold limit</b>: 20 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>
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/empty-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.Profile.DELETE
      tags:
        - usersstatus
  /statuses/current:
    get:
      summary: Retrieve current status
      operationId: Retrieve current status
      description: |
        Fetch your current status in Cliq.
        <br><br> 
        <p>
          <b>Threshold limit</b>: 20 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>
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceUpdateResponse'
        '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.Profile.READ
      tags:
        - usersstatus
  /users/{USER_ID}:
    get:
      summary: Retrieve a user's status
      operationId: Retrieve status of a user
      description: |
        Fetch a user's current status in Cliq.
        <br><br> 
        <p>
          <b>Threshold limit</b>: 20 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>
      parameters:
        - name: USER_ID
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the user whose current status needs to be retrieved To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#USER_ID">USER_ID</a> in the Glossary page.
        - name: fields
          in: query
          required: true
          schema:
            type: string
          description: To identify the user field that indicates the current status of the specified user.
          example: chat_status
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceUpdateResponse'
        '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.Users.READ
      tags:
        - usersstatus
  /statuses/{STATUS_ID}/set:
    put:
      summary: Update current status
      operationId: Update current status
      description: |
        Use these APIs to update a given status ID as the current status. Retrieve the status ID using Retrieve All Statuses API.
        <br><br> 
        <p>
          <b>Threshold limit</b>: 20 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>
      parameters:
        - name: STATUS_ID
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the status which needs to be set as current status To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#STATUS_ID">STATUS_ID</a> in the Glossary page.
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStatusSetResponse'
        '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.Profile.UPDATE
      tags:
        - usersstatus
  /statuses/{STATUS_ID}:
    delete:
      summary: Delete status
      operationId: Delete status
      description: |
        Use this API to delete a status in Cliq.
        <br><br> 
        <p>
          <b>Threshold limit</b>: 20 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>
      parameters:
        - name: STATUS_ID
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the status which needs to be deleted To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#STATUS_ID">STATUS_ID</a> in the Glossary page.
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/empty-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.Profile.DELETE
      tags:
        - usersstatus
components:
  schemas:
    empty-response:
      type: object
      description: Response returned when there is no content.
      properties:
        Response_Code:
          type: string
          example: 204 No response
    UserPresenceUpdateRequest:
      type: object
      description: Request body to update a user's presence status in Cliq.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: |
            Denotes the status in Cliq.   <ul>
              <li><b>busy</b> - Sets the user's status to Busy.  
              <li><b>available</b> - Sets the user's status to Available.  
              <li><b>invisible</b> - Hides the user's online presence.
            </ul>
          enum:
            - busy
            - available
            - invisible
          example: busy
        message:
          type: string
          description: Custom status message in Cliq.
          example: In a meeting, will respond soon!
    TemporaryStatusUpdateRequest:
      type: object
      description: Request body to update a user's temporary presence status in Cliq with expiry.
      required:
        - code
        - message
        - expiry
      properties:
        code:
          type: string
          description: |
            Denotes the status in Cliq.  
             <ul>
               <li><b>busy</b> - Sets the user's status to Busy.  
               <li><b>available</b> - Sets the user's status to Available.  
               <li><b>invisible</b> - Hides the user's online presence.
             </ul>
          enum:
            - busy
            - available
            - invisible
          example: busy
        message:
          type: string
          description: Custom status message in Cliq.
          example: In a meeting, will respond soon!
        expiry:
          type: integer
          description: Time in milliseconds until which the transient status is active.
          example: 1641883476276
    UserPresenceUpdateResponse:
      type: object
      description: Response returned after updating user presence.
      properties:
        data:
          type: object
          properties:
            code:
              type: string
              example: busy
            message:
              type: string
              example: In a Meeting
            id:
              type: integer
              example: 1775998000034476000
    UserPresenceMessagesResponse:
      type: object
      description: Response containing all saved status messages for a user.
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                example: Arise awake and stop not till the goal is reached
              id:
                type: integer
                example: 1775998000028408800
          example:
            - message: Arise awake and stop not till the goal is reached
              id: 1775998000028408800
            - message: Coffee break
              id: 1775998000030383900
            - message: Opportunities don't happen. You create them.
              id: 1775998000034330400
            - message: All progress takes place outside the comfort zone
              id: 1775998000034476000
    UserStatusSetResponse:
      type: object
      description: Response returned after setting a specific status message.
      properties:
        url:
          type: string
          example: /api/v2/statuses/{status_id}/set
        type:
          type: string
          example: status_message
        data:
          type: object
          properties:
            code:
              type: string
              example: available
            message:
              type: string
              example: '11'
            id:
              type: string
              example: '45874000000147003'
  securitySchemes:
    Cliq_Auth:
      type: oauth2
      x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoCliq.Users.CREATE: Add Users
            ZohoCliq.Profile.READ: Read User Profile
            ZohoCliq.Profile.CREATe: Create User Profile
            ZohoCliq.Profile.UPDATE: Update User Profile
            ZohoCliq.Profile.DELETE: Delete User Profile
