Responses and tags API

This article and the rest of the API documentation in this section are written for a technical audience — integrators and developers connecting external systems to Tickiti. Familiarity with HTTP, REST, JSON and bearer-token authentication is assumed.

These endpoints act on a single response — a ticket’s message or a task’s note — the way the ticket page does: pin it, bring it back after it was deleted, tag members of staff on it, and read an email response exactly as it arrived. They also give a ticket’s share link. Editing, moving and deleting responses are in the Ticket operations API.

Each change is made by the same code as the ticket page, so ticket lists and any open copy of the ticket update at once. All endpoints are POST, take and return JSON, and use the response envelope described in the API overview.

Endpoints

Method & pathAbilityPurpose
POST /api/v1/tickets/response-pintickets:writePin or unpin a response
POST /api/v1/tickets/response-restoretickets:writeRestore a deleted response
POST /api/v1/tickets/tagstickets:readList a ticket’s @tags
POST /api/v1/tickets/tagtickets:writeTag members of staff on a response
POST /api/v1/tickets/tag-acktickets:writeAcknowledge a tag on yourself
POST /api/v1/tickets/external-linktickets:writeGet the ticket’s share link
POST /api/v1/tickets/responsetickets:readOne response by id, optionally with the email as it arrived

Write implies read. Only tickets/tag requires an Idempotency-Key header, because it notifies the people tagged; see Idempotency.

Who may do what

A call runs as the token’s owner, who must be able to see the ticket: its assignee (in person or as a member of the assigned team), a participant, or someone with access to its queue. Integration identities (the System user, API user accounts, and on a self-hosted installation sysadmins and superusers) work on tickets in every queue. On top of that:

  1. Restoring a deleted response needs an admin or someone with Manage on the ticket’s queue. Its author alone cannot bring it back.
  2. Acknowledging a tag is for the person tagged, and no one else.
  3. Only members of staff can be tagged.

Pin a response

POST /api/v1/tickets/response-pin

Body: response_id and pinned (true to pin, false to unpin). Pinned responses come first in the thread. The reply gives is_pinned and changed, which is false when the response was already as asked. A deleted response cannot be pinned. A task’s description is always pinned, above any other pinned note: unpinning it is refused with 422 refused (A task's description is always pinned.).

Restore a deleted response

POST /api/v1/tickets/response-restore

Body: response_id. Undoes tickets/response-delete or the ticket page’s Delete: the response comes back with its attachments, and the ticket’s thread records who restored it. Anyone with the ticket open sees it come back; nobody is notified. Anyone other than an admin or a manager of the ticket’s queue gets 403, the response’s author included. A response that is not deleted is refused (422 refused), and so is one whose ticket is deleted — restoring the ticket with tickets/restore brings its responses back with it.

To find deleted responses, call tickets/responses/query with include_deleted: true; each row there carries deleted. See Cross-ticket responses API.

Tags

Listing. tickets/tags takes ticket_number or ticket_id, and optional mine: true for only the token owner’s own tags. Tags come oldest first, each with its response_tag_id, the response_id it is on, the person tagged (email, name), for_me, is_acknowledged, the comment, who tagged them and when.

Tagging. tickets/tag takes response_id, emails (1 to 20 staff addresses) and an optional comment (up to 2,000 characters). It does what the ticket page’s Tag dialog does: each person becomes a participant, the ticket turns unread for them, they are notified, and the tag stays in front of them until they acknowledge it. An address that is not a member of staff is refused (422 validation_failed).

curl -X POST https://support.sole-provider.example/api/v1/tickets/tag \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 3f1c9a52-6d0e-4b7a-9c2f-81e4d5a7b6c0" \
  -H "Content-Type: application/json" \
  -d '{
    "response_id": 90412,
    "emails": ["[email protected]"],
    "comment": "Can you confirm the size 9 Kestrel Pro 3 is back in stock?"
  }'
{
  "ok": true,
  "data": {
    "ticket_number": "528641",
    "response_id": "90412",
    "response_tag_ids": ["2207"],
    "tagged": ["[email protected]"]
  }
}

Acknowledging. tickets/tag-ack takes response_tag_id and acknowledges a tag on the token’s owner; tickets/tags with mine: true lists theirs. The reply gives is_acknowledged and changed. A tag on anyone else is refused with 403.

Share link

POST /api/v1/tickets/external-link

Body: ticket_number or ticket_id, and optional response_id, one of the ticket’s responses, to open the link at. Returns the ticket’s share link — the same link the ticket page’s Copy link gives — creating it the first time it is asked for (created says which). The link is permanent and opens the ticket’s customer view to whoever holds it, so share it as you would the ticket itself. A task has no share link (422 refused).

{
  "ok": true,
  "data": {
    "ticket_number": "528641",
    "response_id": null,
    "url": "https://support.sole-provider.example/ticket/q8Z2kR4vXw",
    "created": false
  }
}

Read an email as it arrived

tickets/response returns one response by response_id (see Ticket operations API). For a response that came in by email it also reports mail_auth: what the receiving mail server concluded about the sender’s address — pass, fail, api when it was posted through the API in the sender’s name, so nothing checked the address, or null when it said nothing or the response did not come by email.

Its optional include list adds:

  1. original_html — the email exactly as it arrived, before Tickiti tidied it for the thread. has_original_html is false, and original_html null, when the stored body already is the original. Inline images stay as cid: references; each attachment in the response lists its cid, so the image can be fetched with tickets/attachment.
  2. reply_text — plain text of what the writer wrote, without the quoted history below it. plain_text keeps the whole body.

max_body_chars shortens each of them as it does html, and original_html_truncated / reply_text_truncated say when it did.

{ "response_id": 90388, "include": ["reply_text"], "max_body_chars": 4000 }