openapi: 3.0.0
info:
  title: Calls & Meetings
  description: |
    All APIs related to audio and video calls, which include video meetings, audio calls, and screen sharing, are categorized under the Calls & Meetings API.
  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: callsmeetings
    description: Calls & Meetings Module
paths:
  /mediasessions:
    get:
      summary: History
      operationId: Retrieve Calls and Meeting History
      description: |
        Use this API to get the details of all your direct calls, meetings, and broadcasts.
         <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:
        - in: query
          name: type
          schema:
            type: string
            enum:
              - all
              - handshake
              - assembly
              - audio_conference
              - video_conference
              - direct_call
            description: |
              Call history of a particular call type can be retrieved. Allowed values: <ul>
                <li><b>all</b>: Retrieve all media sessions (not combinable with other types)</li>
                <li><b>handshake</b>: Retrieve handshake-type calls</li>
                <li><b>assembly</b>: Retrieve organization-wide assemblies</li>
                <li><b>audio_conference</b>: Retrieve audio conferences</li>
                <li><b>video_conference</b>: Retrieve video conferences</li>
                <li><b>direct_call</b>: Retrieve one-on-one direct calls</li>
              </ul>
              <b>Note</b>: <ul>
                <li>When "all" or "direct_call" type is used, you cannot add any other type separated by commas.</li>
                <li>When "type" is not mentioned, the default values returned are "audio_conference", "video_conference", "handshake", and "assembly".</li>
              </ul>
        - in: query
          name: search
          schema:
            type: string
          description: Search a call using the call title.
        - in: query
          name: sync_token
          schema:
            type: string
          description: A token to retrieve recently synced calls.
        - in: query
          name: next_token
          schema:
            type: string
          description: A token to fetch the next set of calls.
        - in: query
          name: limit
          schema:
            type: integer
            maxLength: 100
          description: Number of call history records to retrieve.
        - in: query
          name: from
          schema:
            type: string
            format: date-time
          description: Start timestamp to filter media sessions.
        - in: query
          name: to
          schema:
            type: string
            format: date-time
          description: End timestamp to filter media sessions.
        - in: query
          name: last_modified
          schema:
            type: string
            format: date-time
          description: Retrieve media sessions modified after this timestamp.
        - in: query
          name: filter
          schema:
            type: string
            enum:
              - live
              - viewed
              - scheduled
              - missed
              - received
              - dialled
          description: |
            The media sessions can be filtered based on the following categories. Allowed values: <ul>
              <li><b>live:</b> Ongoing calls</li>
              <li><b>viewed:</b> Already viewed calls</li>
              <li><b>scheduled:</b> Scheduled media sessions</li>
              <li><b>missed:</b> Missed calls (only for direct_call)</li>
              <li><b>received:</b> Received calls (only for direct_call)</li>
              <li><b>dialled:</b> Dialed calls (only for direct_call)</li>
            </ul> 
            <b>Note:</b>
              <ul>
                <li>The values "missed", "received", and "dialled" can be used only when the type is "direct_call".</li>
                <li>The filter parameter cannot be used when the type is "all".</li>
              </ul>
        - in: query
          name: host_id
          schema:
            type: integer
          description: Filter by host ID of the media session.
        - in: query
          name: recipient_id
          schema:
            type: integer
          description: Filter by recipient ID of the media session.
        - in: query
          name: recipient_ids
          schema:
            type: string
          description: Comma-separated list of recipient IDs to filter sessions.
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaSessionListResponse'
        '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.MediaSession.READ
      tags:
        - callsmeetings
  /mediasessions/{CALL_ID}/participants:
    get:
      summary: Get Participants
      operationId: Get Participants of a call or meeting
      description: |
        Use this API to get all the participants in a call or a meeting
        The header X-API-VERSION 1 must be passed to support the use of query params. Users can get the call ID from the nrs_id key in the AV_History 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: next_token
          in: query
          required: false
          description: Token to get the next set of participants.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Use this parameter to specifiy the number of participants retrieved per API call.
          schema:
            type: integer
            maxLength: 100
        - name: from
          in: query
          required: false
          description: Use this parameter to fetch participants from the specified time.
          schema:
            type: string
        - name: to
          in: query
          required: false
          description: Use this parameter to fetch participants till the specified time.
          schema:
            type: string
        - name: filter
          in: query
          required: false
          schema:
            type: string
          description: |
            Use this parameter to fetch the list of active and inactive users in the call. Allowed values: <ul>
              <li><b>live:</b> Current live users</li>
              <li><b>invited:</b> Users invited but yet to join</li>
              <li><b>joined:</b> Users who joined and left the call</li>
            </ul>
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaSessionParticipantsResponse'
        '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.MediaSession.READ
      tags:
        - callsmeetings
