# Client API: Support

> Conversational support chat (threads and messages).

Source: https://www.coritan.com/docs/api/reference/client/support/

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](https://api.coritan.com/docs).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/chat/conversations`](#op-get-api-v1-chat-conversations) | List user conversations |
| POST | [`/api/v1/chat/conversations`](#op-post-api-v1-chat-conversations) | Create user conversation |
| GET | [`/api/v1/chat/conversations/{conversation_id}`](#op-get-api-v1-chat-conversations-conversation-id) | Get user conversation |
| POST | [`/api/v1/chat/conversations/{conversation_id}/attachments`](#op-post-api-v1-chat-conversations-conversation-id-attachments) | Upload attachment |
| GET | [`/api/v1/chat/conversations/{conversation_id}/attachments/{attachment_id}`](#op-get-api-v1-chat-conversations-conversation-id-attachments-attachment-id) | Download attachment |
| GET | [`/api/v1/chat/conversations/{conversation_id}/attachments/{attachment_id}/thumbnail`](#op-get-api-v1-chat-conversations-conversation-id-attachments-attachment-id-thumbnai) | Download thumbnail |
| POST | [`/api/v1/chat/conversations/{conversation_id}/close`](#op-post-api-v1-chat-conversations-conversation-id-close) | Close user conversation |
| POST | [`/api/v1/chat/conversations/{conversation_id}/csat`](#op-post-api-v1-chat-conversations-conversation-id-csat) | Rate user conversation |
| GET | [`/api/v1/chat/conversations/{conversation_id}/messages`](#op-get-api-v1-chat-conversations-conversation-id-messages) | Get conversation messages |
| POST | [`/api/v1/chat/conversations/{conversation_id}/messages`](#op-post-api-v1-chat-conversations-conversation-id-messages) | Send user message |
| POST | [`/api/v1/chat/conversations/{conversation_id}/read`](#op-post-api-v1-chat-conversations-conversation-id-read) | Mark user conversation read |
| POST | [`/api/v1/chat/conversations/{conversation_id}/reopen`](#op-post-api-v1-chat-conversations-conversation-id-reopen) | Reopen user conversation |
| GET | [`/api/v1/chat/meta`](#op-get-api-v1-chat-meta) | Get support meta |

### List user conversations {#op-get-api-v1-chat-conversations}

`GET /api/v1/chat/conversations`

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

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

| 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 {#op-post-api-v1-chat-conversations}

`POST /api/v1/chat/conversations`

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

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

| 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 {#op-get-api-v1-chat-conversations-conversation-id}

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

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### 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 {#op-post-api-v1-chat-conversations-conversation-id-attachments}

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

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### Request body

`multipart/form-data` (required)

| Field | Type | Required |
| --- | --- | --- |
| `file` | string (binary) | yes |

#### Responses

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

### Download attachment {#op-get-api-v1-chat-conversations-conversation-id-attachments-attachment-id}

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

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `attachment_id` | path | integer | yes |

#### Responses

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

### Download thumbnail {#op-get-api-v1-chat-conversations-conversation-id-attachments-attachment-id-thumbnai}

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

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `attachment_id` | path | integer | yes |

#### Responses

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

### Close user conversation {#op-post-api-v1-chat-conversations-conversation-id-close}

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

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### 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 {#op-post-api-v1-chat-conversations-conversation-id-csat}

`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

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### Request body

`application/json` (required)

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

#### Responses

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

### Get conversation messages {#op-get-api-v1-chat-conversations-conversation-id-messages}

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

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

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

| 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 {#op-post-api-v1-chat-conversations-conversation-id-messages}

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

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### Request body

`application/json` (required)

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

#### 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 {#op-post-api-v1-chat-conversations-conversation-id-read}

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

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `up_to_message_id` | integer or null | no |

#### Responses

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

### Reopen user conversation {#op-post-api-v1-chat-conversations-conversation-id-reopen}

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

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### 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 {#op-get-api-v1-chat-meta}

`GET /api/v1/chat/meta`

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

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |