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

A ticket comment is represented as a JSON object named "comment" 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 adding voice comments to tickets is different. See JSON Format for Voice Comments
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

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

{
  "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": {
    ...
  },
}

JSON Format for Voice Comments

Instead of adding a written comment to a ticket, you can add a voice recording of a comment. In the agent interface, a voice comment includes controls to play or stop the voice recording:

You must provide a url to a hosted voice recording. Zendesk doesn't store the recording file: it stores a link to the file. The audio file must be a MP3 or WAV file.

A Talk account is not necessary to add voice comments to tickets.

To add a voice comment to a new or existing ticket, include a JSON object named "voice_comment" with the following properties:

Name	Type	Mandatory	Comment
from	string	yes	Incoming phone number
to	string	yes	Dialed phone number
recording_url	string	yes	URL of the recording. The audio file must be a MP3 or WAV file
started_at	date	yes	Timestamp of the call as a ISO 8601 string. Example: 2019-04-16T09:14:57Z
call_duration	integer	yes	Duration in seconds of the call
answered_by_id	integer	no	The agent who answered the call
transcription_text	string	no	Transcription of the call
location	string	no	Location of the caller

Adding a voice comment to a ticket is logged as a voice comment event in ticket audit logs.

Voice comments can also be added to tickets with the Create Voicemail Ticket endpoint in the Talk Partner Edition. See Creating a ticket based on a voicemail in the Talk Partner Edition developer guide.

Example

data.json file

{
  "ticket": {
    "voice_comment": {
      "from": "+16617480240",
      "to": "+16617480123",
      "recording_url": "http://yourdomain.com/recordings/1.mp3",
      "started_at": "2019-04-16T09:14:57Z",
      "call_duration": 42,
      "answered_by_id": 28765,
      "transcription_text": "The transcription of the call",
      "location": "Topeka, Kansas"
    }
  }
}

curl request

curl https://{subdomain}.zendesk.com/api/v2/tickets/{id}.json \
  -d @data.json \
  -H "Content-Type: application/json" -v -u {email_address}:{password} -X POST

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	Default is false. When true, inline images are also listed as attachments in the response

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

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

Support API

Ticket Comments

JSON Format

Author id

Comment flags

Example

JSON Format for Voice Comments

Example

Create ticket comment

List Comments

Allowed For

Available parameters

Using curl

Example Response

List Email CCs for a Comment

Allowed For

Example Response

Redact String in Comment

Allowed For

Using curl

Example Response

Make Comment Private

Allowed For

Using curl

Example Response