Organization API: Staff Support: Chat

Name	In	Type	Required	Description
`org_slug`	path	string	yes
`status`	query	string	no
`priority`	query	string	no
`q`	query	string	no
`page`	query	integer	no	Default: `1`.
`limit`	query	integer	no	Default: `20`.

Responses

Section titled Create customer conversation

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

A 200 response is a list; each item has these fields:

Field	Type
`[].id`	integer
`[].conversation_number`	integer
`[].scope`	string
`[].subject`	string
`[].status`	string
`[].priority`	string
`[].department`	string or null
`[].assigned_agent_id`	integer or null
`[].assigned_agent_name`	string or null
`[].user_id`	integer or null
`[].user_email`	string or null
`[].user_name`	string or null
`[].customer_id`	integer or null
`[].channel`	string
`[].email_from`	string or null
`[].last_message_at`	string (date-time) or null
`[].last_message_preview`	string or null
`[].tags`	array of string or null
`[].unread_count`	integer
`[].waiting_seconds`	integer or null
`[].sla_first_response_due_at`	string (date-time) or null
`[].sla_resolution_due_at`	string (date-time) or null
`[].sla_breached_first_response`	boolean
`[].sla_breached_resolution`	boolean
`[].first_response_at`	string (date-time) or null
`[].csat_score`	integer or null
`[].created_at`	string (date-time)
`[].updated_at`	string (date-time)
`[].is_free`	boolean or null
`[].viewers`	array of string
`[].escalated_tier`	integer or null
`[].customer_plan`	CustomerPlan or null
`[].customer_plan.key`	string
`[].customer_plan.name`	string
`[].customer_plan.support_level`	string or null
`[].customer_plan.first_response_minutes`	integer or null
`[].support_tier`	string or null
`[].managed`	boolean or null

Create customer conversation

POST /api/v1/orgs/{org_slug}/chat/conversations

Parameters

Name	In	Type	Required
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`subject`	string	yes
`department`	string or null	no
`priority`	string	no
`body`	string	yes
`service_id`	integer or null	no
`tags`	array of string or null	no
`client_request_id`	string or null	no

Responses

Section titled Get customer conversation

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 201 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

Get customer conversation

GET /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Upload customer attachment

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

Upload customer attachment

POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/attachments

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

multipart/form-data (required)

Field	Type	Required
`file`	string (binary)	yes

Responses

Section titled Download customer attachment

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Download customer attachment

GET /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/attachments/{attachment_id}

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`attachment_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Lets a thread show an image inline instead of a download link

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Lets a thread show an image inline instead of a download link

GET /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/attachments/{attachment_id}/thumbnail

Lets a thread show an image inline instead of a download link.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`attachment_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Close customer conversation

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Close customer conversation

POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/close

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Rate customer conversation

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

Rate customer conversation

POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/csat

Rating is only meaningful once the ticket is done, so it is refused while the conversation is still open.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`score`	integer	yes
`comment`	string or null	no

Responses

Section titled Get customer messages

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Get customer messages

GET /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/messages

Parameters

Name	In	Type	Required	Description
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes
`before_id`	query	integer	no
`after_id`	query	integer	no
`limit`	query	integer	no	Default: `50`.

Responses

Section titled Send customer message

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

A 200 response is a list; each item has these fields:

Field	Type
`[].id`	integer
`[].conversation_id`	integer
`[].sender_type`	string
`[].sender_id`	integer or null
`[].sender_name`	string or null
`[].body`	string or null
`[].content_type`	string
`[].is_internal`	boolean
`[].attachments`	array of AttachmentResponse
`[].attachments[].id`	integer
`[].attachments[].file_name`	string
`[].attachments[].file_size`	integer
`[].attachments[].mime_type`	string
`[].attachments[].created_at`	string (date-time)
`[].read_at`	string (date-time) or null
`[].created_at`	string (date-time)
`[].client_request_id`	string or null
`[].request`	object or null

Send customer message

POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/messages

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`body`	string	yes
`client_request_id`	string or null	no

Responses

