---
metadata:
- name: generator
content: Diplodoc Platform v5.55.0
alternate:
- https://yandex.com/dev/market/partner-api/doc/en/step-by-step/chats.md
- https://yandex.com/dev/market/partner-api/doc/ru/step-by-step/chats.md
- https://yandex.com/dev/market/partner-api/doc/zh/step-by-step/chats.md
- href: en/step-by-step/chats.md
type: text/markdown
title: Markdown version
- href: ../llms.txt
type: text/markdown
title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/market/partner-api/doc/en/llms.txt
# Chats with customers
Yandex Market API allows you to communicate with your customers in chat rooms.
What are the types of chats:
* `ORDER` — by orders. [Chats about orders and refunds](https://yandex.ru/support/marketplace/ru/orders/communication/about-orders)
* `RETURN` — on refunds (FBY, FBS and Express). [Chats about orders and refunds](https://yandex.ru/support/marketplace/ru/orders/communication/about-orders)
* `DIRECT` — A chat that the customer starts if they have questions about the product. The seller cannot create it. [Learn more about such chats](https://yandex.ru/support/marketplace/ru/orders/communication/with-users)
## How to check if there are new chats or messages {#check}
**Via API notifications:**
Yandex.Market will send you a request. [POST notification](https://yandex.com/dev/market/partner-api/doc/en/push-notifications/reference/sendNotification.md) when a new chat or message appears:
* On **CHAT_CREATED**: Create a chat in your system and save `chatId`. Get the chat context once using the method [GET v2/businesses/{businessId}/chat](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/getChat.md) and save the chat information.
* On **CHAT_MESSAGE_SENT**: Receive only the message using the method [GET v2/businesses/{businessId}/chats/message](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/getChatMessage.md). If the chat has not been saved yet, get it once using the method [GET v2/businesses/{businessId}/chat](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/getChat.md) and save it.
**Through the main API:**
* Check if there is a chat with the buyer. — [POST v2/businesses/{businessId}/chats](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/getChats.md). In the request, specify the chat type and the ID of the order or refund to which it relates.
* To receive one specific chat — [GET v2/businesses/{businessId}/chat](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/getChat.md)
To receive messages, use the following methods:
* [POST v2/businesses/{businessId}/chats/history](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/getChatHistory.md) — for the history of chat messages;
* [GET v2/businesses/{businessId}/chats/message](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/getChatMessage.md) — for the message.
## How to reply to a message {#answer}
```mermaid
%%{
init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#FDF3E8',
'primaryTextColor': '#000000',
'primaryBorderColor': '#BA9C80',
'lineColor': '#BA9C80',
'secondaryColor': '#94E1C4',
'tertiaryColor': '#F84E57',
'noteBkgColor': '#FED58D'
}
}
}%%
sequenceDiagram
participant Merchant as Your store
participant Market as Yandex Market
rect rgb(251, 243, 232)
note right of Merchant: Search for chats that require a response from the store
Merchant ->>+ Market: "statuses": ["WAITING_FOR_PARTNER"]
POST v2/businesses/{businessId}/chats
Market ->> Market: Compiles a list of chats.
Market -->>- Merchant: OK: list of chats.
end
rect rgb(251, 243, 232)
note right of Merchant: Retrieving message history
Merchant ->>+ Market: Chat ID
POST v2/businesses/{businessId}/chats/history
Market ->> Market: Compiles a list of messages.
Market -->>- Merchant: OK: messages from the chat.
end
rect rgb(251, 243, 232)
note right of Merchant: Sending a message
Merchant ->>+ Market:Message
POST v2/businesses/{businessId}/chats/message
Market ->> Market: Sends the message.
Market -->>- Merchant: OK
end
rect rgb(251, 243, 232)
note right of Merchant: Sending a file
Merchant ->>+ Market: File
POST v2/businesses/{businessId}/chats/file/send
Market ->> Market: Sends the file.
Market -->>- Merchant: OK
end
```
1. Find the chats where your answer is needed. To do this, make a request [POST v2/businesses/{businessId}/chats](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/getChats.md).
In the request, send the status "Store response needed" ("statuses": ["WAITING_FOR_PARTNER"]).
1. To get the chat message history, use a request [POST v2/businesses/{businessId}/chats/history](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/getChatHistory.md), where pass the chat ID.
1. Send a message using a request [POST v2/businesses/{businessId}/chats/message](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/sendMessageToChat.md).
If you need to send a file to the buyer — for example, an additional product photo — use a request [POST v2/businesses/{businessId}/chats/file/send](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/sendFileToChat.md).
## How to start a chat {#create}
```mermaid
%%{
init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#FDF3E8',
'primaryTextColor': '#000000',
'primaryBorderColor': '#BA9C80',
'lineColor': '#BA9C80',
'secondaryColor': '#94E1C4',
'tertiaryColor': '#F84E57',
'noteBkgColor': '#FED58D'
}
}
}%%
sequenceDiagram
participant Merchant as Your store
participant Market as Yandex Market
rect rgb(251, 243, 232)
note right of Merchant: Check if there is a chat with the buyer
Merchant ->>+ Market: Chat type and order or return ID
POST v2/businesses/{businessId}/chats
Market ->> Market: Checks if there is a chat
with the buyer.
Market -->>- Merchant: OK: chat information if it exists.
end
rect rgb(251, 243, 232)
note right of Merchant: Create a chat if it doesn't exist
Merchant ->>+ Market: POST v2/businesses/{businessId}/chats/new
Market ->> Market: Creates a chat
with the user.
Market -->>- Merchant: OK: chat ID.
end
rect rgb(251, 243, 232)
note right of Merchant: Send a message
Merchant ->>+ Market: Message
POST v2/businesses/{businessId}/chats/message
Market ->> Market: Sends the message.
Market -->>- Merchant: OK
end
rect rgb(251, 243, 232)
note right of Merchant: Send a file
Merchant ->>+ Market: File
POST v2/businesses/{businessId}/chats/file/send
Market ->> Market: Sends the file.
Market -->>- Merchant: OK
end
```
1. You can start a new chat and get its ID using a request. [POST v2/businesses/{businessId}/chats/new](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/createChat.md).
If the chat with the transmitted context already exists, the ID of this chat will be returned.
{% note tip "How to start a test chat" %}
In the debugging interface, create a test order, and then click **Create a test chat** or make a request [POST v2/businesses/{businessId}/chats/new](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/createChat.md).
[Learn more about working with test orders](https://yandex.com/dev/market/partner-api/doc/en/concepts/sandbox.md)
Please note:
* such a chat can only be created for an order, not a refund;
* There are no customer responses in the test chats.
{% endnote %}
2. Send a message with a request [POST v2/businesses/{businessId}/chats/message](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/sendMessageToChat.md).
If you need to send a file to the buyer — for example, an additional product photo — use a request [POST v2/businesses/{businessId}/chats/file/send](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/sendFileToChat.md).
3. Check new messages from the buyer. — [POST v2/businesses/{businessId}/chats/history](https://yandex.com/dev/market/partner-api/doc/en/reference/chats/getChatHistory.md). Use a filter based on the ID of the last message in the request to receive only new messages and not re-upload those that you already have.