Tickets

Summary

Generates an AI summary of the ticket and its conversation and stores it as a new SUMMARY_AI conversation at the end of the thread, returning that conversation. The call waits for the model, counts against the workspace's AI usage, and is rejected when the newest item in the thread is already a summary; the summary is internal only, so it is never emailed to the requester and never used as context for suggested replies. A ticket locked by another User (see the lock endpoints) answers 423 Locked and no summary is generated.

POST /api/{tenant:minlength(2)}/v{version:apiVersion}/tickets/summary/{id}

Authorisation: Minimum role: USER

Request arguments

Name	Type	Source
id	Int32

Request body example

Response

Status: 200 (OK)
Type: DTO_ticket_conversation

Wrapper: DTO_response_wrap

Other statuses: 400 (BadRequest), 401 (Unauthorized), 403 (Forbidden), 404 (NotFound), 409 (Conflict), 423 (Locked), 429 (TooManyRequests)

Response body example

DTO_ticket_conversation

Name	Type	ReadOnly	Description
sys_status	DTO_reference_color		Status to move the parent ticket to as this message is created, where only one status may be supplied across the messages sent in a single call
created_by	DTO_reference_user	ReadOnly	The User who wrote the message, null when it came from someone who is not a User in the workspace
last_updated_by	DTO_reference_user	ReadOnly	The User who last edited the message, null while it has not been edited since it was created
requester	DTO_contact		The contact who sent the message, set on messages that arrived from outside and null on messages written in Deskhero
last_message_extracted	String		Only the new text of an inbound email with the quoted thread beneath it stripped away, lines joined with HTML line breaks, null when nothing could be isolated (heavily formatted HTML mail, for example)
sys_attachments	DTO_reference_attachment[]		Files attached to this message, each referenced by its attachment id
based_on_suggested_reply_id	Int32 (nullable)		Optional, only read on outbound replies: the id of the suggested reply this reply was written from. Together with suggestion_state it measures how useful suggested replies are; an id that is not a suggested reply on this ticket is ignored.
id	Int32	ReadOnly	Id of this message, assigned by Deskhero from a different sequence than the ticket number in ticket_id
ticket_id	Int32		The number of the ticket this message belongs to
created	DateTime	ReadOnly	When the message was added to the ticket, in UTC
last_updated	DateTime	ReadOnly	When the message was last written to, in UTC
type	ENUM ticket_conversation_type		What kind of message this is: REPLY_INBOUND and REPLY_OUTBOUND for email replies, NOTE_PRIVATE and NOTE_PUBLIC for notes, FORWARD, SUGGESTED_REPLY for an AI draft, AUTO_REPLY_AI and AUTO_REPLY_STATIC for automatic answers, CHAT_USER and CHAT_BOT for chat-bot messages, and SUMMARY_AI for an AI recap of the thread that an agent asked for.
email_addresses	DTO_email_address[]		Addresses on the message, holding sender and recipients for mail that arrived and the TO, CC and BCC recipients (at most 20, or 3 on the free plan) when sending a reply
sys_content_rich	DTO_rich_text		Body of the message, carried as rich text in whichever of the html, tiptap and editorjs representations was stored
history_mode	ticket_conversation_history_mode (nullable)		Only read on outbound replies. Omit it or send INCLUDE_HISTORY to quote the earlier messages and the original ticket text below the reply as usual; NO_HISTORY sends the reply alone, without any of them. Returned on stored replies so the thread can show which ones went out without history.
suggestion_state	suggestion_state (nullable)		Optional, only read on outbound replies together with based_on_suggested_reply_id: what the User did with the suggested reply before sending (NOT_SHOWN, ACCEPTED_UNCHANGED, ACCEPTED_EDITED, DISMISSED, REPLACED_BY_CANNED or TRANSLATED). It never changes what is sent.
follow_up	DTO_ticket_follow_up_input		Optionally schedules a per-ticket status change with this outbound reply. Supply an operation UUID and reuse it for retries. Only one outbound reply is allowed when scheduling.

DTO_reference_color

Name	Type	ReadOnly	Description
bg_color	String	ReadOnly	Bg color
text_color	String	ReadOnly	Text color
id	Int32		Id
label	Object	ReadOnly	Label

DTO_reference_user

