openapi: 3.1.0
info:
  title: Helpcenter TicketFollowers API
  version: 1.0.0
tags:
- name: TicketFollowers
paths:
  /api/v1/tickets/{ticketId}/removeFollowers:
    post:
      tags:
      - TicketFollowers
      summary: Remove ticket followers
      description: This API removes one or more users from the followers list of a ticket.
      operationId: removeTicketFollowers
      parameters:
      - $ref: '#/components/parameters/ticketId'
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/removeFollowers'
      responses:
        '422':
          $ref: ./Common.json#/components/responses/multipleUnprocessEntityResponse
        '404':
          $ref: ./errors.json#/components/responses/commonErrorResponse
        '204':
          $ref: ./Common.json#/components/responses/emptyResponse
      security:
      - iam-oauth2-schema:
        - Desk.tickets.UPDATE
      x-audience:
      - external-public
  /api/v1/tickets/{ticketId}/addFollowers:
    post:
      tags:
      - TicketFollowers
      summary: Add ticket followers
      description: This API adds one or more users to the followers list of a ticket.
      operationId: addTicketFollowers
      parameters:
      - $ref: '#/components/parameters/ticketId'
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/addFollowers'
      responses:
        '422':
          $ref: ./Common.json#/components/responses/multipleUnprocessEntityResponse
        '404':
          $ref: ./errors.json#/components/responses/commonErrorResponse
        '204':
          $ref: ./Common.json#/components/responses/emptyResponse
      security:
      - iam-oauth2-schema:
        - Desk.tickets.UPDATE
      x-audience:
      - external-public
  /api/v1/tickets/{ticketId}/followers:
    get:
      tags:
      - TicketFollowers
      summary: Get ticket followers
      description: This API fetches the list of users following a ticket. <br/></br/>_Note:_<br/>Sometimes, followers of a contact/account indirectly end up as ticket followers if the ticket is associated with the contact/account they follow. In that case, the _following_ key returns the value of the original module the user follows--*contact* or account. <br/></br/>Even in a case where the user first followed the ticket and then followed the contact/account associated with it, the following key returns the value contact or account. This is because the contact/account is the parent resource of the ticket.
      operationId: getTicketFollowers
      parameters:
      - $ref: '#/components/parameters/ticketId'
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '422':
          $ref: ./Common.json#/components/responses/multipleUnprocessEntityResponse
        '200':
          $ref: '#/components/responses/getFollowersResponse'
      security:
      - iam-oauth2-schema:
        - Desk.tickets.READ
      x-audience:
      - external-public
components:
  requestBodies:
    removeFollowers:
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              followerIds:
                type:
                - 'null'
                - array
                items:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  pattern: ([0-9]+)
                uniqueItems: true
            required:
            - followerIds
          examples:
            Valid requestBody Definitions:
              value:
                followerIds:
                - 5000000013292
    addFollowers:
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              followerIds:
                type:
                - 'null'
                - array
                items:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  pattern: ([0-9]+)
                uniqueItems: true
            required:
            - followerIds
          examples:
            Valid requestBody Definitions:
              value:
                followerIds:
                - 5000000013292
  responses:
    getFollowersResponse:
      description: getFollowersResponse template definitions
      content:
        application/json:
          schema:
            oneOf:
            - type:
              - 'null'
              - object
              additionalProperties: false
              properties:
                data:
                  $ref: ./TicketFollowers.json#/components/schemas/followersDataResponse
              required:
              - data
            - type:
              - 'null'
              - object
              additionalProperties: false
              properties:
                errorCode:
                  type:
                  - string
                  - 'null'
                  enum:
                  - URL_NOT_FOUND
                  - UNAUTHORIZED
                  - INVALID_OAUTH
                  - SCOPE_MISMATCH
                  - FORBIDDEN
                  - LICENSE_ACCESS_LIMITED
                  - METHOD_NOT_ALLOWED
                  - RESOURCE_SIZE_EXCEEDED
                  - UNSUPPORTED_MEDIA_TYPE
                  - INVALID_DATA
                  - UNPROCESSABLE_ENTITY
                  - ONLY_LIVECHAT_USER
                  - INTEGRATION_ADMIN_ERROR
                  - THRESHOLD_EXCEEDED
                  - INTERNAL_SERVER_ERROR
                  - EMPTY_PAYLOAD
                  maxLength: 100
                  minLength: 0
                message:
                  type:
                  - string
                  - 'null'
                  maxLength: 255
                  minLength: 0
              required:
              - errorCode
              - message
          examples:
            Valid responses Definitions:
              value:
                data:
                - firstName: ''
                  lastName: agent
                  photoURL: https://desk.zoho.com/api/v1/agent/5000000012903/photo
                  following: ticket
                  id: '5000000012903'
                  email: agent@zylker.com
                - firstName: ''
                  lastName: deskagent
                  photoURL: https://desk.zoho.com/api/v1/agent/5000000012902/photo
                  following: contact
                  id: '5000000012902'
                  email: deskagent@zylker.com
  parameters:
    ticketId:
      name: ticketId
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type:
        - string
        - 'null'
        - integer
        format: int64
        pattern: ([0-9]+)
  securitySchemes:
    iam-oauth2-schema:
      $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema
x-entity: Helpcenter