Search
API docs by Redocly

Customer Communication (communication)

Management of customer inquiries and feedback, chats, and returns processing

Customer Communication

Management of customer inquiries and feedback, chats, and returns processing

Questions

To access the methods, use a token for the Feedbacks and Questions category

Unseen Feedbacks and Questions{{ /api/v1/new-feedbacks-questions }}

Описание метода

The method displays information about the seller's unseen feedbacks and questions

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": false,
  • "errorText": "",
  • "additionalErrors": null
}

Unanswered Questions{{ /api/v1/questions/count-unanswered }}

Описание метода

The method allows you to get the number of unanswered questions for today and for all time

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": false,
  • "errorText": "",
  • "additionalErrors": null
}

Number of Questions{{ /api/v1/questions/count }}

Описание метода

The method allows to get the number of questions for requested period

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
query Parameters
dateFrom
integer
Example: dateFrom=1688465092

The start date of the period in Unix timestamp format

dateTo
integer
Example: dateTo=1688465092

The end date of the period in Unix timestamp format

isAnswered
boolean
Example: isAnswered=false

If the question was answered:

  • true — yes, by default
  • false — no

Responses

Response samples

Content type
application/json
{
  • "data": 77,
  • "error": false,
  • "errorText": "",
  • "additionalErrors": null
}

Question List{{ /api/v1/questions }}

Описание метода

The method allows you to get a list of questions by the specified parameters with pagination and sorting.
It is possible to get a maximum of 10,000 questions per query

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
query Parameters
isAnswered
required
boolean

The question is answered:

  • true — yes, by default
  • false — no
nmId
integer

WB article

take
required
integer

Number of requested questions (the maximum possible value for the parameter is 10,000, and the total amount of take and skip parameters must not exceed 10,000)

skip
required
integer

Number of questions to skip (maximum possible value for the parameter is 10,000, and the total amount of take and skip parameters must not exceed 10,000)

order
string

Sorting questions by date (dateAsc/dateDesc)

dateFrom
integer
Example: dateFrom=1688465092

The start date of the period in Unix timestamp format

dateTo
integer
Example: dateTo=1688465092

The end date of the period in Unix timestamp format

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": false,
  • "errorText": "",
  • "additionalErrors": null
}

Working with Questions{{ /api/v1/questions }}

Описание метода

Depending on the request body, you can:

  • View question.
  • Reject question.
  • Answer question or edit the answer.

It is possible to edit a response to a question within 2 months (60 days), after the response has been submitted and only once.

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
One of
id
required
string

Question ID

wasViewed
required
boolean

If the question was viewed

Responses

Request samples

Content type
application/json
Example

View question

{
  • "id": "n5um6IUBQOOSTxXoo0gV",
  • "wasViewed": true
}

Response samples

Content type
application/json
{
  • "data": null,
  • "error": false,
  • "errorText": "",
  • "additionalErrors": null
}

Get the Question by ID{{ /api/v1/question }}

Описание метода

The method allows you to get a question by its ID

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
string
Example: id=ljAVapEBL38RyMdRln61

Question ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": false,
  • "errorText": "",
  • "additionalErrors": null
}

Feedbacks

To access the methods, use a token for the Feedbacks and Questions category

Unanswered Feedbacks{{ /api/v1/feedbacks/count-unanswered }}

Описание метода

The method allows you to get the number of unanswered feedbacks for today, for all time and get an estimate of all feedbacks

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": false,
  • "errorText": "",
  • "additionalErrors": null
}

Number of Feedbacks{{ /api/v1/feedbacks/count }}

Описание метода

The method allows to get the number of feedbacks

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
query Parameters
dateFrom
integer
Example: dateFrom=1688465092

The start date of the period in Unix timestamp format

dateTo
integer
Example: dateTo=1688465092

The end date of the period in Unix timestamp format

isAnswered
boolean
Example: isAnswered=false

If the feedback was answered:

  • true — yes, by default
  • false — no

Responses

Response samples

Content type
application/json
{
  • "data": 724583,
  • "error": false,
  • "errorText": "",
  • "additionalErrors": null
}

Feedbacks List{{ /api/v1/feedbacks }}

Описание метода

The method allows you to get a list of feedbacks by the specified parameters with pagination and sorting

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
query Parameters
isAnswered
required
boolean
Example: isAnswered=false

