Управление рассылкой сообщений через REST API

Управление рассылкой сообщений в чате с Telegram-ботом может осуществляться через REST API.

Полный список всех возможных запросов может быть получен в Swagger UI.

http://<IP адрес сервиса>:3300/swagger-ui.html

Запросы поделены на группы по объекту, к которому они относятся.

Для использования метода API необходимо сформировать строку запроса. Строка запроса формируется следующим образом: http://<хост>:<порт>/bot/<остальная часть пути>.

Пример

http://localhost:3300/bot/pushMessage

<хост> – адрес сервера, на котором установлен бот,
<порт> – порт сервиса.

Создание push-уведомления

Описание запроса

Для создания push-уведомления необходимо выполнить запрос типа POST на URL:

http://<хост>:<порт>/bot/pushMessage

В теле запроса указывается текст, который необходимо отправить во все чаты с пользователями.

Добавление промо

Описание запроса

Для добавления промо необходимо выполнить запрос типа POST на URL:

http://<хост>:<порт>/bot/downloadPromotion

Параметры запроса:

Наименование	Возможные значения	Описание	Примечания
name		Наименование промо	Обязательный параметр
description		Описание промо	Обязательный параметр (значение не обязательно)
image		Изображение	Обязательный параметр (значение не обязательно) Изображение должно иметь один из форматов: .PNG, .JPG, .JPEG и размер <1 МБ (значение по умолчанию)
push	true false	Отправка промо во все чаты с пользователями	Необязательный параметр. при значении `true` промо будет отправлено во все чаты с пользователями в виде картинки с описанием, также промо можно просмотреть в разделе "Акции и предложения", при значении `false` промо не будет отправлено во все чаты с пользователями, но промо также можно будет просмотреть в разделе "Акции и предложения" (значение по умолчанию).

Пример curl-запроса

curl --location --request POST 'http://<хост>:<порт>/bot/downloadPromotion?name=<id промо>&description=<описание промо>&push=true' --form 'image=@"/home/user/simple-promotion.png"'

В описании промо могут использоваться символы из таблицы ASCII. Например, если при описании промо необходимо перенести часть текста на новую строку, то в месте переноса строки нужно вставить следующую последовательность символов: &#10.

Промо будет сохранено в БД с возможностью повторной отправки.

Рассылка промо все чаты с пользователями

Описание запроса

Для рассылки промо во все чаты с пользователями необходимо выполнить запрос типа POST на URL:

http://<хост>:<порт>/bot/pushImage

Параметры запроса:

Наименование

Описание

Примечания

name

Наименование промо

Обязательный параметр

description

Описание промо

Обязательный параметр

image

Изображение

Обязательный параметр.

Изображение должно иметь один из форматов: .PNG, .JPG, .JPEG и размер <1 МБ (по умолчанию)

Промо будет отправлено во все чаты с пользователями.

Получение изображения промо

Описание запроса

Чтобы получить изображение промо с указанным наименованием, необходимо выполнить запрос типа GET на URL:

http://<хост>:<порт>/bot/uploadPromotion

Параметры запроса:

Наименование	Описание	Примечания
name	Наименование промо	Обязательный параметр

В результате будет получено изображение по указанному наименованию промо.

Получение списка промо

Описание запроса

Чтобы получить список промо, необходимо выполнить запрос типа GET на URL:

http://<хост>:<порт>/bot/listPromotions

Параметры запроса:

Наименование Возможные значения Описание Примечания

limit Количество промо Обязательный параметр

imageIsNeed

true
false

Получение списка промо с картинками

Необязательный параметр.

при значении true список промо будет отправлен с картинкой,
при значении false список промо будет получен без картинки (значение по умолчанию)

В результате будет получен список промо.

Удаление промо

Описание запроса

Для удаления промо необходимо выполнить запрос типа DELETE на URL:

http://<хост>:<порт>/bot/delete

Параметры запроса:

Наименование	Описание	Примечания
name	Наименование промо	Обязательный параметр

В результате промо с указанным наименованием будет удалено.

Получение состояния задачи, отправленной на рассылку

Описание запроса

