Сообщения

Сообщения, информирующие о совершении определенных изменений в ходе выполнения бизнес-логики, могут быть отправлены не только на платформу, но в том числе и во внешние сервисы. Для организации работы над сообщениями используются HTTP-запросы в API платформы, которые позволяют реализовывать следующие операции:

  1. Получение списка сообщений.
  2. Создание нового сообщения.
  3. Изменение статуса сообщения.
  4. Очистка списка сообщений.
  5. Выгрузка сообщений из истории.
  6. Выгрузка сообщений из истории по интервалу.

Получение списка сообщений

Для получения полного списка сообщений необходимо послать запрос GET api/v1/messages. Стоит учитывать, что если в запрос не добавлять дополнительные ограничения по количеству выгружаемых сообщений, в ответе на него будет получено ровно столько же сообщений, сколько их указано для данной учетной записи пользователя в графическом интерфейсе. В данном примере, напротив, указаны границы начала и окончания забора сообщений в соответствии с правилами формирования временных границ (см. раздел "HTTP REST API", подраздел "Общие принципы формирования запросов", пункт "Работа со списками").

Запрос

GET api/v1/messages?begin=1569438000000&end=1569468100000 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Ответ

HTTP/1.1 200 OK

[
    {
        "_id": "5d8c2eb3c79fe347384cf531",
        "type": "object",
        "time": 1569468083027,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    },
    {
        "_id": "5d8bbaa4c82fdf001125a382",
        "type": "object",
        "time": 1569438372808,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    }
]

Создание нового сообщения

Для того чтобы создать новое сообщение и отправить его на платформу из внешнего сервиса, необходимо использовать метод POST. При этом в теле запроса указывается текст сообщения и все необходимые для конфигурации поля.

Запрос

POST /api/v1/messages HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

BODY

Ответ

HTTP/1.1 200 OK

BODY

Изменение статуса сообщения

Для того чтобы изменить статус сообщения и отметить его как прочитанное или же, напротив, непрочитанное, необходимо изменить поле read. Для прочитанного сообщения значение его поля равно true, для непрочитанного - false.

Стоит отметить, что так как сообщение, полученное объекта, нельзя рассматривать как сущность, его идентификатор нельзя просмотреть в меню "Редактирование", которое в свою очередь располагается в меню "Администрирование". Поэтому чтобы узнать идентификатор нужного пользователю сообщения, рекомендуется в начале выгрузить список сообщений, в котором отображаются все необходимые сведения.

Запрос

PATCH /api/v1/messages/read/:id HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

BODY

Ответ

HTTP/1.1 200 OK

BODY

Очистка списка сообщений

Для удаления и очистки всего списка сообщений отправляется запрос DELETE /api/v1/messages/clear.

Запрос

DELETE /api/v1/messages/clear HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Ответ

HTTP/1.1 200 OK

BODY

Выгрузка сообщений из истории

Как и для объектов, в системе хранится история сообщений, которая может быть просмотрена пользователем. При выгрузке полного списка сообщений из истории в ответе на запрос возвращается массив сообщений.

Запрос

GET /api/v1/messages/history HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Ответ

HTTP/1.1 200 OK

[
    {
        "_id": "5d8c2eb3c79fe347384cf531",
        "type": "object",
        "time": 1569468083027,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    },
    {
        "_id": "5d8bbaa4c82fdf001125a382",
        "type": "object",
        "time": 1569438372808,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    },
    {
        "_id": "5d8b11c2d0025e0012fd7100",
        "type": "object",
        "time": 1569395137986,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    }
]

Выгрузка сообщений из истории по интервалу

Для того чтобы вместо полного списка сообщений получить только их количество, первое и последнее сообщение, необходимо послать запрос GET /api/v1/messages/history/bounds, ресурс которого указывает на сужение отображаемой информации в сравнении с предыдущим запросом.

Запрос

GET /api/v1/messages/history/bounds HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Ответ

HTTP/1.1 200 OK

{
    "count": 8,
    "min": {
        "_id": "5d8a6c965d60133726d3a478",
        "type": "object",
        "time": 1569352854108,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    },
    "max": {
        "_id": "5d8c2eb3c79fe347384cf531",
        "type": "object",
        "time": 1569468083027,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    },
    "success": true
}