If the feedback was answered:

  • true — yes, by default
  • false — no
nmId
integer
Example: nmId=5870243

WB article

take
required
integer
Example: take=1

Number of feedbacks (max. 5 000)

skip
required
integer
Example: skip=0

Number of feedbacks for skip (max. 199990)

order
string
Enum: "dateAsc" "dateDesc"

Sorting of feedbacks by date (dateAsc/dateDesc)

dateFrom
integer
Example: dateFrom=1688465092

The start date of the period in Unix timestamp format

dateTo
integer
Example: dateTo=1688465092

The end date of the period in Unix timestamp format

Responses

Response samples

Content type
application/json
{}

Reply to Feedback{{ /api/v1/feedbacks/answer }}

Описание метода

Allows you to respond to the feedback.
There is no validation by feedback ID: if an incorrect value is provided in the request, you will not receive an error.

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
id
required
string

Feedback ID

text
required
string [ 2 .. 5000 ]

Reply text

Responses

Request samples

Content type
application/json
{
  • "id": "J2FMRjUj6hwvwCElqssz",
  • "text": "Спасибо за Ваш отзыв!"
}

Response samples

Content type
application/json
Example

Content-Type header not specified

{
  • "title": "bad request",
  • "requestId": "e6c4100223db8bf5818b2e5f12705891",
  • "origin": "fbapi",
  • "detail": "content-type header not specified"
}

Edit Response to Feedback{{ /api/v1/feedbacks/answer }}

Описание метода

Allows you to edit an already sent response to the feedback.
You can edit the response only once within 60 days.
There is no validation by feedback ID: if an incorrect value is provided in the request, you will not receive an error.

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
id
required
string

Feedback ID

text
required
string [ 2 .. 5000 ]

Reply text

Responses

Request samples

Content type
application/json
{
  • "id": "J2FMRjUj6hwvwCElqssz",
  • "text": "Спасибо за Ваш отзыв, он очень важен для нас!"
}

Response samples

Content type
application/json
{
  • "title": "unauthorized",
  • "detail": "token problem; token is malformed: could not base64 decode signature: illegal base64 data at input byte 84",
  • "code": "07e4668e--a53a3d31f8b0-[UK-oWaVDUqNrKG]; 03bce=277; 84bd353bf-75",
  • "requestId": "7b80742415072fe8b6b7f7761f1d1211",
  • "origin": "s2s-api-auth-catalog",
  • "status": 401,
  • "statusText": "Unauthorized",
  • "timestamp": "2024-09-30T06:52:38Z"
}

Return Product by Feedback ID{{ /api/v1/feedbacks/order/return }}

Описание метода

The method allows requesting a return for a product for which a feedback has been left.
Return is available for feedbacks with "isAbleReturnProductOrders": true

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
feedbackId
string

Feedback ID

Responses

Request samples

Content type
application/json
{
  • "feedbackId": "absdfgerrrfff1234"
}

Response samples

Content type
application/json
{
  • "data": { },
  • "error": true,
  • "errorText": "string",
  • "additionalErrors": [
    ]
}

Get the Feedback by ID{{ /api/v1/feedback }}

Описание метода

The method allows you to get a feedback by its ID

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
string
Example: id=G7Y9Y1kBAtKOitoBT_lV

Feedback ID

Responses

Response samples

Content type
application/json
{}

List of Archived Feedbacks{{ /api/v1/feedbacks/archive }}

Описание метода

The method allows you to get a list of archived feedbacks.
The feedback becomes archived if:

  • A response to the feedback is received.
  • No response to the feedback is received within 30 days.
  • The feedback contains no text or photos.
Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
query Parameters
nmId
integer
Example: nmId=14917842

WB article

take
required
integer
Example: take=1

Number of feedbacks (max. 5 000)

skip
required
integer
Example: skip=0

Number of feedbacks for skip

order
string
Enum: "dateAsc" "dateDesc"

Sorting of feedbacks by date (dateAsc/dateDesc)

Responses

Response samples

Content type
application/json
{}

Pinned Feedback

To access the methods, use a token for the Feedbacks and Questions category

Use these methods for:

  1. Getting the list of pinned and unpinned feedback
  2. Pinning feedback. The method is available for Jam subscription or Pin a feedback option in the tariff constructor
  3. Unpinning feedback
  4. Getting pinned and unpinned feedback number
  5. Getting pinned feedback limits

