Zendesk Ticket Comments API

openapi: 3.2.0
info:
  title: Zendesk Ticket Comments API
  version: '1.0'
  description: 'Operations tagged Ticket Comments across 4 of this provider''s published API definitions: chat-file-redactions-openapi-original.yml, chat-redactions-openapi-original.yml, comment-redactions-openapi-original.yml, tickets-openapi-original.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Ticket Comments
paths:
  /api/v2/chat_file_redactions/{ticket_id}:
    parameters:
    - $ref: '#/components/parameters/TicketId'
    put:
      operationId: RedactChatCommentAttachment
      tags:
      - Ticket Comments
      summary: Zendesk Put Api V2 Chat_file_redactions Ticket_id
      description: 'Permanently removes one or more chat attachments from a chat ticket.


        **Note**: This does not work on active chats. For chat tickets that predate March 2020, consider using Redact Ticket Comment In Agent Workspace.


        #### Allowed For


        - Agents


        Agent Workspace must enabled for the account. Deleting tickets must be enabled for agents.


        #### Request Body Properties


        | Name | Type | Required | Description |

        | ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

        | chat_id | string | true | The `chat_id` in the `ChatStartedEvent` event in the ticket audit. See Ticket Audits |

        | chat_indexes | array | false | The array of `chat_index` in the `ChatFileAttachment` event in the ticket audit. See Ticket Audits. Mandatory if `message_ids` is not used |

        | message_ids | array | false | The array of `message_id` in the `ChatFileAttachment` event in the ticket audit that is part of a `ChatStartedEvent` history. Used when redacting a ChatFileAttachment that is part of a conversation history. Mandatory if `chat_indexes` is not used |


        To get the required body properties, make a request to the Ticket Audits endpoint. Example response:


        ```http

        Status 200 OK

        {

        "audits": [

        "events": [

        {

        "id": 1932802680168,

        "type": "ChatStartedEvent",

        "value": {

        "visitor_id": "10502823-16EkM3T6VNq7KMd",

        "chat_id": "2109.10502823.Sjuj2YrBpXwei",

        "history": [

        {

        "chat_index": 0,

        "type": "ChatFileAttachment",

        "filename": "image1.jpg"

        },

        {

        "chat_index": 1,

        "type": "ChatFileAttachment",

        "filename": "image2.jpg"

        }

        ]

        }

        }

        ]

        ]

        }

        ```'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketChatCommentRedactionResponse'
              examples:
                default:
                  $ref: '#/components/examples/TicketChatCommentAttachmentRedactionResponseExample'
  /api/v2/chat_redactions/{ticket_id}:
    parameters:
    - $ref: '#/components/parameters/TicketId'
    put:
      operationId: RedactChatComment
      tags:
      - Ticket Comments
      summary: Zendesk Put Api V2 Chat_redactions Ticket_id
      description: 'Permanently removes words or strings from a chat ticket''s comment.


        Wrap `` tags around the content in the chat comment you want redacted. Example:


        ```json

        {

        "text": "My ID number is 847564!"

        }

        ```


        The characters contained in the tag will be replaced by the ▇ symbol.


        **Note**: This does not work on active chats. For chat tickets that predate March 2020, consider using Redact Ticket Comment In Agent Workspace.


        #### Allowed For


        - Agents


        Agent Workspace must enabled for the account. Deleting tickets must be enabled for agents.


        #### Request Body Properties


        | Name | Type | Required | Description |

        | ------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

        | chat_id | string | true | The `chat_id` in the `ChatStartedEvent` event in the ticket audit. See Ticket Audits |

        | chat_index | integer | false | The `chat_index` in the `ChatMessage` event in the ticket audit. See Ticket Audits. Mandatory if `message_id` is not used |

        | message_id | string | false | The `message_id` of the `ChatMessage` event in the ticket audit that is part of a `ChatStartedEvent` history. Used when redacting a ChatMessage that is part of a conversation history. Mandatory if `chat_index` is not used |

        | text | string | true | The `message` in the `ChatMessage` event in the ticket audit. See Ticket Audits. Wrap `message` with `` tags |


        To get the required body properties, make a request to the Ticket Audit endpoint. Example response:


        ```http

        Status 200 OK

        {

        "audits": [

        "events": [

        {

        "id": 1932802680168,

        "type": "ChatStartedEvent",

        "value": {

        "visitor_id": "10502823-16EkM3T6VNq7KMd",

        "chat_id": "2109.10502823.Sjuj2YrBpXwei",

        "history": [

        {

        "chat_index": 0,

        "type": "ChatMessage",

        "message": "My ID number is 847564!"

        }

        ]

        }

        }

        ]

        ]

        }

        ```'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketChatCommentRedactionResponse'
              examples:
                default:
                  $ref: '#/components/examples/TicketChatCommentRedactionResponseExample'
  /api/v2/comment_redactions/{ticket_comment_id}:
    parameters:
    - $ref: '#/components/parameters/TicketCommentId'
    put:
      operationId: RedactTicketCommentInAgentWorkspace
      tags:
      - Ticket Comments
      summary: Zendesk Put Api V2 Comment_redactions Ticket_comment_id
      description: 'Redaction allows you to permanently remove words, strings, or attachments from a ticket comment.


        In the `html_body` of the comment, wrap the content you want redacted in `` tags. Example:


        ```json

        {

        "html_body": "

        My ID number is 847564!

        ",

        "ticket_id":100

        }

        ```


        The characters in the redact tag will be replaced by the ▇ symbol.


        To redact HTML elements such inline images, anchor tags, and links, add the `redact` tag attribute to the element as well as the `` tag to inner text, if any. Example:


        `some link`


        The `redact` attribute only redacts the tag. Any inner text will be left behind if not enclosed in a `` tag.


        Redaction is permanent and can not be undone. Data is permanently deleted from Zendesk servers with no way to recover it.


        This endpoint provides all the same functionality that the Redact String in Comment endpoint provides, plus:


        - Redaction of comments in closed tickets


        - Redaction of comments in archived tickets


        - Redaction of formatted text (bold, italics, hyperlinks)


        **Limitations**: When content is redacted from an email comment, the content is also redacted from the original email through a background job. It may take a while for the changes to be completed.


        **Note**: We recommend using this endpoint instead of the Redact String in Comment endpoint, which will eventually be deprecated.


        #### Allowed For


        - Agents


        Agent Workspace must be enabled on the account. For professional accounts, deleting tickets must be enabled for agents. On Enterprise accounts, you can assign agents to a custom role with permissions to redact ticket content.


        #### Request Body Properties


        | Name | Type | Required | Description |

        | -------------------------| ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |

        | ticket_id | integer | true | The ID of the ticket |

        | html_body | string | false | The `html_body` of the comment containing `` tags or `redact` attributes |

        | external_attachment_urls | array | false | Array of attachment URLs belonging to the comment to be redacted. See `content_url` property of Attachment |'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketCommentResponse'
              examples:
                default:
                  $ref: '#/components/examples/TicketCommentsRedactionInAgentWorkspaceResponseExample'
  /api/v2/tickets/{ticket_id}/comments:
    parameters:
    - $ref: '#/components/parameters/TicketId'
    get:
      operationId: ListTicketComments
      tags:
      - Ticket Comments
      summary: Zendesk Get Api V2 Tickets Ticket_id Comments
      description: 'Returns the comments added to the ticket.


        Each comment may include a `content_url` for an attachment or a `recording_url` for a voice comment that points to a file that may be hosted externally. For security reasons, take care not to inadvertently send Zendesk authentication credentials to third parties when attempting to access these files. See Working with url properties.


        #### Pagination


        - Cursor pagination (recommended)

        - Offset pagination


        See Pagination.


        Returns a maximum of 100 records per page.


        #### Sorting


        By default, comments are sorted by creation date in ascending order.


        When using cursor pagination, use the following parameter to change the sort order:


        | Name | Type | Required | Comments

        | ------ | ------ | -------- | --------

        | `sort` | string | no | Possible values are "created_at" (ascending order) or "-created_at" (descending order)


        When using offset pagination, use the following parameters to change the sort order:


        | Name | Type | Required | Comments

        | ------------ | ------ | -------- | --------

        | `sort_order` | string | no | One of `asc`, `desc`. Defaults to `asc`


        #### Allowed For


        * Agents'
      parameters:
      - name: include_inline_images
        in: query
        description: Default is false. When true, inline images are also listed as attachments in the response
        schema:
          type: boolean
      - name: include
        in: query
        description: 'Accepts "users". Use this parameter to list email CCs by side-loading users. Example: `?include=users`. **Note**: If the comment source is email, a deleted user will be represented as the CCd email address. If the comment source is anything else, a deleted user will be represented as the user name.'
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketCommentsResponse'
              examples:
                default:
                  $ref: '#/components/examples/TicketCommentsResponseExample'
  /api/v2/tickets/{ticket_id}/comments/{ticket_comment_id}/make_private:
    parameters:
    - $ref: '#/components/parameters/TicketId'
    - $ref: '#/components/parameters/TicketCommentId'
    put:
      operationId: MakeTicketCommentPrivate
      tags:
      - Ticket Comments
      summary: Zendesk Put Api V2 Tickets Ticket_id Comments Ticket_comment_id Make_private
      description: '#### Allowed For


        * Agents'
      responses:
        '200':
          description: description
          content:
            application/json:
              schema:
                type: string
                description: Empty response
                example: ''
              example: ''
  /api/v2/tickets/{ticket_id}/comments/{ticket_comment_id}/redact:
    parameters:
    - $ref: '#/components/parameters/TicketId'
    - $ref: '#/components/parameters/TicketCommentId'
    put:
      operationId: RedactStringInComment
      tags:
      - Ticket Comments
      summary: Zendesk Put Api V2 Tickets Ticket_id Comments Ticket_comment_id Redact
      description: 'Permanently removes words or strings from a ticket comment. Specify the string to redact in an object with a `text` property. Example: `''{"text": "987-65-4320"}''`. The characters of the word or string are replaced by the ▇ symbol.


        If the comment was made by email, the endpoint also attempts to redact the string from the original email retained by Zendesk for audit purposes.


        **Note**: If you use the rich text editor, support for redacting formatted text (bold, italics, hyperlinks) is limited.


        Redaction is permanent. You can''t undo the redaction or see *what* was removed. Once a ticket is closed, you can no longer redact strings from its comments.


        To use this endpoint, the "Agents can delete tickets" option must be enabled in the Zendesk Support admin interface at **Admin** > **Settings** > **Agents**.


        #### Allowed For


        * Agents'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketCommentResponse'
              examples:
                default:
                  $ref: '#/components/examples/TicketCommentStringRedactResponseExample'
  /api/v2/tickets/{ticket_id}/comments/count:
    get:
      operationId: CountTicketComments
      tags:
      - Ticket Comments
      summary: Zendesk Get Api V2 Tickets Ticket_id Comments Count
      description: 'Returns an approximate count of the comments added to the ticket. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours.


        The `count[refreshed_at]` property is a timestamp that indicates when the count was last updated.


        **Note**: When the count exceeds 100,000, `count[refreshed_at]` may occasionally be null.

        This indicates that the count is being updated in the background, and `count[value]` is limited to 100,000 until the update is complete.


        #### Allowed For

        * Agents'
      parameters:
      - $ref: '#/components/parameters/TicketId'
      responses:
        '200':
          description: Count of ticket comments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketCommentsCountResponse'
              examples:
                default:
                  $ref: '#/components/examples/TicketCommentsCountResponseExample'