Name	Type	ReadOnly	Description
profile_pic	String	ReadOnly	Profile pic
email	String	ReadOnly	Email
id	Int32		Id
label	Object	ReadOnly	Label

DTO_contact

Name	Type	Description
user_id	Int32	User id
email	String	Email
name	String	Name
profile_pic	String	Profile pic

DTO_reference_attachment

Name	Type	ReadOnly	Description
size_kb	Int32	ReadOnly	Size kb
status	ENUM attachment_status	ReadOnly	Status
status_message	String	ReadOnly	Status message
download_url	String	ReadOnly	Download url
id	Int32		Id
label	Object	ReadOnly	Label

DTO_email_address

Name	Type	Description
email	String	Email
name	String	Name
direction	ENUM email_address_direction	Direction

DTO_rich_text

Name	Type	ReadOnly	Description
plain_preview	String	ReadOnly	Plain preview
html	String		Html
editorjs	DTO_editorjs		Editorjs
tiptap	DTO_tiptap		Tiptap
read_minutes	Int32		Read minutes

DTO_editorjs

Name	Type	Description
time	Int64	Time
version	String	Version
blocks	DTO_editorjs_block[]	Blocks

DTO_editorjs_block

Name	Type	Description
id	String	Id
type	String	Type
data	Object	Data

DTO_tiptap

Name	Type	ReadOnly	Description
type	String		Type
content	DTO_tiptap_node[]		Content

DTO_tiptap_node

Name	Type	Description
type	String	Type
attrs	DTO_tiptap_attrs	Attrs
content	DTO_tiptap_node[]	Content
text	String	Text
marks	DTO_tiptap_mark[]	Marks

DTO_tiptap_attrs

Name	Type	Description
textAlign	String	Textalign
level	Int32 (nullable)	Level
checked	Boolean (nullable)	Checked
id	Int32 (nullable)	Id
alt	String	Alt
title	String	Title
width	String	Width
wrapperStyle	String	Wrapperstyle
containerStyle	String	Containerstyle
files	DTO_tiptap_file_ref[]	Files
href	String	Href
target	String	Target
colspan	Int32 (nullable)	Colspan
rowspan	Int32 (nullable)	Rowspan
color	String	Color
text	String	Text
name	String	For emoji
native	String	For emoji

DTO_tiptap_file_ref

Name	Type	ReadOnly	Description
id	Int32		Id
label	String		Label

DTO_tiptap_mark

Name	Type	ReadOnly	Description
type	String		Type
attrs	DTO_tiptap_attrs		Attrs

DTO_ticket_follow_up_input

Name	Type	Description
operation_id	String	Unique operation UUID. Reuse it when retrying the same request.
expected_version	String	Version of the saved follow-up being edited, or null when creating one.
target_status_id	Int32	Workspace status id to move to when no customer reply has arrived.
due_at	DateTimeOffset	Future deadline with a UTC offset. Checked every two minutes.

ENUM attachment_status

Value	Name	Description
0	UNKNOWN	UNKNOWN
1	UNAVAILABLE	UNAVAILABLE, processing in progress
2	OK	OK
3	WARNING	WARNING
4	ERROR	ERROR

ENUM email_address_direction

Value	Name	Description
0	UNKNOWN	UNKNOWN
1	FROM	FROM
2	TO	TO
3	CC	CC
4	BCC	BCC
5	FORWARDED_TO	FORWARDED_TO
6	RESENT_FROM	RESENT_FROM
7	REPLY_TO	REPLY_TO

ENUM ticket_conversation_type

Value	Name	Description
0	UNKNOWN	UNKNOWN
1	REPLY_INBOUND	REPLY_INBOUND
2	NOTE_PRIVATE	NOTE_PRIVATE
3	NOTE_PUBLIC	NOTE_PUBLIC
4	FORWARD	FORWARD
5	REPLY_OUTBOUND	REPLY_OUTBOUND
6	SUGGESTED_REPLY	SUGGESTED_REPLY
7	AUTO_REPLY_AI	AUTO_REPLY_AI
8	AUTO_REPLY_STATIC	AUTO_REPLY_STATIC
9	CHAT_USER	CHAT_USER
10	CHAT_BOT	CHAT_BOT
11	SUMMARY_AI	AI-generated recap of the whole thread, requested by a User from the ticket view. Internal only: never emailed, never fed back into AI context, and not counted as a reply.

Generated Sep 29, 2026 15:11