Section titled Mark customer conversation read

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`id`	integer
`conversation_id`	integer
`sender_type`	string
`sender_id`	integer or null
`sender_name`	string or null
`body`	string or null
`content_type`	string
`is_internal`	boolean
`attachments`	array of AttachmentResponse
`attachments[].id`	integer
`attachments[].file_name`	string
`attachments[].file_size`	integer
`attachments[].mime_type`	string
`attachments[].created_at`	string (date-time)
`read_at`	string (date-time) or null
`created_at`	string (date-time)
`client_request_id`	string or null
`request`	object or null

Mark customer conversation read

POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/read

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`up_to_message_id`	integer or null	no

Responses

Section titled Reopen customer conversation

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Reopen customer conversation

POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/reopen

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Approve ticket request

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

Approve ticket request

POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/requests/{request_id}/approve

Share the logs asked for, or give the engineer who asked subuser access until the ticket closes.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`request_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Decline ticket request

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Decline ticket request

POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/requests/{request_id}/decline

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`request_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Take back access given from this ticket, before it closes

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Take back access given from this ticket, before it closes

POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/requests/{request_id}/revoke

Take back access given from this ticket, before it closes.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`request_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled The servers you own that have Server Management

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

The servers you own that have Server Management

GET /api/v1/orgs/{org_slug}/chat/managed-servers

The servers you own that have Server Management.

While Server Management is active on a server, our support team installs and configures plugins, mods and modpacks on it when you ask by ticket. This lists your own servers with that add-on. A server another customer shared with you is not listed, because only its owner can ask for that service. Each row has org_service_id, the ID to send as service_id when you open a ticket about that server, the server's server_uuid and name, and its hostname. A server being deleted is left out, and the list is empty when none of your servers has the add-on.

Parameters

Name	In	Type	Required
`org_slug`	path	string	yes

Responses

Section titled Get customer support meta

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`servers`	array of ManagedServer	The customer's servers that have Server Management, including servers shared with them. Empty when none do.
`servers[].org_service_id`	integer	The server's order ID. Send it as `service_id` when opening a ticket about this server.
`servers[].server_uuid`	string or null	The server's UUID, as the server list shows it. Empty while the server has no container.
`servers[].name`	string	The server's name.
`servers[].hostname`	string or null	The server's hostname, when it has one.

Get customer support meta

GET /api/v1/orgs/{org_slug}/chat/meta

Parameters

Name	In	Type	Required
`org_slug`	path	string	yes

Responses

Section titled How the support team is doing over a period, with the period before it for comparison

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

How the support team is doing over a period, with the period before it for comparison

GET /api/v1/orgs/{org_slug}/chat/staff/analytics

How the support team is doing over a period, with the period before it for comparison.

Needs Tier 3 support or above. from and to are days in the brand's own time zone (the last 30 days when left out, at most 366), and compare sets them against another period (previous, week, month, year, custom with compare_from and compare_to, or none). A bad word, a period over 366 days or a custom comparison without both days answers 422.

The answer holds opened (conversations created in the period), closed (closed in it, whenever they opened), first_reply and resolution (median and p90 in seconds by nearest rank, over the conversations opened in the period for replies and over those closed in it for resolution), first_reply.on_time_pct (the share of reply targets kept), csat (ratings of conversations closed in the period, with average, count and a distribution of { score, count } from 5 down to 1), by_day (chat and email opened and conversations closed for each day), first_reply_buckets and backlog_by_age (counts per bucket), by_agent and by_department (each with its own medians), heatmap (seven weekdays from Monday by 24 hours of conversations opened, in the brand's time) and right_now (the queue as the inbox tiles show it now). A conversation by email counts as email. previous repeats the headline figures for the comparison period, or is null.

Quantile figures read at most 20,000 conversations per list, newest first; truncated says when there were more.

Parameters

Name	In	Type	Required	Description
`org_slug`	path	string	yes
`from`	query	string (date) or null	no	First day of the period, YYYY-MM-DD, in the brand's time zone. A period is at most 366 days.
`to`	query	string (date) or null	no	Last day of the period, YYYY-MM-DD, in the brand's time zone. Left out, today.
`compare`	query	string or null	no	What to set the period against: previous (the same number of days just before it; a calendar month compares to the prior month), week, month or year (the same days one week, month or year earlier), custom (the days between compare_from and compare_to) or none. Left out, none.
`compare_from`	query	string (date) or null	no	First day of the comparison period for compare=custom, YYYY-MM-DD.
`compare_to`	query	string (date) or null	no	Last day of the comparison period for compare=custom, YYYY-MM-DD.

Responses

Section titled List org canned responses

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

List org canned responses

GET /api/v1/orgs/{org_slug}/chat/staff/canned-responses

Parameters

Name	In	Type	Required
`org_slug`	path	string	yes
`department`	query	string	no

Responses

Section titled Create org canned response

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

A 200 response is a list; each item has these fields:

Field	Type
`[].id`	integer
`[].org_id`	integer or null
`[].title`	string
`[].shortcut`	string
`[].body`	string
`[].department`	string or null
`[].is_shared`	boolean
`[].actions`	object or null
`[].usage_count`	integer
`[].last_used_at`	string (date-time) or null
`[].created_by`	object or null
`[].created_at`	string (date-time)
`[].updated_at`	string (date-time)

Create org canned response

POST /api/v1/orgs/{org_slug}/chat/staff/canned-responses

Parameters

Name	In	Type	Required
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required	Description
`title`	string	yes
`shortcut`	string	yes
`body`	string	yes
`department`	string or null	no
`is_shared`	boolean	no
`actions`	object or null	no	What sending a reply made from it also does: status (awaiting_customer, on_hold or closed), priority (low, medium, high or critical) and add_tags (up to ten), each optional; null for none

Responses

Section titled Update org canned response

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 201 response:

Field	Type
`id`	integer
`org_id`	integer or null
`title`	string
`shortcut`	string
`body`	string
`department`	string or null
`is_shared`	boolean
`actions`	object or null
`usage_count`	integer
`last_used_at`	string (date-time) or null
`created_by`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)

Update org canned response

PUT /api/v1/orgs/{org_slug}/chat/staff/canned-responses/{response_id}

Parameters

Name	In	Type	Required
`response_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required	Description
`title`	string or null	no
`shortcut`	string or null	no
`body`	string or null	no
`department`	string or null	no
`is_shared`	boolean or null	no
`actions`	object or null	no	As on create; null clears them, and leaving it out keeps them

