Ticket comments represent the conversation between requesters, collaborators, and agents. Comments can be public or private.

For information on comments in requests as opposed to tickets, see Request comments.

Creating ticket comments

Ticket comments, including voice comments, are created with the Tickets API, not the Ticket Comments API described in this document. The Tickets Comments API has no endpoint to create comments.

Ticket comments are created by including a comment object in the ticket object when creating or updating the ticket. Example:

curl https://{subdomain}.zendesk.com/api/v2/tickets/{id}.json \  -d '{"ticket": {"comment": { "body": "The smoke is very colorful.", "author_id": 494820284 }}}' \  -H "Content-Type: application/json" \  -v -u {email_address}:{password} -X PUT

To learn more, see Adding voice comments to tickets.

See also the following reference documentation:

JSON Format

Ticket Comments are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
attachments array true false Attachments, if any. See Attachment
author_id integer false false The id of the comment author. See Author id
body string false false The comment string
created_at string true false The time the comment was created
html_body string false false The comment formatted as HTML
id integer true false Automatically assigned when the comment is created
metadata object true false System information (web client, IP address, etc.) and comment flags, if any. See Comment flags
plain_body string true false The comment as plain text
public boolean false false true if a public comment; false if an internal note. The initial value set on ticket creation persists for any additional comment unless you change it
type string true false Comment or VoiceComment. The JSON object for adding voice comments to tickets is different. See Adding voice comments to tickets
uploads array false false List of tokens received from uploading files for comment attachments. The files are attached by creating or updating tickets with the tokens. See Attaching files in Tickets
via object false false Describes how the object was created. See the Via object reference

Author id

If you set the author_id, the user with the id is shown as the author of the comment. However, this user is not considered the updater of the ticket. The authenticated user making the API request is the updater. This has implications for business rules and views, such as the requester updated attribute and current user conditions.

Comment flags

Each comment can be flagged by Zendesk for several reasons. If the comment is flagged, the metadata property will have a flags array with any of the following values:

Value Reason for flag
0 Zendesk is unsure the comment should be trusted
2 The comment author was not part of the conversation. Learn more
3 The comment author was not signed in when the comment was submitted. Learn more
4 The comment was automatically generated. Automatic email notifications have been suppressed. Learn more
5 The attached file was rejected because it's too big
11 This comment was submitted by the user on behalf of the author. See Requesters and submitters
14 This message might not have been sent by the user
16 Requester's name has been truncated. Please edit the name or mark as spam
17 This is a private comment created by an end user. Learn more
18 Some email recipients were excluded from CCs due to the limit of CCs per email. View the original email for the full list. Learn more
20 To protect your agents, we suspended the ability of the user in this Reply-to address to perform certain actions. Learn more
21 We flagged this comment because the From and Reply-to in the messages don’t match. See Reply-to addresses
22 User has yet to confirm ownership of the address used to deliver the email. Learn more

A flags_options object will also be included with additional information about the flags.

The flags and flags_options properties are omitted if there are no flags.

Example

metadata: {  system: { ... },  flags: [2,5],  "flags_options": {    "2": {      "trusted": false    },    "5": {      "message": {        "file": "printer_manual.pdf",        "account_limit": "20"      },      "trusted": false    }  },  "trusted": false,  "suspension_type_id": null}

Example

