# 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](/qs-framework/real-time-events.md)

{% 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"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.quicksync.me/qs-framework/chats-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.