Сообщения
Чтение переписки, ответ посетителю, идемпотентность и признак источника.
На этой странице
Переписка #
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| cursor | RFC 3339 | нет | продолжение предыдущей страницы |
| limit | int | нет | 1…100, по умолчанию 25 |
{"data": [{
"id": "7735af47-2e36-45fd-9543-83f67b6d7eef",
"direction": "outgoing",
"senderType": "admin",
"content": "Заказ уже в пути",
"messageType": "text",
"origin": "api",
"createdAt": "2026-08-22T09:15:04.281Z",
"editedAt": null,
"attachments": []
}], "hasMore": false}Объект message #
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| id | uuid | да | номер сообщения |
| direction | string | да | incoming — посетитель, outgoing — поддержка |
| senderType | string | да | customer, admin, system |
| content | string | да | текст |
| messageType | string | да | text, image, document, audio, video |
| origin | string | да | откуда написано: widget, telegram, api, bitrix24, amocrm, retailcrm, unknown |
| createdAt | RFC 3339 | да | когда записано |
| editedAt | RFC 3339|null | нет | когда исправлено |
| attachments[] | object | нет | вложения, см. раздел «Вложения» |
🔴 origin нужен, чтобы не зациклиться: получив событие о собственном ответе, ваша система не должна отправить его второй раз.
Ответить посетителю #
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| content | string | нет | текст до 4096 символов; обязателен, если нет file |
| file.url | string | нет | ссылка на файл: мы скачаем его сами, до 50 МБ |
| file.name | string | нет | имя файла для переписки |
| file.type | string | нет | image, document, audio, video |
POST /api/v1/conversations/6c82f8e2-…/messages
Idempotency-Key: reply-4417
Content-Type: application/json
{"content": "Заказ уже в пути",
"file": {"url": "https://example.ru/act.pdf", "name": "Акт.pdf", "type": "document"}}201 {"data": {"id": "7735af47-…", "content": "Заказ уже в пути",
"createdAt": "2026-08-22T09:15:04.281Z", "direction": "outgoing", "status": "queued"}}
200 {"data": {"id": "7735af47-…", "duplicate": true}}Файл забирается до записи сообщения: недоступная ссылка не оставит в переписке пустой ответ. Запросы к вашему адресу идут мимо прокси и не во внутреннюю сеть.
Idempotency-Key #
Заголовок делает повтор безопасным: связь может оборваться после того, как запрос уже приняли. Повторная отправка с тем же ключом вернёт 200 и duplicate: true вместо второго сообщения.
Допустимы до 128 символов из A-Z a-z 0-9 . _ : - Ключ действует в пределах вашего ключа доступа: два разных ключа доступа с одинаковым Idempotency-Key друг другу не мешают.
Что означает status: queued #
Ответ принят в доставку и уйдёт в окно посетителя той же очередью, что и ответ оператора из Telegram. Отдельного признака «доставлено» у API нет: событие message.created придёт вам на общих основаниях, а видимость ответа посетителем отражает поле lastReadAt разговора.