Skip to content
Coritan Docs

Client API: Support

Conversational support chat (threads and messages).

View as Markdown

Conversational support chat (threads and messages).

Base URL: https://api.coritan.com/api/v1. Paths below are complete.

To try these requests in the browser, open the interactive Client API reference.

Operations

Section titled Operations
Method Path Summary
GET /api/v1/chat/conversations List user conversations
POST /api/v1/chat/conversations Open a support conversation for this account
GET /api/v1/chat/conversations/{conversation_id} Get user conversation
POST /api/v1/chat/conversations/{conversation_id}/attachments Upload attachment
GET /api/v1/chat/conversations/{conversation_id}/attachments/{attachment_id} Download attachment
GET /api/v1/chat/conversations/{conversation_id}/attachments/{attachment_id}/thumbnail Download thumbnail
POST /api/v1/chat/conversations/{conversation_id}/close Close user conversation
POST /api/v1/chat/conversations/{conversation_id}/csat Rate user conversation
GET /api/v1/chat/conversations/{conversation_id}/messages Get conversation messages
POST /api/v1/chat/conversations/{conversation_id}/messages Send user message
POST /api/v1/chat/conversations/{conversation_id}/read Mark user conversation read
POST /api/v1/chat/conversations/{conversation_id}/reopen Reopen user conversation
GET /api/v1/chat/meta Departments, priorities and attachment rules for the composer

List user conversations

Section titled List user conversations

GET /api/v1/chat/conversations

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters
Name In Type Required Description
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 Responses
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 support conversation for this account

Section titled Open a support conversation for this account

POST /api/v1/chat/conversations

Open a support conversation for this account.

While the plans apply to the account, its plan decides the lowest priority (support_level: Free low, Pro medium, Business and Enterprise high; a higher choice stands) and the first-reply target (support_target_minutes) in place of the department's.

Authentication: an access token, sent as Authorization: Bearer <token>.

Request body

Section titled 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 Responses
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 user conversation

Section titled Get user conversation

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

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters
Name In Type Required
conversation_id path integer yes

Responses

Section titled Responses
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 attachment

Section titled Upload attachment

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

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters
Name In Type Required
conversation_id path integer yes

Request body

Section titled Request body

multipart/form-data (required)

Field Type Required
file string (binary) yes

Responses

Section titled Responses
Status Meaning
201 Success.
422 The request is not valid. detail lists each problem.

Download attachment

Section titled Download attachment

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

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters
Name In Type Required
conversation_id path integer yes
attachment_id path integer yes

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

Download thumbnail

Section titled Download thumbnail

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

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters
Name In Type Required
conversation_id path integer yes
attachment_id path integer yes

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

Close user conversation

Section titled Close user conversation

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

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters
Name In Type Required
conversation_id path integer yes

Responses

Section titled Responses
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 user conversation

Section titled Rate user conversation

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

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

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters
Name In Type Required
conversation_id path integer yes

Request body

Section titled Request body

application/json (required)

Field Type Required
score integer yes
comment string or null no

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

Get conversation messages

Section titled Get conversation messages

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

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters
Name In Type Required Description
conversation_id path integer yes
before_id query integer no
after_id query integer no
limit query integer no Default: 50.

Responses

Section titled Responses
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 user message

Section titled Send user message

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

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters
Name In Type Required
conversation_id path integer yes

Request body

Section titled Request body

application/json (required)

Field Type Required
body string yes
client_request_id string or null no

Responses

Section titled Responses
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 user conversation read

Section titled Mark user conversation read

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

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters
Name In Type Required
conversation_id path integer yes

Request body

Section titled Request body

application/json (required)

Field Type Required
up_to_message_id integer or null no

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

Reopen user conversation

Section titled Reopen user conversation

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

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters
Name In Type Required
conversation_id path integer yes

Responses

Section titled Responses
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.

Departments, priorities and attachment rules for the composer

Section titled Departments, priorities and attachment rules for the composer

GET /api/v1/chat/meta

Departments, priorities and attachment rules for the composer. Each department's sla_first_response_minutes is the target a new conversation from this account gets, and plan_terms names the plan that set it (None while the plans do not apply to the account).

Authentication: an access token, sent as Authorization: Bearer <token>.

Responses

Section titled Responses
Status Meaning
200 Success.