Responses

Section titled Delete org canned response

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`id`	integer
`org_id`	integer or null
`title`	string
`shortcut`	string
`body`	string
`department`	string or null
`is_shared`	boolean
`actions`	object or null
`usage_count`	integer
`last_used_at`	string (date-time) or null
`created_by`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)

Delete org canned response

DELETE /api/v1/orgs/{org_slug}/chat/staff/canned-responses/{response_id}

Parameters

Name	In	Type	Required
`response_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Count org canned response use

Status	Meaning
`204`	Success.
`422`	The request is not valid. `detail` lists each problem.

Count org canned response use

POST /api/v1/orgs/{org_slug}/chat/staff/canned-responses/{response_id}/used

Count one use of a canned reply: the console calls it when a member sends a reply made from it. Any support tier may. It adds 1 to the reply's usage_count, sets last_used_at to now and answers { usage_count }. A reply that is not this brand's answers 404. A member who counts more than 600 uses an hour answers 429.

Parameters

Name	In	Type	Required
`response_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Tickets, newest activity first

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Tickets, newest activity first

GET /api/v1/orgs/{org_slug}/chat/staff/conversations

Tickets, newest activity first. Tier 1 sees only the queue and its own; assigned_to (one engineer's claims) is for Tier 3 and above, escalated narrows to tickets escalated to a higher tier, department to one department and late to the tickets past a target. Every filter is applied before the page is cut, so page and limit walk exactly the tickets that match.

Parameters

Name	In	Type	Required	Description
`org_slug`	path	string	yes
`status`	query	string	no
`priority`	query	string	no
`department`	query	string or null	no	A department's key, as GET chat/staff/departments lists it (slug). Only that department's tickets.
`late`	query	string or null	no	1 or true keeps the tickets waiting on staff that are past a target: a first reply nobody sent or a resolution not reached in time, as the Past SLA figure counts them. 0, false or left out does not narrow the list. Any other word answers 422.
`q`	query	string	no
`assigned_to_me`	query	boolean	no	Default: `False`.
`assigned_to`	query	integer or null	no
`escalated`	query	boolean	no	Default: `False`.
`audience`	query	string	no
`page`	query	integer	no	Default: `1`.
`limit`	query	integer	no	Default: `20`.

Responses

Section titled Open a ticket on a customer's behalf

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

A 200 response is a list; each item has these fields:

Field	Type
`[].id`	integer
`[].conversation_number`	integer
`[].scope`	string
`[].subject`	string
`[].status`	string
`[].priority`	string
`[].department`	string or null
`[].assigned_agent_id`	integer or null
`[].assigned_agent_name`	string or null
`[].user_id`	integer or null
`[].user_email`	string or null
`[].user_name`	string or null
`[].customer_id`	integer or null
`[].channel`	string
`[].email_from`	string or null
`[].last_message_at`	string (date-time) or null
`[].last_message_preview`	string or null
`[].tags`	array of string or null
`[].unread_count`	integer
`[].waiting_seconds`	integer or null
`[].sla_first_response_due_at`	string (date-time) or null
`[].sla_resolution_due_at`	string (date-time) or null
`[].sla_breached_first_response`	boolean
`[].sla_breached_resolution`	boolean
`[].first_response_at`	string (date-time) or null
`[].csat_score`	integer or null
`[].created_at`	string (date-time)
`[].updated_at`	string (date-time)
`[].is_free`	boolean or null
`[].viewers`	array of string
`[].escalated_tier`	integer or null
`[].customer_plan`	CustomerPlan or null
`[].customer_plan.key`	string
`[].customer_plan.name`	string
`[].customer_plan.support_level`	string or null
`[].customer_plan.first_response_minutes`	integer or null
`[].support_tier`	string or null
`[].managed`	boolean or null

Open a ticket on a customer's behalf

POST /api/v1/orgs/{org_slug}/chat/staff/conversations

Open a ticket on a customer's behalf. The customer sees a system line saying staff opened it, then the staff member's message, and is emailed like any reply; the paid-support gate does not apply because staff chose to reach out.

Parameters

Name	In	Type	Required
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`customer_id`	integer	yes
`subject`	string	yes
`body`	string	yes
`priority`	string	no
`department`	string or null	no
`service_id`	integer or null	no
`assign_to_me`	boolean	no

Responses

Section titled Bulk org staff conversations

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 201 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

Bulk org staff conversations

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/bulk

The same change to many tickets at once: take them, drop them, close them, or set their priority or department. Tickets outside this org are skipped, not refused, so one bad id cannot spoil a selection.

Parameters

Name	In	Type	Required
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`ids`	array of integer	yes
`action`	string	yes
`value`	string or null	no

Responses

Section titled Get org staff conversation

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Get org staff conversation

GET /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Update org conversation

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

Update org conversation

PATCH /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}