Чтобы получить состояние задачи, отправленной на рассылку, необходимо выполнить запрос типа GET на URL:

http://<хост>:<порт>/bot/taskCompletionReport?taskId=<id_задачи_на_рассылку>

Параметры запроса:

Наименование	Описание	Примечания
taskId	Идентификатор задачи на рассылку	Обязательный параметр

В результате будет получено состояние задачи, отправленной на рассылку.

Повторная отправка на рассылку уже завершившейся задачи

Описание запроса

Для повторной отправки завершившейся задачи на рассылку пользователям, не получившим сообщение, необходимо выполнить запрос типа GET на URL:

http://<хост>:<порт>/bot/retryPushTask?taskId=<id_задачи_на_рассылку>

Параметры запроса:

Наименование	Описание	Примечания
taskId	Идентификатор задачи на рассылку	Обязательный параметр

В результате может быть получено два ответа:

- true – при успешной повторной отправке задачи на рассылку,
- false – если задачу на рассылку отправить не удалось или ее не существует.

Запрос списка активных рассылок

Описание запроса

Для запроса списка активных рассылок необходимо выполнить запрос типа GET на URL:

http://<хост>:<порт>/bot/scheduleMail

Параметры запроса:

Наименование	Описание	Примечания
offset	Элемент, с которого начинается поиск
limit	Максимальное количество возвращаемых элементов

В результате будет получен список активных рассылок.

Количество активных рассылок

Описание запроса

Для запроса количества активных рассылок необходимо выполнить запрос типа GET на URL:

http://<хост>:<порт>/bot/scheduleMail/count

В результате будет получено общее количество активных рассылок.

Создание рассылки по идентификатору промо

Описание запроса

Для создания рассылки по идентификатору промо необходимо выполнить POST запрос на URL:

http://<хост>:<порт>/bot/scheduleMail

Параметры запроса:

Наименование	Описание	Примечания
name	Идентификатор промо	Обязательный параметр

В теле запроса передаются следующие параметры:

Наименование	Описание	Примечания
cron	Cron-выражение	Используется при рассылке по расписанию
startAt	Дата начала периода рассылки (если значение параметра cron не задано, то Дата отправки сообщения)	Если значение параметра не задано, то в качестве значения по умолчанию будет установлена текущая дата
endAt	Дата окончания периода рассылки	Используется при рассылке по расписанию
phoneNumbers	Список номеров, на которые будет осуществлена рассылка	Если значение параметра не задано, то рассылка будет осуществляться на все номера, зарегистрированные в Telegram-боте

Пример тела запроса

{
    "cron": "0 40 9 * * 1",
    "startAt": "2023-10-25 00:00:00",
    "endAt": "2024-10-25 00:00:00",
    "phoneNumbers": "[]"
}

В результате будет создана рассылка с данными, указанными в параметрах запроса.

Редактирование рассылки

Описание запроса

Для редактирования рассылки необходимо выполнить PUT запрос на URL:

http://<хост>:<порт>/bot/scheduleMail

В теле запроса передается объект MailDto, параметры которого необходимо изменить:

Наименование	Описание	Примечания
id	Идентификатор рассылки	Обязательный параметр
promotion	Идентификатор промо	Обязательный параметр
cron	Cron-выражение	Если значение параметра не задано, промо из рассылки по расписанию перейдёт в рассылку по времени
targetPhones	Список номеров, на которые будет осуществлена рассылка	Если значение параметра не задано, то рассылка будет осуществляться на все номера, зарегистрированные в Telegram-боте
startTime	Дата начала периода рассылки	Если значение параметра не задано, то в качестве значения по умолчанию будет установлена текущая дата
endTime	Дата окончания периода рассылки	Используется при рассылке по расписанию

В результате данные существующей рассылки будут изменены.

Удаление рассылки

Описание запроса

Для удаления рассылки необходимо выполнить запрос типа DELETE на URL:

http://<хост>:<порт>/bot/scheduleMail

Параметры запроса:

Наименование	Описание	Примечания
mailId	Идентификатор рассылки	Обязательный параметр

В результате рассылка по указанному идентификатору будет удалена.

Page tree

Управление рассылкой сообщений через REST API