Динамические рассылки
Динамические рассылки позволяют отправлять большие объемы персонализированных сообщений клиентам. Их можно запускать напрямую из сценариев бота или интегрировать со сторонними сервисами через API. В отличие от обычных рассылок, динамические рассылки формируют контент индивидуально для каждого получателя, что повышает релевантность и вовлеченность.
Отправка сообщений
Шаг 1. Создание текстовой рассылки
- Описание: создается текстовая рассылка, которая будет использоваться как основа для отправки сообщений. Это делается через API.
- Метод:
POST /text-campaign-service/projects/{projectShortName}/text-campaigns, параметрisDynamicдолжен бытьtrue.
- Особенности:
- Динамическая рассылка становится активной сразу после создания.
- При создании рассылки через API можно задать количество потоков и интервал отправки сообщений.
- Результат: возвращается идентификатор рассылки для привязки шаблонов и отправки сообщений.
Шаг 2. Создание шаблона отправки
- Описание: создается шаблон сообщения для конкретного клиента. Шаблон фиксирует данные для отправки, но сообщение не отправляется.
- Методы:
- Особенности:
- Шаблон может содержать данные по умолчанию, которые будут использоваться при отправке, но могут быть переопределены.
- Есть два типа сообщений:
- В качестве параметра вы можете передать
callbackUrlдля получения уведомлений о статусе отправки сообщений, а также указатьpriorityдля управления порядком отправки.
- Результат: возвращается уникальный идентификатор шаблона и ссылка для отправки сообщений.
Шаг 3. Отправка сообщения по шаблону
-
Описание: после создания шаблона нужно инициировать отправку сообщения конкретному клиенту. На этом этапе можно переопределить данные, указанные в шаблоне.
к сведениюПри необходимости вы можете отправить сообщение без привязки к шаблону, но в рамках созданной рассылки. Для этого используйте методы:
-
Методы:
GET /text-campaign-service/dynamics/send-event-by-template/{eventSendingTemplateUuid}— отправка с использованием данных, указанных в шаблоне.POST /text-campaign-service/dynamics/send-event-by-template/{eventSendingTemplateUuid}— отправка с переопределением данных, напримерeventData.$jsapi.sendToDynamicTextCampaign()— отправка сообщения из сценарии бота с возможностью переопределения данных и без.
-
Особенности:
- Если отправляется
event, сообщение обрабатывается в сценарии и может быть выполнено дополнительное действие, например переход в определенный стейт. - Если используется
replies, сообщение отправляется напрямую в канал без дополнительных обработок.
- Если отправляется
-
Результат: сообщение добавляется в очередь отправки, затем отправляется клиенту. В ответ возвращается идентификатор отправки.
Чтобы отменить отправку сообщения, вы можете использовать методы:
Управление рассылками
Помимо создания рассылки, вам также доступны методы управления ими:
-
Обновление рассылки:
PUT /text-campaign-service/projects/{projectShortName}/text-campaigns/{textCampaignId}— обновление параметров рассылки, например изменение количества потоков отправки или интервала между сообщениями. -
Остановка динамической рассылки:
PUT /text-campaign-service/projects/{projectShortName}/text-campaigns/{textCampaignId}/stop— остановка рассылки предотвращает дальнейшую отправку сообщений. В дальнейшем вы можете запустить ее снова с помощью методаPUT /text-campaign-service/projects/{projectShortName}/text-campaigns/{textCampaignId}/resume. -
Завершение динамической рассылки:
PUT /text-campaign-service/projects/{projectShortName}/text-campaigns/{textCampaignId}/complete— в рамках рассылки больше нельзя будет отправлять сообщения, история отправленных сообщений сохранится. -
Получение истории отправки сообщений по шаблону рассылки и связанных сообщений:
GET /text-campaign-service/dynamics/sending-templates/chat-history— возвращает историю сообщений, связанных с сообщением или шаблоном отправки, а также полную историю общения клиента с ботом в указанном временном диапазоне.
Скорость отправки
Мессенджеры, например Telegram, ограничивают частоту отправки сообщений. Чтобы избежать блокировки при массовых рассылках, управляйте скоростью отправки.
Для этого при создании или обновлении динамической рассылки через API используйте следующие параметры:
threadCount— количество потоков. Определяет, сколько сообщений отправляется одновременно. Значение по умолчанию — 1, возможные значения: 1–10.delayBetweenSending— пауза в миллисекундах между отправками сообщений в одном потоке. Значение по умолчанию — 0, возможные значения: 0–60000.
Получение статусов доставки
Чтобы отслеживать статусы доставки сообщений во внешней системе, вы можете использовать механизм обратных вызовов (callback).
Для этого при создании шаблона отправки или при отправке сообщения укажите параметр callbackUrl.
На этот URL платформа будет асинхронно отправлять POST-запросы с информацией о финальном статусе доставки каждого сообщения.
Структура callback-события
POST-запрос на callbackUrl содержит JSON-объект следующей структуры:
| Поле | Тип | Описание |
|---|---|---|
textCampaignId | Число | ID рассылки, в рамках которой было отправлено сообщение. |
eventSendingTemplateId | Строка | UUID шаблона отправки, если он использовался. |
eventSendingInfoId | Строка | UUID конкретной отправки сообщения. |
status | Строка | Финальный статус доставки сообщения. Возможные значения:
|
eventSendingTime | Строка | Время отправки сообщения в формате ISO 8601. |
errorChannelStatus | Строка | Код ошибки от канала, если errorChannelStatus читайте ниже. |
errorChannelStatusDescription | Строка | Текстовое описание ошибки от канала. |
questionId | Строка | Уникальный идентификатор запроса. |
chatId | Строка | Идентификатор чата с клиентом. |
sessionId | Строка | Идентификатор сессии диалога. |
- При ошибке в каком-либо канале придет статус
NOT_DELIVERED. Если ошибок несколько, то полеerrorChannelStatusбудет заполнено по первой возникшей ошибке. - Сообщение из нескольких частей, например текст и картинка, обрабатывается как единое целое. Если не доставлена хотя бы одна его часть, все сообщение получит статус
NOT_DELIVERED.
Пример JSON-объекта
{
"textCampaignId": 42,
"eventSendingTemplateId": "12345678-abcd-4ef0-9012-345678901234",
"eventSendingInfoId": "abcdef01-2345-4678-9abc-def012345678",
"status": "NOT_DELIVERED",
"errorChannelStatus": "FORBIDDEN",
"errorChannelStatusDescription": "403 ERROR. Bot was blocked by the user.",
"eventSendingTime": "2024-01-15T10:30:00Z",
"questionId": "98765432-fedc-4ba9-8765-432109876543",
"chatId": "telegram:987654321",
"sessionId": "00000000-1111-2222-3333-444444444444"
}
Детализация статусов ошибок
При статусе NOT_DELIVERED поле errorChannelStatus содержит один из стандартизированных кодов ошибки.
В таблице ниже показано соответствие этих кодов исходным ошибкам каналов.
Значение errorChannelStatus | Описание | Исходные коды ошибок каналов |
|---|---|---|
BAD_REQUEST | Некорректные данные: недопустимый формат номера, синтаксическая ошибка или отправка несуществующему пользователю. |
|
FORBIDDEN | Доступ запрещен: пользователь заблокировал бота, отключил уведомления, или отправитель в списке заблокированных. |
|
TOO_MANY_REQUESTS | Превышение лимитов: слишком много запросов к API канала за единицу времени. |
|
INTERNAL_SERVER_ERROR | Техническая ошибка: временная недоступность сервисов, проблемы с сетью или внутренние сбои. |
|
OTHER_ERRORS | Прочие ошибки: специфические ошибки канала, не вошедшие в указанные выше категории. |
|
Списки кодов основаны на официальной документации каналов и могут изменяться. errorChannelStatusDescription всегда содержит исходный код и описание ошибки.