openapi: 3.1.0
info:
version: '1.0'
title: Zendesk Account Account Settings Ticket Comments API
description: Needs a description.
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.\n\n**Note**: This does not work on active chats. For chat tickets that predate March 2020, consider using [Redact Ticket Comment In Agent Workspace](#redact-ticket-comment-in-agent-workspace).\n\n#### Allowed For\n\n- Agents\n\n[Agent Workspace](https://support.zendesk.com/hc/en-us/articles/360024218473) must enabled for the account. Deleting tickets must be enabled for agents.\n\n#### Request Body Properties\n\n| Name | Type | Required | Description |\n| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| chat_id | string | true | The `chat_id` in the `ChatStartedEvent` event in the ticket audit. See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits) |\n| chat_indexes | array | false | The array of `chat_index` in the `ChatFileAttachment` event in the ticket audit. See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits). Mandatory if `message_ids` is not used |\n| 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 |\n\nTo get the required body properties, make a request to the [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits) endpoint. Example response:\n\n```http\nStatus 200 OK\n{\n \"audits\": [\n \"events\": [\n {\n \"id\": 1932802680168,\n \"type\": \"ChatStartedEvent\",\n \"value\": {\n \"visitor_id\": \"10502823-16EkM3T6VNq7KMd\",\n \"chat_id\": \"2109.10502823.Sjuj2YrBpXwei\",\n \"history\": [\n {\n \"chat_index\": 0,\n \"type\": \"ChatFileAttachment\",\n \"filename\": \"image1.jpg\"\n },\n {\n \"chat_index\": 1,\n \"type\": \"ChatFileAttachment\",\n \"filename\": \"image2.jpg\"\n }\n ]\n }\n }\n ]\n ]\n}\n```\n"
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. \n\nWrap `<redact>` tags around the content in the chat comment you want redacted. Example: \n\n```json\n{\n \"text\": \"My ID number is <redact>847564</redact>!\"\n}\n```\n\nThe characters contained in the tag will be replaced by the ▇ symbol.\n\n**Note**: This does not work on active chats. For chat tickets that predate March 2020, consider using [Redact Ticket Comment In Agent Workspace](#redact-ticket-comment-in-agent-workspace).\n\n#### Allowed For\n\n- Agents\n\n[Agent Workspace](https://support.zendesk.com/hc/en-us/articles/360024218473) must enabled for the account. Deleting tickets must be enabled for agents.\n\n#### Request Body Properties\n\n| Name | Type | Required | Description |\n| ------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| chat_id | string | true | The `chat_id` in the `ChatStartedEvent` event in the ticket audit. See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits) |\n| chat_index | integer | false | The `chat_index` in the `ChatMessage` event in the ticket audit. See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits). Mandatory if `message_id` is not used |\n| 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 |\n| text | string | true | The `message` in the `ChatMessage` event in the ticket audit. See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits). Wrap `message` with `<redact>` tags |\n\nTo get the required body properties, make a request to the [Ticket Audit](/api-reference/ticketing/tickets/ticket_audits) endpoint. Example response:\n\n```http\nStatus 200 OK\n{\n \"audits\": [\n \"events\": [\n {\n \"id\": 1932802680168,\n \"type\": \"ChatStartedEvent\",\n \"value\": {\n \"visitor_id\": \"10502823-16EkM3T6VNq7KMd\",\n \"chat_id\": \"2109.10502823.Sjuj2YrBpXwei\",\n \"history\": [\n {\n \"chat_index\": 0,\n \"type\": \"ChatMessage\",\n \"message\": \"My ID number is 847564!\"\n }\n ]\n }\n }\n ]\n ]\n}\n```\n"
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.\n\nIn the `html_body` of the comment, wrap the content you want redacted in `<redact>` tags. Example:\n\n```json\n{\n \"html_body\": \"<div class=\\\"zd-comment\\\" dir=\\\"auto\\\">My ID number is <redact>847564</redact>!</div>\",\n \"ticket_id\":100\n}\n```\n\nThe characters in the redact tag will be replaced by the ▇ symbol.\n\nTo redact HTML elements such inline images, anchor tags, and links, add the `redact` tag attribute to the element as well as the `<redact>` tag to inner text, if any. Example: \n\n`<a href=\"http://example.com\" redact><redact>some link</redact></a>`\n\nThe `redact` attribute only redacts the tag. Any inner text will be left behind if not enclosed in a `<redact>` tag.\n\nRedaction is permanent and can not be undone. Data is permanently deleted from Zendesk servers with no way to recover it.\n\nThis endpoint provides all the same functionality that the [Redact String in Comment](/api-reference/ticketing/tickets/ticket_comments/#redact-string-in-comment) endpoint provides, plus:\n\n- Redaction of comments in closed tickets\n\n- Redaction of comments in archived tickets\n\n- Redaction of formatted text (bold, italics, hyperlinks)\n\n**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.\n\n**Note**: We recommend using this endpoint instead of the [Redact String in Comment](/api-reference/ticketing/tickets/ticket_comments/#redact-string-in-comment) endpoint, which will eventually be deprecated.\n\n#### Allowed For\n\n- Agents\n\n[Agent Workspace](https://support.zendesk.com/hc/en-us/articles/360024218473) 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.\n\n#### Request Body Properties\n\n| Name | Type | Required | Description |\n| -------------------------| ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |\n| ticket_id | integer | true | The ID of the ticket |\n| html_body | string | false | The `html_body` of the comment containing `<redact>` tags or `redact` attributes |\n| external_attachment_urls | array | false | Array of attachment URLs belonging to the comment to be redacted. See [`content_url` property of Attachment](/api-reference/ticketing/tickets/ticket-attachments/) |\n"
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](/documentation/ticketing/managing-tickets/working-with-url-properties).
#### Pagination
- Cursor pagination (recommended)
- Offset pagination
See [Pagination](/api-reference/introduction/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
TicketCommentsResponse:
type: object
properties:
comments:
type: array
items:
$ref: '#/components/schemas/TicketCommentObject'
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