openapi: 3.0.0
info:
  title: Maintenance - Bulk Export
  description: |
    Create a backup of all conversations (chats, channels and bots) by exporting it. Note: All maintenance APIs will be accessible to give a response only to the organization admin in Cliq.
  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
    description: Zoho Cliq US DC
tags:
  - name: bulkexport
    description: Bulk Export
paths:
  /company/{COMPANY_ID}/maintenanceapi/v2/chats?fields=title,chat_id:
    get:
      summary: Export Conversations
      operationId: Export Conversations in Bulk
      description: |
        Use this API to export specific details of all individual chats and group conversations in your organization. <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: COMPANY_ID
          in: path
          required: true
          description: |
            <ul>
              
              <li>All Maintenance API endpoints must be prefixed with <code>company/{COMPANY_ID}/</code>.</li>
              <li>You can retrieve the company ID from the Cliq web app URL on the homepage.</li>
              <li>Example: <code>https://cliq.zoho.com/company/632387644/index.do</code> where <code>632387644</code> is the <code>COMPANY_ID</code>.</li>
            </ul>
          schema:
            type: string
          example: COMPANY_ID
        - name: Content-Type
          in: header
          required: true
          description: Specifies the format of the exported data.
          schema:
            type: string
            example: text/csv
        - name: fields
          in: query
          required: true
          schema:
            type: string
            description: |
              Comma-separated list of fields to be exported for each chat.<br> <b>Allowed values</b>: <ul>
                <li><b>title</b> : The name or title of the chat.</li>
                <li><b>chat_id</b> : The unique identifier assigned to the chat.</li>
                <li><b>creation_time</b> : The timestamp when the chat was created.</li>
                <li><b>last_modified_time<b> : The timestamp when the chat was last updated.</li>
                <li><b>participant_count</b> : The total number of users in the chat.</li>
                <li><b>total_message_count</b> : The total number of messages in the chat.</li>
                <li><b>creator_id</b> : The user ID of the person who created the chat.</li>
              </ul>      
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/export-conversations-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.OrganizationChats.READ
      tags:
        - bulkexport
  /company/{COMPANY_ID}/maintenanceapi/v2/channels?fields=name,channel_id,participant_count:
    get:
      summary: Export Channels
      operationId: Export Channels in Bulk
      description: |
        Use this API to export details of all the channels in your organization. <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: COMPANY_ID
          in: path
          required: true
          description: |
            <ul>
              
              <li>All Maintenance API endpoints must be prefixed with <code>company/{COMPANY_ID}/</code>.</li>
              <li>You can retrieve the company ID from the Cliq web app URL on the homepage.</li>
              <li>Example: <code>https://cliq.zoho.com/company/632387644/index.do</code> where <code>632387644</code> is the <code>COMPANY_ID</code>.</li>
            </ul>
          schema:
            type: string
          example: COMPANY_ID
        - name: Content-Type
          in: header
          required: true
          description: Specifies the format of the exported data.
          schema:
            type: string
            example: text/csv
        - name: fields
          in: query
          required: true
          schema:
            type: string
          description: |
            Use this parameter to get the list of necessary details to be exported for all channels in your organization. <br> <b>Allowed values:</b> <ul>
              <li><b>name:</b> Name of the channel</li>
              <li><b>channel_id:</b> Unique identifier of the channel</li>
              <li><b>creation_time:</b> Timestamp when the channel was created</li>
              <li><b>last_modified_time:</b> Timestamp of the most recent update</li>
              <li><b>creator_id:</b> Unique ID of the channel creator</li>
              <li><b>description:</b> Description of the channel</li>
              <li><b>participant_count:</b> Number of users in the channel</li>
              <li><b>total_message_count:</b> Total messages exchanged in the channel</li>
              <li><b>status:</b> Indicates if the channel is active or archived</li>
              <li><b>role:</b> Role of the user accessing the channel (e.g., admin, member)</li>
            </ul>     
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/export-channels-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.OrganizationChannels.READ
      tags:
        - bulkexport
  /company/{COMPANY_ID}/maintenanceapi/v2/chats/{CHAT_ID}/members?fields=name,email_id:
    get:
      summary: Export Members in a Conversation
      operationId: Export Members in a Conversation
      description: |
        Use this API to exclusively export the details of members from a specific chat or channel. <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: COMPANY_ID
          in: path
          required: true
          description: |
            <ul>
              
              <li>All Maintenance API endpoints must be prefixed with <code>company/{COMPANY_ID}/</code>.</li>
              <li>You can retrieve the company ID from the Cliq web app URL on the homepage.</li>
              <li>Example: <code>https://cliq.zoho.com/company/632387644/index.do</code> where <code>632387644</code> is the <code>COMPANY_ID</code>.</li>
            </ul>
          schema:
            type: string
          example: COMPANY_ID
        - name: CHAT_ID
          in: path
          required: true
          description: Unique idenfifier of the chat from which details of the members need to be retrieved To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.
          schema:
            type: string
          example: CHAT_ID
        - name: Content-Type
          in: header
          required: true
          description: Specifies the format of the exported data.
          schema:
            type: string
            example: text/csv
        - name: fields
          in: query
          required: true
          schema:
            type: string
          description: |
            Use this parameter to get the details of members to be exported from a specific chat or channel in your organization. <br> <b>Allowed values:</b> <ul>
              <li><b>name:</b> Name of the member</li>
              <li><b>email:</b> Email ID of the member </li>
              <li><b>user_id:</b> Unique ID of the member</li>
            </ul> 
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/export-members-response'
      security:
        - Cliq_Auth:
            - ZohoCliq.OrganizationChats.READ
      tags:
        - bulkexport
  /company/{COMPANY_ID}/maintenanceapi/v2/chats/{CHAT_ID}/messages:
    get:
      summary: Export Messages
      operationId: Export Messages in a Conversation
      description: |
        Use this API to export transcripts or history of all conversations in your organization.
         <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: COMPANY_ID
          in: path
          required: true
          description: |
            <ul>
              
              <li>All Maintenance API endpoints must be prefixed with <code>company/{COMPANY_ID}/</code>.</li>
              <li>You can retrieve the company ID from the Cliq web app URL on the homepage.</li>
              <li>Example: <code>https://cliq.zoho.com/company/632387644/index.do</code> where <code>632387644</code> is the <code>COMPANY_ID</code>.</li>
            </ul>
          schema:
            type: string
          example: COMPANY_ID
        - name: CHAT_ID
          in: path
          required: true
          description: Unique idenfifier of the chat from which history of conversations needs to be exported To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.
          schema:
            type: string
          example: CHAT_ID
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMessagesResponse'
        '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.OrganizationMessages.READ
      tags:
        - bulkexport
