Support API

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.

JSON Format

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

Name Type Read-only Comment
id integer yes Automatically assigned when the comment is created
type string yes Comment or VoiceComment. The JSON object for voice comments is different. See voice comment event for the format
body string no The comment string
html_body string no The comment formatted as HTML
plain_body string yes The comment as plain text
public boolean no 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
author_id integer no The id of the comment author. See Author id
attachments array yes Attachments, if any. See Attachment
via object yes How the comment was created. See Via Object
metadata object yes System information (web client, IP address, etc.) and comment flags, if any. See Comment flags
created_at date yes The time the comment was created
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
5 The attached file was rejected because it's too big
11 This comment was submitted by the user on behalf of the author. 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
 
{
  "id":        1274,
  "type":      "Comment"
  "body":      "Thanks for your help!",
  "public":    true,
  "created_at": "2009-07-20T22:55:29Z",
  "author_id": 123123,
  "attachments": [
    {
      "id":           498483,
      "file_name":    "crash.log",
      "content_url":  "https://company.zendesk.com/attachments/crash.log",
      "content_type": "text/plain",
      "size":         2532,
      "thumbnails":   []
    }
  ],
  "metadata": {
    ...
  },
  "via": {
    ...
  },
}

Create ticket comment

Ticket comments are created by including a comment object in the request body 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

See the following docs:

List Comments

GET /api/v2/tickets/{ticket_id}/comments.json

Allowed For
  • Agents
Available parameters
Name Type Required Comments
sort_order string no One of asc, desc. Defaults to asc
include_inline_images boolean no true or false
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": [
    {
      "id": 35436,
      "value": "My ticket comment",
      ...
    },
    {
      "id": 35437,
      "value": "My other ticket comment",
      ...
    }
  ]
}

List Email CCs for a Comment

Note: The CC and Followers feature is in beta and may change. You can learn more about the feature here.

GET /api/v2/tickets/{ticket_id}/comments.json?include=users

You can list email CCs by side-loading users.

Allowed For
  • Agents
Example Response
 
Status: 200 OK

{
  "comments": [
    {
      "id": 35436,
      "value": "My email ticket comment",
      "via": {
        channel: "email",
        source: {
          from: {
            address: "enduser@example.com",
            name: "End-user",
            original_recipients: [
              "agent@company.zendesk.com",
              "enduser@gmail.com",
              "deletedenduser@example.com"
            ]
          },
          to: {
            name: "Support",
            address: "support@company.zendesk.com"
            email_ccs: [
              847390,
              1234567,
              "deletedenduser@example.com"
            ]
          },
          rel: null
        }
      },
      ...
    },
    {
      "id": 35437,
      "value": "My agent UI ticket comment",
      "via": {
        channel: "web",
        source: {
          from: { },
          to: {
            email_ccs: [
              847390,
              1234567,
              "deletedendusername"
            ]
          },
          rel: null
        }
      },
      ...
    }
  ],
  "users": [
    {
      "id":                    847390,
      "name":                  "Johnny Agent",
      "role":                  "agent",
      ...
    },
    {
      "id":                    1234567,
      "name":                  "Jane Enduser",
      "role":                  "end-user",
      ...
    },

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

Redact String in Comment

PUT /api/v2/tickets/{ticket_id}/comments/{id}/redact.json

Permanently removes words or strings from a ticket comment. Specify the string to redact in an object with a text property. Example: '{"text": "credit-card-number"}'. The characters of the word or string are replaced by the ▇ symbol.

For voice comments, redaction only works on the transcription and not on the call details.

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/comments/{id}/redact.json \
  -H "Content-Type: application/json" -v -u {email_address}:{password} -X PUT \
  -d '{"text": "credit-card-number"}'
Example Response
 
Status: 200 OK

{
  "comment": {
    "id":    35436,
    "value": "My credit card number is ▇▇▇▇!",
    ...
  }
}

Status: 400 Bad Request

Text was not found in comment.

Make Comment Private

PUT /api/v2/tickets/{ticket_id}/comments/{id}/make_private.json

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/comments/{id}/make_private.json \
  -v -u {email_address}:{password} -X PUT -d '{}' -H "Content-Type: application/json"
Example Response
 
Status: 200 OK