List of Pinned and Unpinned Feedback{{ /api/feedbacks/v1/pins }}

Описание метода

The method allows to get the list of pinned and unpinned feedback.
Only automatically unpinned feedback cause of the reasons specified in the response in the unpinnedCause field are considered unpinned.

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
query Parameters
state
string
Enum: "pinned" "unpinned"
Example: state=pinned

If the feedback is pinned:

  • pinned — yes
  • unpinned — no
pinOn
string
Enum: "nm" "imt"
Example: pinOn=nm

Место закрепления отзыва:

  • nm — карточка товара
  • imt — объединённая карточка
imtId
integer
Example: imtId=256972151

Merged product card ID
All WB articles of a merged product card have the same imtId.
Every product card has imtId, even if is not merged with any other card

nmId
integer
Example: nmId=177974151

WB article

feedbackId
integer
Example: feedbackId=789

Feedback ID

dateFrom
string <date-time>
Example: dateFrom=2020-01-01T15:04:05Z

The date the first feedback in the list was pinned

dateTo
string <date-time>
Example: dateTo=2020-02-01T15:04:05Z

The date the last feedback in the list was pinned

next
integer
Example: next=741

The last pinning operation ID (paginator)

limit
integer <= 500
Default: 500
Example: limit=100

Feedback number per page (pagination)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "next": 200
}

Pin Feedback{{ /api/feedbacks/v1/pins }}

Описание метода

The method allows to pin the feedback to the merged product card or to product card.
To get feedback ID, use the List of pinned and unpinned feedback method.

The method is available for Jam subscription or Pin a feedback option in the tariff constructor.

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
Array (<= 500 items)
pinMethod
required
string
Enum: "tariff" "subscription"

Pinning methods:

  • subscription — Jam subscription
  • tariff — tariff option
pinOn
required
string
Enum: "nm" "imt"

Feedback pinning placement:

  • nm — product card
  • imt — merged product card
feedbackId
required
string

Feedback ID

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Unpin Feedback{{ /api/feedbacks/v1/pins }}

Описание метода

The method allows to unpin the feedback in the merged product card or product card.
To get pinId — feedback pinning operation ID, use the List of pinned and unpinned feedback method.

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
required

List of pinId — IDs of feedback pinning operations

Array (<= 500 items)
integer

Responses

Request samples

Content type
application/json
[
  • 123456,
  • 234567,
  • 345678
]

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Pinned and Unpinned Feedback Number{{ /api/feedbacks/v1/pins/count }}

Описание метода

The method returns the number of pinned and unpinned feedback for the period.

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey
query Parameters
state
string
Enum: "pinned" "unpinned"
Example: state=pinned

If the feedback is pinned:

  • pinned — yes
  • unpinned — no
pinOn
string
Enum: "nm" "imt"
Example: pinOn=nm

Feedback pinning placement:

  • nm — product card
  • imt — merged product card
imtId
integer
Example: imtId=256971531

Merged product card ID
All WB articles of a merged product card have the same imtId.
Every product card has imtId, even if is not merged with any other card

nmId
integer
Example: nmId=177974151

WB article

feedbackId
integer
Example: feedbackId=789

Feedback ID

dateFrom
string <date-time>
Example: dateFrom=2020-01-01T15:04:05Z

The date the first feedback in the list was pinned

dateTo
string <date-time>
Example: dateTo=2020-02-01T15:04:05Z

The date the last feedback in the list was pinned

Responses

Response samples

Content type
application/json
{
  • "data": 0
}

Pinned Feedback Limits{{ /api/feedbacks/v1/pins/limits }}

Описание метода

The method returns the pinned feedback limits for a tariff and subscription.

Request limit per one seller's account for all methods in the Feedbacks and Questions category:
Period Limit Interval Burst
1 second 3 requests 333 milliseconds 6 requests
Authorizations:
HeaderApiKey

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Buyers Chat

To access the methods, use a token for the Buyers chat category
Buyers chat allows sellers and buyers to communicate directly.
Buyers can ask questions about products or file complaints. We recommended to respond to the messages in the chat within 10 days.
The buyer always starts the chat. In one chat you can communicate only with one buyer.
Processing requests for product refunds is only available in the web version of buyers chat.

