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 Create user conversation
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 Get support meta

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

Create user conversation

Section titled Create user conversation

POST /api/v1/chat/conversations

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

Section titled Get support meta

GET /api/v1/chat/meta

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

Responses

Section titled Responses
Status Meaning
200 Success.