Priority, department, status, tags, and (Tier 3 and above) which customer the ticket belongs to. A status of closed closes it the way the close button does, and moving a closed ticket to any other status reopens it first, so whatever a close or a reopen sets in motion runs either way.

tags replaces the ticket's tags with the list it holds: at most 10, each at most 40 characters, trimmed and lower case, blanks and repeats dropped. An empty list clears them. More than 10 answers 422. The change is on the activity log with the tags as saved.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`priority`	string or null	no
`department`	string or null	no
`status`	string or null	no
`tags`	array of string or null	no
`subject`	string or null	no
`customer_id`	integer or null	no

Responses

Section titled Claim a ticket, or with agentid (Tier 3 and above) give it to a teammate

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

Claim a ticket, or with agentid (Tier 3 and above) give it to a teammate

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/assign

Claim a ticket, or with agent_id (Tier 3 and above) give it to a teammate. Either way the new holder must be able to take it and have room under their claim limit.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`agent_id`	integer or null	no

Responses

Section titled The file a customer attached, for the staff member reading the ticket

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

The file a customer attached, for the staff member reading the ticket

GET /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/attachments/{attachment_id}

The file a customer attached, for the staff member reading the ticket. The customer route is scoped to the owner; this one to the org.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`attachment_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Close org staff conversation

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Close org staff conversation

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/close

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Close this ticket as a duplicate of another of the same customer's

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

Close this ticket as a duplicate of another of the same customer's

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/duplicate

Close this ticket as a duplicate of another of the same customer's.

The customer is told which ticket the conversation continues in; the other ticket gets an internal note pointing back, so whoever answers it knows there was a second report. Only tickets of the same customer can be folded together, because folding two customers' tickets is always a mistake.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required	Description
`of`	integer	yes	The ticket this one duplicates

Responses

Section titled Escalate org conversation

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

Escalate org conversation

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/escalate

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Pass a ticket up to Tier 2 or Tier 3, back into the queue there

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

Pass a ticket up to Tier 2 or Tier 3, back into the queue there

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/escalate-tier

Pass a ticket up to Tier 2 or Tier 3, back into the queue there.

Tiers 1 and 2 may only send a ticket above themselves. Tier 3 and above may also lower an escalation or clear it (tier: null). note tells the next engineer what has been tried, as an internal note.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`tier`	integer or null	no
`note`	string or null	no

Responses

Section titled A note for the desk, on any ticket the caller may read

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

A note for the desk, on any ticket the caller may read

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/internal-note

A note for the desk, on any ticket the caller may read. Tier 2 can leave one on a colleague's ticket it may not answer.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`body`	string	yes

Responses

Section titled Get org staff messages

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`id`	integer
`conversation_id`	integer
`sender_type`	string
`sender_id`	integer or null
`sender_name`	string or null
`body`	string or null
`content_type`	string
`is_internal`	boolean
`attachments`	array of AttachmentResponse
`attachments[].id`	integer
`attachments[].file_name`	string
`attachments[].file_size`	integer
`attachments[].mime_type`	string
`attachments[].created_at`	string (date-time)
`read_at`	string (date-time) or null
`created_at`	string (date-time)
`client_request_id`	string or null
`request`	object or null

Get org staff messages

GET /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/messages

Parameters

Name	In	Type	Required	Description
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes
`before_id`	query	integer	no
`limit`	query	integer	no	Default: `50`.

Responses

Section titled A reply to a closed ticket reopens it first

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

A 200 response is a list; each item has these fields:

Field	Type
`[].id`	integer
`[].conversation_id`	integer
`[].sender_type`	string
`[].sender_id`	integer or null
`[].sender_name`	string or null
`[].body`	string or null
`[].content_type`	string
`[].is_internal`	boolean
`[].attachments`	array of AttachmentResponse
`[].attachments[].id`	integer
`[].attachments[].file_name`	string
`[].attachments[].file_size`	integer
`[].attachments[].mime_type`	string
`[].attachments[].created_at`	string (date-time)
`[].read_at`	string (date-time) or null
`[].created_at`	string (date-time)
`[].client_request_id`	string or null
`[].request`	object or null

A reply to a closed ticket reopens it first

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/messages

A reply to a closed ticket reopens it first. The composer says so, and a staff member writing to a customer means to be heard, not refused. An unassigned ticket becomes the replier's: whoever answers owns it, unless somebody already does, and within the replier's claim limit. With close the ticket is closed once the reply is in.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`body`	string	yes
`client_request_id`	string or null	no
`close`	boolean	no

Responses

Section titled Give a claimed ticket back to the queue

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`id`	integer
`conversation_id`	integer
`sender_type`	string
`sender_id`	integer or null
`sender_name`	string or null
`body`	string or null
`content_type`	string
`is_internal`	boolean
`attachments`	array of AttachmentResponse
`attachments[].id`	integer
`attachments[].file_name`	string
`attachments[].file_size`	integer
`attachments[].mime_type`	string
`attachments[].created_at`	string (date-time)
`read_at`	string (date-time) or null
`created_at`	string (date-time)
`client_request_id`	string or null
`request`	object or null

Give a claimed ticket back to the queue

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/release

Give a claimed ticket back to the queue. The holder may release their own; Tier 3 and above may release anyone's. note is left for whoever takes it next, as an internal note.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json

Field	Type	Required
`note`	string or null	no

Responses

Section titled Reopen org staff conversation

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

Reopen org staff conversation

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/reopen

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Every request on the ticket, newest first, as its card shows it

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

Every request on the ticket, newest first, as its card shows it

GET /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/requests

Every request on the ticket, newest first, as its card shows it.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Create ticket request

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Create ticket request

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/requests

Ask the ticket's customer for a server's logs (any tier) or for subuser access to it (Tier 2 and above). The customer answers in their thread; nothing is shared or granted until they do.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`kind`	string	yes
`server_uuid`	string	yes
`scope`	string	yes
`note`	string or null	no

Responses

Section titled Withdraw a request the customer has not answered yet

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Withdraw a request the customer has not answered yet

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/requests/{request_id}/cancel

Withdraw a request the customer has not answered yet.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`request_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Give back server access before the ticket closes: done with it, or handing the work on

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Give back server access before the ticket closes: done with it, or handing the work on

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/requests/{request_id}/release

