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

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
`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

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
`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

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
`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

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
`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

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 Get customer support meta

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

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 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
`[].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
`title`	string	yes
`shortcut`	string	yes
`body`	string	yes
`department`	string or null	no
`is_shared`	boolean	no

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
`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
`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

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
`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 Tickets, newest activity first

Status	Meaning
`204`	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.

Parameters

Name	In	Type	Required	Description
`org_slug`	path	string	yes
`status`	query	string	no
`priority`	query	string	no
`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

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
`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

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 Priority, department, status, and (Tier 3 and above) which customer the ticket belongs to

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
`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

Priority, department, status, and (Tier 3 and above) which customer the ticket belongs to

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

Priority, department, status, 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.

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
`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

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
`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

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
`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

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
`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

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
`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

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
`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

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
`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

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
`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

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
`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

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

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 figures 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

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

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

The figures 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.

Parameters

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

Responses