Text Campaign API
Text Campaign API — набор методов для управления динамическими текстовыми рассылками в вашем проекте. API позволяет внешним системам, СRM и другим сервисам управлять рассылками в ваших ботах.
С помощью Text Campaign API можно:
- Получать список рассылок.
- Создавать новые рассылки.
- Получать, обновлять, останавливать или завершать рассылки.
- Создавать, получать и удалять шаблоны рассылок.
- Отправлять события по шаблону (с параметрами по умолчанию или пользовательскими).
- Отправлять события без шаблона.
- Отправлять ответы клиентам напрямую.
- Просматривать историю рассылок и чатов.
Подробное описание методов, параметров запросов и форматов ответов представлено в спецификации.
Авторизация
Получите единый токен в разделе Доступ к API и используйте его в запросах как bearer-токен.
Получение статусов доставки
При использовании параметра callbackUrl в методах создания шаблонов или отправки сообщений вы будете получать уведомления о статусах доставки.
Структура 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 всегда содержит исходный код и описание ошибки.