Give back server access before the ticket closes: done with it, or handing the work on.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`request_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Transfer org conversation

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Transfer org conversation

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/transfer

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`agent_id`	integer or null	no
`department`	string or null	no

Responses

Section titled Org ticket viewing

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`conversation_number`	integer
`scope`	string
`org_id`	integer or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`email_mailbox`	string or null
`subject`	string
`department`	string or null
`priority`	string
`status`	string
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`assigned_at`	string (date-time) or null
`service_id`	integer or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`closed_at`	string (date-time) or null
`reopened_count`	integer
`tags`	array of string or null
`first_response_at`	string (date-time) or null
`first_response_by_id`	integer or null
`resolved_at`	string (date-time) or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`csat_score`	integer or null
`csat_comment`	string or null
`csat_rated_at`	string (date-time) or null
`unread_count`	integer
`messages`	array of ChatMessageResponse
`messages[].id`	integer
`messages[].conversation_id`	integer
`messages[].sender_type`	string
`messages[].sender_id`	integer or null
`messages[].sender_name`	string or null
`messages[].body`	string or null
`messages[].content_type`	string
`messages[].is_internal`	boolean
`messages[].attachments`	array of AttachmentResponse
`messages[].read_at`	string (date-time) or null
`messages[].created_at`	string (date-time)
`messages[].client_request_id`	string or null
`messages[].request`	object or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null
...		More fields than this page lists; the interactive reference has them all.

Org ticket viewing

POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/viewing

The console's heartbeat on an open ticket: "I am looking at this one", answered with who else is. One presence row per staff member follows them from ticket to ticket; a row older than VIEWING_TTL is a closed tab and is not reported.

Parameters

Name	In	Type	Required
`conversation_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Departments with their names and SLAs, for anything staff-side that shows a ticket

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`viewers`	array of object

