# Chats API

{% hint style="warning" %}
The Chats API is currently in a closed beta phase and not publicly available. 

*Access is limited to selected partners for testing and feedback purposes.*
{% endhint %}

The Chats API offers a comprehensive set of endpoints designed to manage conversations and user interactions within a chat environment. 

It supports key features:

1. [**Chat Management:**](#chat-management) Create, retrieve, and manage chat messages.
2. [**Reaction Management:**](#reactions-management) Add, view, and track emoji or custom reactions on messages.
3. [**Pinning Management:**](#pinning-management) Pin important messages.

For real time events, look at [real-time-events](https://docs.quicksync.me/qs-framework/real-time-events "mention")

{% hint style="info" %}
**Notable limitations in beta phase:**

* Chat message length is capped to 280 characters.
* Reactions are limited to \[:thumbs\_up:,:thumbs\_down:]
* Paged chat result can return a maximum of 20 messages in a single page.
* Destructive actions can only performed by the owner of the resource or privileged users in a session, as of now, it is only the Host of the session.
* Pinning a message can only be done by privileged users in a session, as of now, it is only the Host of the session. 
  {% endhint %}

## Chat Management

***

## Retrieve paginated list of chat messages

> Fetches a list of chat messages in a paginated format. Supports sorting by creation time, pinned status, or specific reaction types.

```json
{"openapi":"3.0.1","info":{"title":"Chats API","version":"1.0.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}},"schemas":{"PagedMessagesDto":{"type":"object","properties":{"totalCount":{"type":"integer","format":"int32"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/MessageDto"},"nullable":true}},"additionalProperties":false},"MessageDto":{"type":"object","properties":{"chatId":{"type":"string","nullable":true},"message":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"user":{"$ref":"#/components/schemas/ChatUser"},"pinned":{"$ref":"#/components/schemas/Pinned"},"reactions":{"type":"array","items":{"$ref":"#/components/schemas/Reaction"},"nullable":true}},"additionalProperties":false},"ChatUser":{"type":"object","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true}},"additionalProperties":false},"Pinned":{"type":"object","properties":{"id":{"type":"string","nullable":true}},"additionalProperties":false},"Reaction":{"type":"object","properties":{"name":{"type":"string","nullable":true},"count":{"type":"integer","format":"int32"},"users":{"type":"array","items":{"$ref":"#/components/schemas/ReactedUser"},"nullable":true}},"additionalProperties":false},"ReactedUser":{"type":"object","properties":{"id":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/chats":{"get":{"tags":["Chats"],"summary":"Retrieve paginated list of chat messages","description":"Fetches a list of chat messages in a paginated format. Supports sorting by creation time, pinned status, or specific reaction types.","parameters":[{"name":"Skip","in":"query","description":"The number of items to skip before starting to return results. Useful for paginating through results.","required":false,"style":"form","schema":{"type":"integer","format":"int32","default":0,"minimum":0}},{"name":"Take","in":"query","description":"The number of items to return. Used for paginating results. Limits the size of the result set.","required":false,"style":"form","schema":{"type":"integer","format":"int32","default":20,"minimum":1,"maximum":20}},{"name":"SortBy","in":"query","description":"The field by which to sort the results. Supported values include 'CreatedAt', 'Pinned', and reaction types like ':thumbsup:' or ':thumbsdown:'.","required":false,"style":"form","schema":{"type":"string","default":"CreatedAt","enum":["CreatedAt","Pinned",":thumbsup:",":thumbsdown:"]}},{"name":"Ascending","in":"query","description":"Determines whether the sorting should be in ascending order. Set to 'false' for descending order.","required":false,"style":"form","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Success","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/PagedMessagesDto"}},"application/json":{"schema":{"$ref":"#/components/schemas/PagedMessagesDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/PagedMessagesDto"}}}}}}}}}
```

## Send a new chat message

> Creates and stores a new chat message within a session. This is typically used when a user sends a message in a conversation.

```json
{"openapi":"3.0.1","info":{"title":"Chats API","version":"1.0.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}},"schemas":{"CreateChatMessageRequest":{"type":"object","properties":{"message":{"type":"string","nullable":true}},"additionalProperties":false},"SingleMessageDto":{"type":"object","properties":{"chatId":{"type":"string","nullable":true},"message":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"paths":{"/chats":{"post":{"tags":["Chats"],"summary":"Send a new chat message","description":"Creates and stores a new chat message within a session. This is typically used when a user sends a message in a conversation.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChatMessageRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/CreateChatMessageRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/CreateChatMessageRequest"}}}},"responses":{"200":{"description":"Success","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/SingleMessageDto"}},"application/json":{"schema":{"$ref":"#/components/schemas/SingleMessageDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/SingleMessageDto"}}}}}}}}}
```

## Delete a specific chat message

> Deletes a chat message by its unique identifier.

```json
{"openapi":"3.0.1","info":{"title":"Chats API","version":"1.0.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}},"schemas":{}},"paths":{"/chats/{chatId}":{"delete":{"tags":["Chats"],"summary":"Delete a specific chat message","description":"Deletes a chat message by its unique identifier.","parameters":[{"name":"chatId","in":"path","required":true,"style":"simple","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}}
```

## Add a reaction to a chat message

> Adds a reaction (e.g., emoji in shortcodes format) to a specific chat message identified by its chatId.

```json
{"openapi":"3.0.1","info":{"title":"Chats API","version":"1.0.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}},"schemas":{"CreateChatReactionRequest":{"type":"object","properties":{"reaction":{"type":"string","nullable":true}},"additionalProperties":false},"ChatReactionCreatedResponseDto":{"type":"object","properties":{"reactionId":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/chats/{chatId}/reactions":{"post":{"tags":["Chats"],"summary":"Add a reaction to a chat message","description":"Adds a reaction (e.g., emoji in shortcodes format) to a specific chat message identified by its chatId.","parameters":[{"name":"chatId","in":"path","required":true,"style":"simple","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChatReactionRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/CreateChatReactionRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/CreateChatReactionRequest"}}}},"responses":{"200":{"description":"Success","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ChatReactionCreatedResponseDto"}},"application/json":{"schema":{"$ref":"#/components/schemas/ChatReactionCreatedResponseDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/ChatReactionCreatedResponseDto"}}}},"404":{"description":"Not Found","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Conflict","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}}
```

## Reactions Management

***

## Fetch reactions for multiple messages

> Retrieves a list of reactions associated with multiple chat messages using their chat IDs.

```json
{"openapi":"3.0.1","info":{"title":"Chats API","version":"1.0.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}},"schemas":{"ChatMessagesReactionsDto":{"type":"object","properties":{"chatId":{"type":"string","nullable":true},"id":{"type":"string","nullable":true},"reaction":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/chats/reactions":{"get":{"tags":["Chats"],"summary":"Fetch reactions for multiple messages","description":"Retrieves a list of reactions associated with multiple chat messages using their chat IDs.","parameters":[{"name":"chatId","in":"query","style":"form","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Success","content":{"text/plain":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessagesReactionsDto"}}},"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessagesReactionsDto"}}},"text/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessagesReactionsDto"}}}}}}}}}}
```

## Remove a reaction from a chat message

> Removes a specific reaction from a chat message. Requires both the chatId and reactionId.

```json
{"openapi":"3.0.1","info":{"title":"Chats API","version":"1.0.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}}},"paths":{"/chats/{chatId}/reactions/{reactionId}":{"delete":{"tags":["Chats"],"summary":"Remove a reaction from a chat message","description":"Removes a specific reaction from a chat message. Requires both the chatId and reactionId.","parameters":[{"name":"chatId","in":"path","required":true,"style":"simple","schema":{"type":"string"}},{"name":"reactionId","in":"path","required":true,"style":"simple","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}}}}
```

## Pinning Management

***

## Pin a chat message

> Pins a specific message in a chat.

```json
{"openapi":"3.0.1","info":{"title":"Chats API","version":"1.0.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}},"schemas":{}},"paths":{"/chats/{chatId}/pins":{"post":{"tags":["Chats"],"summary":"Pin a chat message","description":"Pins a specific message in a chat.","parameters":[{"name":"chatId","in":"path","required":true,"style":"simple","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"404":{"description":"Not Found","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Conflict","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}}
```

## Unpin a chat message

> Removes a previously pinned message in a chat, using the chatId and pinId.

```json
{"openapi":"3.0.1","info":{"title":"Chats API","version":"1.0.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}}},"paths":{"/chats/{chatId}/pins/{pinId}":{"delete":{"tags":["Chats"],"summary":"Unpin a chat message","description":"Removes a previously pinned message in a chat, using the chatId and pinId.","parameters":[{"name":"chatId","in":"path","required":true,"style":"simple","schema":{"type":"string"}},{"name":"pinId","in":"path","required":true,"style":"simple","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}}}}
```