This method allows you to post updates to a ticket. These updates can be either public or private however the ticket must exist before you can post an update.

URL

/api/v2/tickets/post_update

Access

This method can be accessed by account tokens and user tokens where the associated user has access to the tickets UI.

Supported Parameters

• ticket - the reference for the ticket you wish to post an update to (required)
• message - the contents of the message you wish to post (required)
• subject - the subject for the reply (optional, will use the ticket subject if not entered)
• authenticated - a boolean to define whether or not this update is "authenticated" (optional)
• posted_at - the date/time the updated was posted (optional, leave blank for the current time). Formatting details can be found on the Date/Time Formatting page.

Posting HTML content for ticket updates

If you also have an HTML version of your update (perhaps from an incoming HTML email) you can use the options below:

• html_body - the full HTML for the update
• html_safe - if this HTML should be displayed within the staff interface to your users, this value should be sent as '1'. If this is not sent, the HTML body will be escaped when displayed to the user.

Passing the author details

If you are authenticating with an account token, you must set who the author of your ticket update is. If you authenticate with a user token, any updates which you post will be associated with the user account associated with the token.

The author for a ticket update can either be a user or a contact (not both) - updates posted by users are those by a member of staff whereas contact updates are those posted by a contact.

• To post an update as a member of staff, you should send the user parameter containing the username or ID of the user.
• To post an update as a contact who already exists, you should send the contact parameter containing the contact's reference, name or ID.
• If you don't know the contact name/reference, you can pass author_name as well as author_email and the contact object will be looked up based on the e-mail address and if no contact exists, one will be created with the details provided.
• If you do not wish to link the update to a contact but wish to add an update with the supplied author_name/author_email, you can pass the skip_contact_lookup parameter to post an update with the passed name but without being linked to an existing contact.
• If none of these details are provided, the update will be posted as System.

Parsing ticket variables

If you are posting an update as a member of staff you have the option of sending ticket variables within the message parameter, which get parsed before posting.

• parse_ticket_variables - a boolean to define whether or not Sirportly should parse the message parameter for ticket variables

Linking attachments

If you have pre-uploaded attachments using the add_attachment method, you can pass the attachment's temporary tokens to link these uploaded files to your new ticket update.

• attachments - a comma separated list of attachment temporary tokens (optional)

Additional parameters for updates by users

If you pass a user parameter or you have authenticated with a user token, additional parameters may be passed to the ticket update. These parameters are not available for updates by contacts therefore will have no affect unless a user has been provided.

• private - a boolean to define whether or not this update is private or not
• macro - the name or ID of a macro to execute once this update has been posted
• outgoing - the e-mail address/twitter nickname to use when sending this update to the contact (must be configured). If no value is sent, the contents of the update will not be sent to the ticket recipient(s).

Returned Data

If the update is posted successfully, you will receive a 201 Created status and information about the ticket update will be provided. If a validation error occurs, you will receive a 422 Unprocessable Entity status along with an array of errors (see below)

Example JSON

A successful ticket update

{
  "id": 13,
  "subject": "Example API Ticket",
  "message": "Blah",
  "private": null,
  "posted_at": "2012-02-03T12:13:46+00:00",
  "author": {
    "id": 1,
    "username": "adam",
    "first_name": "Adam",
    "last_name": "Cooke",
    "email_address": "adam@atechmedia.com",
    "time_zone": "London",
    "created_at": "2012-02-02T16:09:55+00:00"
  },
  "from_name": null,
  "from_address": null,
  "minutes_since_reply_due": null,
  "minutes_since_resolution_due": null,
  "minutes_since_submission": "13.170776483333333",
  "minutes_since_last_reply": "1.0374597666666667",
  "signature_text": null,
  "authenticated": null,
  "attachments": [

  ]
}

A failed ticket update

{
  "errors": {
    "base": [
      "You must enter a message"
    ]
  }
}