Departments with their names and SLAs, for anything staff-side that shows a ticket

GET /api/v1/orgs/{org_slug}/chat/staff/departments

Departments with their names and SLAs, for anything staff-side that shows a ticket. Tickets carry only the slug; without this the console printed billing where a customer sees "Billing".

Parameters

Name	In	Type	Required
`org_slug`	path	string	yes

Responses

Section titled Unclaimed tickets waiting for an answer, at the caller's tier or below

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Unclaimed tickets waiting for an answer, at the caller's tier or below

GET /api/v1/orgs/{org_slug}/chat/staff/queue

Unclaimed tickets waiting for an answer, at the caller's tier or below.

Parameters

Name	In	Type	Required	Description
`org_slug`	path	string	yes
`department`	query	string	no
`audience`	query	string	no
`page`	query	integer	no	Default: `1`.
`limit`	query	integer	no	Default: `20`.

Responses

Section titled Claim the ticket at the front of the queue and hand it back

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

A 200 response is a list; each item has these fields:

Field	Type
`[].id`	integer
`[].conversation_number`	integer
`[].scope`	string
`[].subject`	string
`[].status`	string
`[].priority`	string
`[].department`	string or null
`[].assigned_agent_id`	integer or null
`[].assigned_agent_name`	string or null
`[].user_id`	integer or null
`[].user_email`	string or null
`[].user_name`	string or null
`[].customer_id`	integer or null
`[].channel`	string
`[].email_from`	string or null
`[].last_message_at`	string (date-time) or null
`[].last_message_preview`	string or null
`[].tags`	array of string or null
`[].unread_count`	integer
`[].waiting_seconds`	integer or null
`[].sla_first_response_due_at`	string (date-time) or null
`[].sla_resolution_due_at`	string (date-time) or null
`[].sla_breached_first_response`	boolean
`[].sla_breached_resolution`	boolean
`[].first_response_at`	string (date-time) or null
`[].csat_score`	integer or null
`[].created_at`	string (date-time)
`[].updated_at`	string (date-time)
`[].is_free`	boolean or null
`[].viewers`	array of string
`[].escalated_tier`	integer or null
`[].customer_plan`	CustomerPlan or null
`[].customer_plan.key`	string
`[].customer_plan.name`	string
`[].customer_plan.support_level`	string or null
`[].customer_plan.first_response_minutes`	integer or null
`[].support_tier`	string or null
`[].managed`	boolean or null