components:
  schemas:
    MediaSessionListResponse:
      type: object
      description: Response containing a list of media sessions with metadata, host details, chat linkage (if any), and participant counts.
      properties:
        data:
          type: array
          description: Array of media session records returned by the API.
          items:
            type: object
            description: A media session record containing identifiers, timestamps, metadata, and optional chat linkage.
            properties:
              id:
                type: string
                description: Unique identifier of the media session.
                example: '392330000000598005'
              end_time:
                type: integer
                description: Epoch timestamp (in milliseconds) indicating when the session ended.
                example: 1643361458859
              session_id:
                type: string
                description: System-generated UUID representing the session instance.
                example: b13d0691-ca45-47c7-b6ad-6cbdf339b9e9
              start_time:
                type: integer
                description: Epoch timestamp (in milliseconds) indicating when the session started.
                example: 1643361407614
              notes:
                type: boolean
                description: Indicates whether notes are linked or available for the session.
                example: false
              is_partial:
                type: boolean
                description: Flag that denotes if the session data is partial or incomplete.
                example: true
              nrs_id:
                type: string
                description: Internal recording system reference ID used for mapping session recordings or logs.
                example: '62440502_1643361407784_1643361407650'
              type:
                type: string
                description: 'Type of the media session (for example: audio_conference, video_conference).'
                example: audio_conference
              title:
                type: string
                description: Title or label assigned to the session (often user-defined).
                example: av_recording
              scope:
                type: string
                description: 'Scope of the session (for example: personal, chat, or team).'
                example: personal
              host:
                type: object
                description: Information about the session host.
                properties:
                  name:
                    type: string
                    description: Full name of the host user.
                    example: '"Scott Fisher'
                  id:
                    type: string
                    description: Unique identifier of the host user.
                    example: '62589940502'
              participant_count:
                type: integer
                description: Total number of participants who joined the session.
                example: 10
              recording:
                type: boolean
                description: Indicates whether the session was recorded (optional field).
                example: true
              chat_id:
                type: string
                description: Identifier of the associated chat if the session is linked to a conversation (optional).
                example: CT_11846783329648523663_62439860
              chat:
                type: object
                description: Chat details linked to this session, present when the session is associated with a chat thread.
                properties:
                  title:
                    type: string
                    description: Title of the chat where the session took place.
                    example: Q3 releases
                  id:
                    type: string
                    description: Unique identifier of the chat thread.
                    example: CT_1184653329648523663_62439860
            required:
              - id
              - end_time
              - session_id
              - start_time
              - notes
              - is_partial
              - nrs_id
              - type
              - title
              - scope
              - host
              - participant_count
          example:
            - id: '392330000000598005'
              end_time: 1643361458859
              session_id: b13d0691-ca45-47c7-b6ad-6cbdf339b9e9
              start_time: 1643361407614
              notes: false
              is_partial: true
              nrs_id: '62440502_1643361407784_1643361407650'
              type: audio_conference
              title: av_recording
              scope: personal
              host:
                name: '"Scott Fisher'
                id: '62589940502'
              participant_count: 10
            - recording: true
              id: '392330000089297001'
              end_time: 1643283428901
              session_id: d419f9e8-36c7-4179-b35a-d7a38df78860
              start_time: 1643283406317
              notes: false
              is_partial: true
              nrs_id: 62440502_1643283406451_CT_1184653329648523663_62439860
              type: video_conference
              chat_id: CT_11846783329648523663_62439860
              title: Marketing Campaigns
              scope: chat
              host:
                name: '"Scott Fisher'
                id: '62440502'
              chat:
                title: Q3 releases
                id: CT_1184653329648523663_62439860
              participant_count: 15
    MediaSessionParticipantsResponse:
      type: object
      description: Represents the response containing participants of a specific media session.
      properties:
        url:
          type: string
          description: API endpoint to fetch participants for the given media session.
          example: /api/v2/mediasessions/15093303_1654794155339_GN_1256255415498864798_15093376/participants
        type:
          type: string
          description: Indicates the resource type of the response object.
          example: participant
        data:
          type: array
          description: List of participants who joined the media session.
          items:
            type: object
            description: Details of a single participant in the media session.
            properties:
              email_id:
                type: string
                description: Email address of the participant.
                example: scott.fisher@zylker.com
              name:
                type: string
                description: Display name of the participant.
                example: Scott
              end_time:
                type: integer
                description: Timestamp (in milliseconds) when the participant left the session.
                example: 1654797815323
              start_time:
                type: integer
                description: Timestamp (in milliseconds) when the participant joined the session.
                example: 1654794247047
              role:
                type: string
                description: Role of the participant in the session, such as host, speaker, or attendee.
                example: host
              id:
                type: string
                description: Unique identifier assigned to the participant within the session.
                example: '12543958'
      example:
        url: /api/v2/mediasessions/15093303_1654794155339_GN_1256255415498864798_15093376/participants
        type: participant
        data:
          - email_id: scott.fisher@zylker.com
            name: Scott
            end_time: 1654797815323
            start_time: 1654794247047
            role: host
            id: '12543958'
          - email_id: olivia.palmer@zylker.com
            name: Admin Account
            end_time: 1654794872529
            start_time: 1654794859243
            role: speaker
            id: '14395792'
  securitySchemes:
    Cliq_Auth:
      type: oauth2
      x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoCliq.MediaSession.READ: Read information about calls and meetings