components:
  schemas:
    TicketChatCommentRedactionResponse:
      type: object
      properties:
        chat_event:
          type: object
          description: Chat event object
          properties:
            id:
              type: integer
              description: Id assigned to the chat event object
              readOnly: true
            type:
              type: string
              description: Type of chat event
              readOnly: true
            value:
              type: object
              description: The value of the chat event object
              properties:
                chat_id:
                  type: string
                  description: Id of the chat session
                  readOnly: true
                history:
                  type: array
                  description: Chat events within the chat session
                  items:
                    type: object
                    additionalProperties: true
                visitor_id:
                  type: string
                  description: Id assigned to the visitor
                  readOnly: true
              readOnly: true
          readOnly: true
      example:
        chat_event:
          id: 1932802680168
          type: ChatStartedEvent
          value:
            chat_id: 2109.10502823.Sjuj2YrBpXwei
            history:
            - actor_id: 1900448983828
              actor_name: Visitor 36044085
              actor_type: end-user
              chat_index: 0
              timestamp: 1632470783218
              type: ChatJoin
            visitor_id: 10502823-16EkM3T6VNq7KMd
    TicketCommentResponse:
      type: object
      properties:
        comment:
          $ref: '#/components/schemas/TicketCommentObject'
    TicketCommentsCountResponse:
      type: object
      properties:
        count:
          type: object
          properties:
            refreshed_at:
              type: string
              format: date-time
            value:
              type: integer
    TicketCommentsResponse:
      type: object
      properties:
        comments:
          type: array
          items:
            $ref: '#/components/schemas/TicketCommentObject'
x-refined-from:
- chat-file-redactions-openapi-original.yml
- chat-redactions-openapi-original.yml
- comment-redactions-openapi-original.yml
- tickets-openapi-original.yml