> For the complete documentation index, see [llms.txt](https://docs.suvvy.ai/ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.suvvy.ai/ru/kanaly/personalnyi-kanal-api/poluchenie-soobshenii.md).

# Получение сообщений

{% hint style="info" %}
Для тестирования работы вебхука можно использовать [этот сервис](https://webhook.site/)
{% endhint %}

Для подключения персонального канала, вы должны указать вебхук, на который Савви будет отправлять сообщения. Он будет делать это в следующем виде:

## Запрос

{% hint style="danger" %}
Ваш вебхук должен возвращать статус код в диапазоне **200-299** и отвечать в течение **20 секунд**. В противном случае запрос считается ошибочным, а сообщения — недоставленными *(такие сообщения Савви не видит)*.
{% endhint %}

{% hint style="warning" %}
Ваш вебхук будет получать запросы **с разных IP-адресов.** Для проверки и авторизации используйте настройку **«Секрет вебхука»**.
{% endhint %}

Мы сделаем **POST** запрос на ваш вебхук, передав туда тело следующего вида:

```json
{
  "event_type": "new_messages",
  "new_messages": [
    {
      "type": "image",
      "message_sender": "ai",
      "file": {
        "name": "image.png",
        "url": "<прямая ссылка на изображение>",
        "size_bytes": 10240,
        "mime_type": "image/png"
      }
    },
    {
      "type": "text",
      "message_sender": "ai",
      "text": "Привет! Как я могу вам помочь?"
    }
  ]
}
```

Если при подключении персонального канала, вы указали **секрет вебхука,** то мы передадим его в заголовке `Authorization` в следующем виде:

```
Bearer <ваш секрет>
```

### Объект в запросе

| Поле           | Тип                                        | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_type`   | строка (`new_messages` или `test_request`) | <p><strong>Тип события.</strong></p><p>На данный момент реализовано только событие для новых сообщений и тестовый запрос, но в будущем можем добавить и другие.</p><p>В зависимости от этого параметра набор полей может измениться</p><p><code>test\_request</code> - событие который мы пришлем на ваш вебхук при нажатии на кнопку проверки в ЛК Савви</p><p>Рекомендуем проверять данный параметр и игнорировать запрос, если <code>event\_type != "new\_messages"</code></p> |
| `new_messages` | массив объектов `Message`                  | <p><strong>Новые сообщения.</strong></p><p>Присутствует только если тип события - <code>new\_messages</code></p>                                                                                                                                                                                                                                                                                                                                                                  |
| `chat_id`      | строка                                     | <p><strong>Айди чата.</strong></p><p>Айди чата, который вы указывали при отправке запроса на наш АПИ. Нужен, чтобы вы могли в своей системе идентифицировать, в какой чат добавить ответ.<br>Присутствует только если тип события - <code>new\_messages</code></p>                                                                                                                                                                                                                |

#### Объект `Message`

| Поле             | Тип                                           | Описание                                                                                                                                                         |
| ---------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`           | строка (`text`, `image`, `audio`, `document`) | <p><strong>Тип сообщения.</strong></p><p>От этого параметра зависит набор полей</p>                                                                              |
| `message_sender` | строка (`ai` или `employee`)                  | <p><strong>Отправитель сообщения.</strong></p><p>Присутствует во всех типах, определяет кто прислал сообщение (бот или сотрудник через личный кабинет Савви)</p> |
| `text`           | строка                                        | <p><strong>Текст сообщения.</strong></p><p>Присутствует только, если тип сообщения - <code>text</code></p>                                                       |
| `file`           | объект `MessageFile`                          | <p><strong>Приложенный файл.</strong></p><p>Присутствует только, если тип сообщения - <code>image</code>, <code>audio</code> или <code>document</code></p>       |

#### Объект `MessageFile`

| Поле         | Тип                                     | Описание                                                                                                                                                                                                |
| ------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`        | строка                                  | <p><strong>Прямая ссылка для загрузки файла.</strong></p><p>Например: <a href="https://i.imgur.com/ucYKBpa.png"><https://i.imgur.com/ucYKBpa.png></a></p><p>Файл будет расположен на нашем сервере.</p> |
| `name`       | строка                                  | **Имя файла.**                                                                                                                                                                                          |
| `size_bytes` | целое число ∈ `[0, +∞)`                 | **Размер файла в байтах.**                                                                                                                                                                              |
| `mime_type`  | строка `^[a-zA-Z0-9]+/[a-zA-Z0-9-.+]+$` | **Mime-тип файла.**                                                                                                                                                                                     |

Савви может отправить файлы следующих типов:

* Для изображений: `image/png`, `image/jpeg`, `image/gif`
* Для аудио: `audio/ogg`, `audio/mpeg`, `audio/wav`, `audio/x-wav`, `audio/webm`, `audio/mp4`, `audio/m4a`, `audio/x-m4a`
* Для документов: **любые**, включая вышеперечисленные


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.suvvy.ai/ru/kanaly/personalnyi-kanal-api/poluchenie-soobshenii.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.