Chat operations:

  1. Get a chat list. Save the chat ID in your database — this will allow you to update the chat information when receiving events.
  2. Get chat events: messages. New chats will have the isNewChat parameter set to true.
  3. Send messages to the chat

Chat List{{ /api/v1/seller/chats }}

Описание метода

Returns a list of all seller's chats.

Request limit per one seller's account:
Period Limit Interval Burst
10 seconds 10 requests 1 second 10 requests
Authorizations:
HeaderApiKey

Responses

Response samples

Content type
application/json
{
  • "result": [
    ],
  • "errors": null
}

Chat Events{{ /api/v1/seller/events }}

Описание метода

Returns an event list for all chats.

To retrieve all events:

  1. Make the first request without a next parameter.
  2. Repeat the request with the next parameter value from the previous response until totalEvents becomes 0. This will indicate that you have received all events.
Request limit per one seller's account:
Period Limit Interval Burst
10 seconds 10 requests 1 second 10 requests
Authorizations:
HeaderApiKey
query Parameters
next
integer

Paginator. Retrieve the next data packet starting from this moment.
Format: Unix timestamp with milliseconds

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "errors": null
}

Send Message{{ /api/v1/seller/message }}

Описание метода

Sends message to the buyer.

Request limit per one seller's account:
Period Limit Interval Burst
10 seconds 10 requests 1 second 10 requests
Authorizations:
HeaderApiKey
Request Body schema: multipart/form-data
required
replySign
required
string <= 255 characters

Chat signature. Can be obtained from chat information or event data if the event contains the "isNewChat": true field.

message
string <= 1000 characters

Message text. Maximum of 1000 symbols.

file
Array of strings <binary> [ items <binary > ]

Files, in JPEG, PDF, or PNG format, maximum size — 5 MB each. Maximum of total file size — 30 MB.

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "errors": [ ]
}

Get File from the Message{{ /api/v1/seller/download/{id} }}

Описание метода

The method provides a file or image from the message by its ID.

Request limit per one seller's account:
Period Limit Interval Burst
10 seconds 10 requests 1 second 10 requests
Authorizations:
HeaderApiKey
path Parameters
id
required
string

File ID from the downloadID field in the chat events method

Responses

Response samples

Content type
application/json

Invalid file ID

{
  • "status": 400,
  • "title": "invalid fileID",
  • "origin": "proxy-chats",
  • "detail": "invalid fileID",
  • "requestId": "62f59a4ce21064f20b1bbc28c85f38d8",
  • "error": "invalid fileID"
}

Buyers Returns

To access the methods, use a token for the Buyers returns category

Buyers Return Applications{{ /api/v1/claims }}

Описание метода

Returns buyers applications for product returns for the current 14 days.

Request limit per one seller's account:
Period Limit Interval Burst
1 minute 20 requests 3 seconds 10 requests
Authorizations:
HeaderApiKey
query Parameters
is_archive
required
boolean
Example: is_archive=true

Application status:

  • false — under review
  • true — in archive
id
string <UUID>
Example: id=fe3e9337-e9f9-423c-8930-946a8ebef80

Application ID

limit
integer <uint> [ 1 .. 200 ]
Example: limit=50

Number of applications in the response. 50 by default

offset
integer <uint> >= 0
Example: offset=0

From which element to start outputting data. 0 by default

nm_id
integer
Example: nm_id=196320101

WB article

Responses

Response samples

Content type
application/json
{
  • "claims": [
    ],
  • "total": 31
}

Answer Buyers Application{{ /api/v1/claim }}

Описание метода

Sends an answer to the buyers application for product return.

Request limit per one seller's account:
Period Limit Interval Burst
1 minute 20 requests 3 seconds 10 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
required

Application answer

id
required
string <UUID>

Application ID

action
required
string

Application action.
Use one of the actions array values from the response of the getting buyers applications method

comment
string [ 10 .. 1000 ] characters

Comment.
Only when "action":"rejectcustom" or "action":"approvecc1". When "action":"rejectcustom" this parameter is required

Responses

Request samples

Content type
application/json
{
  • "id": "fe3e9337-e9f9-423c-8930-946a8ebef80",
  • "action": "rejectcustom",
  • "comment": "The photo is not related to the product in the application"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "title": "Validation error",
  • "detail": "Input model is not valid; Details: The Action field is required.",
  • "requestId": "0HN3PI6JUGFSL:00000004"
}