Управление рассылкой сообщений в чате с Telegram-ботом может осуществляться через REST 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. Например, если при описании промо необходимо перенести часть текста на новую строку, то в месте переноса строки нужно вставить следующую последовательность символов: &#13;&#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Идентификатор промоОбязательный параметр

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

НаименованиеОписаниеПримечания
cronCron-выражениеИспользуется при рассылке по расписанию
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Идентификатор промоОбязательный параметр
cronCron-выражениеЕсли значение параметра не задано, промо из рассылки по расписанию перейдёт в рассылку по времени
targetPhonesСписок номеров, на которые будет осуществлена рассылкаЕсли значение параметра не задано, то рассылка будет осуществляться на все номера, зарегистрированные в Telegram-боте
startTimeДата начала периода рассылкиЕсли значение параметра не задано, то в качестве значения по умолчанию будет установлена текущая дата
endTimeДата окончания периода рассылкиИспользуется при рассылке по расписанию

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

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

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

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

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

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

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

swagger: '2.0' info: version: '1.0' title: Swagger Api Documentation tags: - name: user-statistics-controller description: User Statistics Controller - name: restfull description: Restfull - name: mail-rest-controller description: Mail Rest Controller - name: advertising-rest-controller description: Advertising Rest Controller paths: /bot/advertising: get: tags: - advertising-rest-controller summary: getAdvertisingByPromoName operationId: getAdvertisingByPromoNameUsingGET consumes: - application/json produces: - '*/*' parameters: - name: name in: query description: name required: true type: string responses: '200': description: OK schema: $ref: '#/definitions/Optional«AdvertisingDao»' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found post: tags: - advertising-rest-controller summary: saveAdvertising operationId: saveAdvertisingUsingPOST consumes: - application/json produces: - '*/*' parameters: - name: promotionName in: query description: promotionName required: true type: string - name: type in: query description: type required: true type: string - name: active in: query description: active required: true type: boolean - name: deletePromoAfterComplete in: query description: deletePromoAfterComplete required: false type: boolean - name: cron in: query description: cron required: false type: string - name: startTime in: query description: startTime required: false type: string - name: endTime in: query description: endTime required: false type: string - name: mailId in: query description: mailId required: false type: string - name: phoneNumbers in: query description: phoneNumbers required: false type: array items: type: string collectionFormat: multi responses: '200': description: OK '201': description: Created '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/bonusesUsers/count: get: tags: - restfull summary: getBonusesUsersCount operationId: getBonusesUsersCountUsingGET consumes: - application/json produces: - '*/*' responses: '200': description: OK schema: type: integer format: int64 '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/delete: delete: tags: - restfull summary: removePromotion operationId: removePromotionUsingDELETE consumes: - application/json produces: - '*/*' parameters: - name: name in: query description: name required: true type: string responses: '200': description: OK '204': description: No Content '401': description: Unauthorized '403': description: Forbidden /bot/detailTaskCompletionReport: get: tags: - restfull summary: taskCompletionDetailReport operationId: taskCompletionDetailReportUsingGET consumes: - application/json produces: - '*/*' parameters: - name: taskId in: query description: taskId required: true type: string responses: '200': description: OK schema: $ref: '#/definitions/PushTaskExecuteDetailReport' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/downloadPromotion: post: tags: - restfull summary: downloadPromotion operationId: downloadPromotionUsingPOST consumes: - multipart/form-data produces: - '*/*' parameters: - name: name in: query description: name required: true type: string - name: description in: query description: description required: true type: string - name: image in: formData description: image required: true type: file - name: push in: query description: push required: false type: boolean default: false responses: '200': description: OK schema: type: string '201': description: Created '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/getSourceImage: get: tags: - restfull summary: getSourceImage operationId: getSourceImageUsingGET consumes: - application/json produces: - '*/*' parameters: - name: name in: query description: name required: true type: string responses: '200': description: OK schema: $ref: '#/definitions/SourceFile' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/licence/expirationDate: get: tags: - restfull summary: getCurrentLicenceExpirationDate operationId: getCurrentLicenceExpirationDateUsingGET consumes: - application/json produces: - '*/*' responses: '200': description: OK schema: $ref: '#/definitions/LicenceExpDateResult' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/listPromotions: get: tags: - restfull summary: downloadPromotions operationId: downloadPromotionsUsingGET consumes: - application/json produces: - '*/*' parameters: - name: limit in: query description: limit required: false type: integer default: 10 format: int32 - name: offset in: query description: offset required: false type: integer default: 0 format: int32 - name: imageIsNeed in: query description: imageIsNeed required: false type: boolean default: false responses: '200': description: OK schema: type: array items: $ref: '#/definitions/Promotion' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/listPromotions/count: get: tags: - restfull summary: getPromotionsCount operationId: getPromotionsCountUsingGET consumes: - application/json produces: - '*/*' responses: '200': description: OK schema: type: integer format: int64 '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/pushImage: post: tags: - restfull summary: pushImage operationId: pushImageUsingPOST consumes: - multipart/form-data produces: - '*/*' parameters: - name: name in: query description: name required: true type: string - name: description in: query description: description required: true type: string - name: image in: formData description: image required: true type: file responses: '200': description: OK schema: type: string '201': description: Created '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/pushImageByPhoneNumbers: post: tags: - restfull summary: pushImageByPhoneNumbers operationId: pushImageByPhoneNumbersUsingPOST consumes: - multipart/form-data produces: - '*/*' parameters: - name: description in: query description: description required: true type: string - name: file in: formData description: file required: true type: file - name: phoneNumbers in: formData description: phoneNumbers required: true type: array items: type: string collectionFormat: multi responses: '200': description: OK schema: type: string '201': description: Created '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/pushImageToUser: post: tags: - restfull summary: pushImageToUser operationId: pushImageToUserUsingPOST consumes: - multipart/form-data produces: - '*/*' parameters: - name: description in: query description: description required: true type: string - name: image in: formData description: image required: true type: file - name: phoneNumber in: query description: phoneNumber required: true type: string responses: '200': description: OK '201': description: Created '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/pushMessage: post: tags: - restfull summary: pushMessage operationId: pushMessageUsingPOST consumes: - application/json produces: - '*/*' parameters: - in: body name: message description: message required: true schema: type: string responses: '200': description: OK schema: type: string '201': description: Created '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/pushMessageToUser: post: tags: - restfull summary: pushMessageToUser operationId: pushMessageToUserUsingPOST consumes: - application/json produces: - '*/*' parameters: - name: phoneNumber in: query description: phoneNumber required: true type: string - in: body name: message description: message required: true schema: type: string responses: '200': description: OK '201': description: Created '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/pushPromotion: get: tags: - restfull summary: pushPromotion operationId: pushPromotionUsingGET consumes: - application/json produces: - '*/*' parameters: - name: name in: query description: name required: true type: string responses: '200': description: OK schema: type: string '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/pushPromotionToUser: get: tags: - restfull summary: pushPromotionToUser operationId: pushPromotionToUserUsingGET consumes: - application/json produces: - '*/*' parameters: - name: name in: query description: name required: true type: string - name: phoneNumber in: query description: phoneNumber required: true type: string responses: '200': description: OK schema: type: string '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/retryPushTask: get: tags: - restfull summary: retryPushTask operationId: retryPushTaskUsingGET consumes: - application/json produces: - '*/*' parameters: - name: taskId in: query description: taskId required: true type: string responses: '200': description: OK schema: type: boolean '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/scheduleMail: get: tags: - mail-rest-controller summary: getMails operationId: getMailsUsingGET consumes: - application/json produces: - '*/*' parameters: - name: offset in: query description: offset required: false type: integer default: 0 format: int32 - name: limit in: query description: limit required: false type: integer default: 10 format: int32 responses: '200': description: OK schema: type: array items: $ref: '#/definitions/MailDto' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found post: tags: - mail-rest-controller summary: saveMail operationId: saveMailUsingPOST consumes: - application/json produces: - '*/*' parameters: - name: name in: query description: name required: true type: string - name: cron in: query description: cron required: false type: string - name: startAt in: query description: startAt required: false type: string - name: endAt in: query description: endAt required: false type: string - name: phoneNumbers in: query description: phoneNumbers required: false type: array items: type: string collectionFormat: multi responses: '200': description: OK schema: $ref: '#/definitions/MailDto' '201': description: Created '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found put: tags: - mail-rest-controller summary: updateMail operationId: updateMailUsingPUT consumes: - application/json produces: - '*/*' parameters: - in: body name: mail description: mail required: true schema: $ref: '#/definitions/MailDto' responses: '200': description: OK '201': description: Created '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found delete: tags: - mail-rest-controller summary: removeMail operationId: removeMailUsingDELETE consumes: - application/json produces: - '*/*' parameters: - name: mailId in: query description: mailId required: true type: string responses: '200': description: OK '204': description: No Content '401': description: Unauthorized '403': description: Forbidden /bot/scheduleMail/count: get: tags: - mail-rest-controller summary: getMailsCount operationId: getMailsCountUsingGET consumes: - application/json produces: - '*/*' responses: '200': description: OK schema: type: integer format: int64 '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/taskCompletionReport: get: tags: - restfull summary: taskCompletionReport operationId: taskCompletionReportUsingGET consumes: - application/json produces: - '*/*' parameters: - name: taskId in: query description: taskId required: true type: string responses: '200': description: OK schema: $ref: '#/definitions/PushTaskExecuteReport' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/tasksCompletionReports: get: tags: - restfull summary: tasksCompletionReports operationId: tasksCompletionReportsUsingGET consumes: - application/json produces: - '*/*' responses: '200': description: OK schema: type: array items: $ref: '#/definitions/PushTaskExecuteReport' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/uploadPromotion: get: tags: - restfull summary: downloadPromotion operationId: downloadPromotionUsingGET consumes: - application/json produces: - '*/*' parameters: - name: name in: query description: name required: true type: string responses: '200': description: OK schema: type: object '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /bot/userstatistics/by-range: get: tags: - user-statistics-controller summary: Получить статистику по подписавшимся/покинувшим бота пользователям operationId: getStatistcisByRangeUsingGET consumes: - application/json produces: - '*/*' parameters: - name: from in: query description: Дата с которой нужна статистика required: true type: string format: date - name: to in: query description: Дата по которую нужна статистика. Если не будет указана, то берется вчерашняя дата required: false type: string format: date responses: '200': description: OK schema: type: array items: $ref: '#/definitions/UserStatisticsRecord' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found definitions: AdvertisingDao: type: object properties: active: type: boolean mailId: type: string promotion: type: string targetPhones: type: array items: type: string type: type: string enum: - NO_ADVERTISING - ALWAYS_ACTIVE - PERIOD_ACTIVE - SELECT_DAYS File: type: object properties: absolute: type: boolean absoluteFile: $ref: '#/definitions/File' absolutePath: type: string canonicalFile: $ref: '#/definitions/File' canonicalPath: type: string directory: type: boolean executable: type: boolean file: type: boolean freeSpace: type: integer format: int64 hidden: type: boolean lastModified: type: integer format: int64 name: type: string parent: type: string parentFile: $ref: '#/definitions/File' path: type: string readable: type: boolean totalSpace: type: integer format: int64 usableSpace: type: integer format: int64 writable: type: boolean InputStream: type: object LicenceExpDateResult: type: object properties: code: type: integer format: int32 expirationDate: type: string format: date message: type: string MailDto: type: object properties: cron: type: string endTime: type: string format: date-time id: type: string promotion: type: string startTime: type: string format: date-time targetPhones: type: array items: type: string Optional«AdvertisingDao»: type: object properties: present: type: boolean Promotion: type: object properties: description: type: string image: $ref: '#/definitions/SourceFile' name: type: string PushTaskExecuteDetailReport: type: object properties: promotionName: type: string states: type: object additionalProperties: type: string PushTaskExecuteReport: type: object properties: allNumbers: type: integer format: int32 failed: type: integer format: int32 idTask: type: string namePromotion: type: string notFound: type: integer format: int32 status: type: string success: type: integer format: int32 waiting: type: integer format: int32 Resource: type: object properties: description: type: string file: $ref: '#/definitions/File' filename: type: string inputStream: $ref: '#/definitions/InputStream' open: type: boolean readable: type: boolean uri: $ref: '#/definitions/URI' url: $ref: '#/definitions/URL' SourceFile: type: object properties: content: type: string format: byte fileName: type: string mediaType: type: string URI: type: object properties: absolute: type: boolean authority: type: string fragment: type: string host: type: string opaque: type: boolean path: type: string port: type: integer format: int32 query: type: string rawAuthority: type: string rawFragment: type: string rawPath: type: string rawQuery: type: string rawSchemeSpecificPart: type: string rawUserInfo: type: string scheme: type: string schemeSpecificPart: type: string userInfo: type: string URL: type: object properties: authority: type: string content: type: object defaultPort: type: integer format: int32 file: type: string host: type: string path: type: string port: type: integer format: int32 protocol: type: string query: type: string ref: type: string userInfo: type: string UserStatisticsRecord: type: object properties: date: type: string format: date subscribedAmount: type: integer format: int32 unsubscribedAmount: type: integer format: int32
  • No labels