{  "attachments": [    {      "content_type": "text/plain",      "content_url": "https://company.zendesk.com/attachments/crash.log",      "file_name": "crash.log",      "id": 498483,      "size": 2532,      "thumbnails": []    }  ],  "author_id": 123123,  "body": "Thanks for your help!",  "created_at": "2009-07-20T22:55:29Z",  "id": 1274,  "metadata": {    "system": {      "client": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36",      "ip_address": "1.1.1.1",      "latitude": -37.000000000001,      "location": "Melbourne, 07, Australia",      "longitude": 144.0000000000002    },    "via": {      "channel": "web",      "source": {        "from": {},        "rel": "web_widget",        "to": {}      }    }  },  "public": true,  "type": "Comment"}

List Comments

  • GET /api/v2/tickets/{ticket_id}/comments

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.

Allowed For

  • Agents

Parameters

Name Type In Required Description
include string Query false 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.
include_inline_images boolean Query false Default is false. When true, inline images are also listed as attachments in the response
sort_order string Query false One of asc, desc. Defaults to asc
ticket_id integer Path true The ID of the ticket

Using curl

curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/comments.json \  -H "Content-Type: application/json" -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "comments": [    {      "attachments": [        {          "content_type": "text/plain",          "content_url": "https://company.zendesk.com/attachments/crash.log",          "file_name": "crash.log",          "id": 498483,          "size": 2532,          "thumbnails": []        }      ],      "author_id": 123123,      "body": "Thanks for your help!",      "created_at": "2009-07-20T22:55:29Z",      "id": 1274,      "metadata": {        "system": {          "client": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36",          "ip_address": "1.1.1.1",          "latitude": -37.000000000001,          "location": "Melbourne, 07, Australia",          "longitude": 144.0000000000002        },        "via": {          "channel": "web",          "source": {            "from": {},            "rel": "web_widget",            "to": {}          }        }      },      "public": true,      "type": "Comment"    }  ]}

Make Comment Private

  • PUT /api/v2/tickets/{ticket_id}/comments/{ticket_comment_id}/make_private

Allowed For

  • Agents

Parameters

Name Type In Required Description
ticket_comment_id integer Path true The ID of the ticket comment
ticket_id integer Path true The ID of the ticket

Using curl

curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/comments/{ticket_comment_id}/make_private.json \  -v -u {email_address}:{password} -X PUT -d '{}' -H "Content-Type: application/json"

Example Response

Status 200 OK

Redact Ticket Comment In Agent Workspace

  • PUT /api/v2/comment_redactions/{ticket_comment_id}

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 <redact> tags. Example:

{  "html_body": "<div class=\"zd-comment\" dir=\"auto\">My ID number is <redact>847564</redact>!</div>"}

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

To redact inline images and anchor tags, add the individual attribute redact to the element. Example: <a href="http://example.com" redact>some link</a>.

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 Messaging tickets

  • 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. Deleting tickets must be enabled for agents.

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 <redact> 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

Parameters

Name Type In Required Description
ticket_comment_id integer Path true The ID of the ticket comment

Using curl

curl https://{subdomain}.zendesk.com/api/v2/comment_redactions/{ticket_comment_id}.json \  -H "Content-Type: application/json" -v -u {email_address}:{password} -X PUT \  -d '{"html_body":"<div class=\"zd-comment\" dir=\"auto\">My ID number is <redact>847564</redact>!</div>", "ticket_id": 100 }'

Example Response

Status 200 OK
{  "comment": {    "attachments": [],    "author_id": 123,    "id": 100,    "plain_body": "My ID number is ▇▇▇▇!",    "public": true,    "type": "Comment"  }}

Redact Chat Comment

  • PUT /api/v2/chat_redactions/{ticket_id}

Permanently removes words or strings from a chat ticket's comment.

Wrap <redact> tags around the content in the chat comment you want redacted. Example:

{  "text": "My ID number is <redact>847564</redact>!"}

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 true The chat_index in the ChatMessage event in the ticket audit. See Ticket Audits
text string true The message in the ChatMessage event in the ticket audit. See Ticket Audits. Wrap message with <redact> tags

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

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!"            }          ]        }      }    ]  ]}

Parameters

Name Type In Required Description
ticket_id integer Path true The ID of the ticket

Using curl

curl https://{subdomain}.zendesk.com/api/v2/chat_redactions/{ticket_id}.json \  -H "Content-Type: application/json" -v -u {email_address}:{password} -X PUT \  -d '{"chat_id":"2109.10502823.Sjuj2YrBpXwei", "chat_index": 0, "text": My ID number is <redact>847564</redact>!" }'

Example Response

Status 200 OK
{  "chat_event": {    "id": 1932802680168,    "type": "ChatStartedEvent",    "value": {      "chat_id": "2109.10502823.Sjuj2YrBpXwei",      "history": [        {          "chat_index": 0,          "message": "My ID number is ▇▇▇▇!",          "type": "ChatMessage"        }      ],      "visitor_id": "10502823-16EkM3T6VNq7KMd"    }  }}

Redact Chat Comment Attachment

  • PUT /api/v2/chat_file_redactions/{ticket_id}

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 true The array of chat_index in the ChatFileAttachment event in the ticket audit. See Ticket Audits

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

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"            }          ]        }      }    ]  ]}

Parameters

Name Type In Required Description
ticket_id integer Path true The ID of the ticket

Using curl

curl https://{subdomain}.zendesk.com/api/v2/chat_redactions/{ticket_id}.json \  -H "Content-Type: application/json" -v -u {email_address}:{password} -X PUT \  -d '{"chat_id":"2109.10502823.Sjuj2YrBpXwei", "chat_indexes": [0,1] }'

Example Response

Status 200 OK
{  "chat_event": {    "id": 1932802680168,    "type": "ChatStartedEvent",    "value": {      "chat_id": "2109.10502823.Sjuj2YrBpXwei",      "history": [        {          "chat_index": 0,          "filename": "redacted.txt",          "type": "ChatFileAttachment"        },        {          "chat_index": 1,          "filename": "redacted.txt",          "type": "ChatFileAttachment"        }      ],      "visitor_id": "10502823-16EkM3T6VNq7KMd"    }  }}

Redact String in Comment

  • PUT /api/v2/tickets/{ticket_id}/comments/{ticket_comment_id}/redact

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

Parameters

Name Type In Required Description
ticket_comment_id integer Path true The ID of the ticket comment
ticket_id integer Path true The ID of the ticket

Using curl

curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/comments/{ticket_comment_id}/redact.json \  -H "Content-Type: application/json" -v -u {email_address}:{password} -X PUT \  -d '{"text": "987-65-4320"}'

Example Response

Status 200 OK
{  "comment": {    "author_id": 1,    "id": 35436,    "plain_body": "My social security number is ▇▇▇▇!",    "type": "Comment"  }}