components:
  schemas:
    export-conversations-response:
      type: object
      description: Represents the response containing a list of exported conversations with their details.
      properties:
        list:
          type: array
          description: List of conversation records included in the export.
          items:
            type: object
            description: Details of an exported conversation.
            properties:
              name:
                type: string
                description: The name or title of the conversation.
              id:
                type: string
                description: Unique identifier of the conversation.
      example:
        list:
          - name: Whats new-feature updates
            id: '1277744317795524707'
          - name: Zylcal team trip
            id: '1277744317795524704'
          - name: Notely release 2.0
            id: '1277744317795524710'
          - name: Regional sales managers
            id: '1252218064667202771'
          - name: marketing-editors
            id: '1252218129769350577'
    export-channels-response:
      type: object
      description: Represents the response containing a list of exported channels with their metadata.
      properties:
        data:
          type: array
          description: List of channel export records.
          items:
            type: object
            description: Details of an exported channel.
            properties:
              name:
                type: string
                description: The name of the channel.
              channel_id:
                type: string
                description: Unique identifier assigned to the channel.
              participant_count:
                type: integer
                description: The number of participants in the channel.
      example:
        data:
          - name: '#announcements'
            channel_id: '15928000000004007'
            participant_count: 600
          - name: '#marketing'
            channel_id: '15928000000021001'
            participant_count: 15
          - name: '#devops'
            channel_id: '15928000000032005'
            participant_count: 54
          - name: '#sales'
            channel_id: '15928000000054005'
            participant_count: 250
          - name: '#contentreview'
            channel_id: '15928000000075001'
            participant_count: 88
    export-members-response:
      type: object
      description: Represents the response containing a list of exported chat members.
      properties:
        data:
          type: array
          description: List of chat member export records.
          items:
            type: object
            description: Details of an exported chat member.
            properties:
              name:
                type: string
                description: The full name of the chat member.
              email:
                type: string
                description: The email address of the chat member.
      example:
        data:
          - name: Scott Fisher
            email: scott.fisher@zylker.com
          - name: Ryan West
            email: ryan.west@zylker.com
          - name: Olivia Palmer
            email: olivia.palmer@zylker.com
    ChatMessagesResponse:
      type: object
      description: Represents the response containing a list of chat messages exchanged in a conversation.
      properties:
        data:
          type: array
          description: List of messages exchanged in a conversation.
          items:
            type: object
            description: Details of an individual chat message.
            properties:
              sender:
                type: object
                description: Information about the user who sent the message.
                properties:
                  name:
                    type: string
                    description: Full name of the sender.
                    example: Scott Fisher
                  id:
                    type: string
                    description: Unique identifier of the sender.
                    example: '1234567'
              ack_key:
                type: string
                description: Acknowledgment key used for message delivery tracking.
                example: '1528182303065'
              id:
                type: string
                description: Unique identifier of the message.
                example: '1528182303637_7763880281'
              time:
                type: integer
                description: Timestamp of when the message was sent (in milliseconds).
                example: 1528182303637
              type:
                type: string
                description: Type of message (e.g., text, info, call_notification).
                example: text
              content:
                type: object
                description: Content of the message, which may vary based on message type.
                oneOf:
                  - properties:
                      text:
                        type: string
                        description: Textual content of the message.
                        example: Hey Olivia, are you available right now to discuss about our cross marketing with Notely?
                  - properties:
                      type:
                        type: string
                        description: Indicates the type of non-text content, such as a call notification.
                        example: call_notification
                      data:
                        type: object
                        description: Additional data related to the non-text content, such as call details.
                        properties:
                          status:
                            type: string
                            description: Status of the call (e.g., completed, missed).
                            example: completed
                          callee:
                            type: object
                            description: Details of the user who received the call.
                            properties:
                              name:
                                type: string
                                description: Name of the callee.
                                example: Olivia
                              id:
                                type: string
                                description: Unique identifier of the callee.
                                example: '55185718'
                          duration:
                            type: string
                            description: Duration of the call in HH:MM:SS format.
                            example: '00:00:09'
                          call_type:
                            type: string
                            description: Type of call (e.g., audio, video).
                            example: audio
      example:
        data:
          - sender:
              name: Scott Fisher
              id: '1234567'
            ack_key: '1528182303065'
            id: '1528182303637_7763880281'
            time: 1528182303637
            type: text
            content:
              text: Hey Olivia, are you available right now to discuss about our cross marketing with Notely?
          - sender:
              name: Scott Fisher
              id: '1234567'
            ack_key: ''
            id: '1534756983506_74468102866'
            time: 1534756983506
            type: info
            content:
              type: call_notification
              data:
                status: completed
                callee:
                  name: Olivia
                  id: '55185718'
                duration: '00:00:09'
                call_type: audio
          - sender:
              name: Olivia Palmer
              id: '9876543'
            ack_key: '1547615832454'
            id: '1547615832586_143161526662'
            time: 1547615832586
            type: text
            content:
              text: Sure, Scott!s
  securitySchemes:
    Cliq_Auth:
      type: oauth2
      x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoCliq.OrganizationChats.READ: Read chats of the organization
            ZohoCliq.OrganizationMessages.READ: Read messages of the organization
            ZohoCliq.OrganizationChannels.READ: Read channels of the organization