Claim the ticket at the front of the queue and hand it back

POST /api/v1/orgs/{org_slug}/chat/staff/queue/take-next

Claim the ticket at the front of the queue and hand it back.

One click instead of open the inbox, pick the top row, press Take. The lock means two people pressing at the same moment get two different tickets, not the same one. null when nobody is waiting. Refused with 409 when the caller already holds as many tickets as their tier may.

Parameters

Name	In	Type	Required
`org_slug`	path	string	yes
`department`	query	string	no
`audience`	query	string	no

Responses

Section titled The numbers above the inbox, under the audience the request carries

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`id`	integer
`conversation_number`	integer
`scope`	string
`subject`	string
`status`	string
`priority`	string
`department`	string or null
`assigned_agent_id`	integer or null
`assigned_agent_name`	string or null
`user_id`	integer or null
`user_email`	string or null
`user_name`	string or null
`customer_id`	integer or null
`channel`	string
`email_from`	string or null
`last_message_at`	string (date-time) or null
`last_message_preview`	string or null
`tags`	array of string or null
`unread_count`	integer
`waiting_seconds`	integer or null
`sla_first_response_due_at`	string (date-time) or null
`sla_resolution_due_at`	string (date-time) or null
`sla_breached_first_response`	boolean
`sla_breached_resolution`	boolean
`first_response_at`	string (date-time) or null
`csat_score`	integer or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`is_free`	boolean or null
`viewers`	array of string
`escalated_tier`	integer or null
`customer_plan`	CustomerPlan or null
`customer_plan.key`	string
`customer_plan.name`	string
`customer_plan.support_level`	string or null
`customer_plan.first_response_minutes`	integer or null
`support_tier`	string or null
`managed`	boolean or null

The numbers above the inbox, under the audience the request carries

GET /api/v1/orgs/{org_slug}/chat/staff/stats

The numbers above the inbox, under the audience the request carries. closed_today is the tickets closed since midnight in the brand's own timezone (OrgSettings.timezone; UTC when the brand has not set one), so "what we finished today" is the day the team is working in. Waiting counts what the caller's tier may take; claim_limit is how many the caller may hold, and Tier 3 and above also get claims per engineer.

by_status counts every ticket of the brand under each status (open, awaiting_customer, awaiting_agent, in_progress, on_hold and closed), with a 0 for a status nothing is in. avg_first_response_seconds is the average time from a ticket's opening to its first reply, over the tickets whose first reply came in the last 30 days; it is null when there were none.

my_open, my_awaiting_agent and claim_limit are for the member who asks and are always current. Everything else is the same for every member of one tier. It is normally under a minute old, and the first request after a quiet spell can show numbers a few minutes old.

Parameters

Name	In	Type	Required
`org_slug`	path	string	yes
`audience`	query	string	no

Responses

Section titled Which support tier the signed-in customer has, and what it changes

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`total_waiting`	integer
`agents_online`	integer
`my_open`	integer
`my_awaiting_agent`	integer
`total_active`	integer
`open`	integer
`total_on_hold`	integer
`sla_breached`	integer
`closed_today`	integer
`oldest_waiting_seconds`	integer or null
`avg_first_response_seconds`	number or null
`avg_resolution_seconds`	number or null
`by_department`	By Department
`by_priority`	By Priority
`by_status`	By Status
`claim_limit`	integer or null
`escalated_waiting`	integer
`claims`	array of object or null

Which support tier the signed-in customer has, and what it changes

GET /api/v1/orgs/{org_slug}/chat/support-tier

Which support tier the signed-in customer has, and what it changes.

Customers with an active Priority Support service get tier: "priority". Their new tickets open at high priority with the plan's first reply target, and they can choose any priority. Everyone else is on standard: a store that sells Priority Support opens their tickets at the priority they choose, up to medium, with the store's standard first reply target.

service describes the customer's Priority Support service, including whether it ends at the end of its term. offer lists the plan and its prices when the store sells Priority Support and the customer does not have it yet. The answer covers this customer in this store only.

Parameters

Name	In	Type	Required
`org_slug`	path	string	yes

Responses