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

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
uploads array no 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 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. 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: "[email protected]",
            name: "End-user",
            original_recipients: [
              "[email protected]",
              "[email protected]",
              "[email protected]"
            ]
          },
          to: {
            name: "Support",
            address: "[email protected]"
            email_ccs: [
              847390,
              1234567,
              "[email protected]"
            ]
          },
          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": "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
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": "987-65-4320"}'
Example Response
 
Status: 200 OK

{
  "comment": {
    "id":    35436,
    "value": "My social security 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