Ticket Comments

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

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

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

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

Support API

Ticket Comments

Creating ticket comments

JSON Format

Author id

Comment flags

Example

List Comments

Allowed For

Parameters

Using curl

Example Response

Make Comment Private

Allowed For

Parameters

Using curl

Example Response

Redact String in Comment

Allowed For

Parameters

Using curl

Example Response