Channels API Reference — Омниканальные коммуникации

Полная документация API каналов Trigly: настройка Email, SMS, Telegram, WhatsApp, Push. Аналитика, бюджеты, smart-select.

Обзор модуля Channels

Модуль Channels обеспечивает омниканальную доставку сообщений через 6 адаптеров: Email (SMTP/Unisender), SMS (SMS.ru), Telegram (Bot API), WhatsApp (Cloud API), Web Push (VAPID). API предоставляет 38 эндпоинтов для настройки каналов, аналитики, бюджетов и умного выбора каналов.

Базовые URL:

  • Конфигурация и аналитика: /api/v1/channels
  • Провайдерские вебхуки: /hooks/
  • SDK: /api/v1/sdk/

Конфигурация каналов

Модель ChannelConfig

Поле Тип Описание
id UUID Уникальный идентификатор
channel_type ChannelType email, sms, telegram, whatsapp, push
provider string smtp, unisender, sms_ru, telegram_bot, whatsapp_cloud, webpush
credentials JSONB Креденшлы провайдера (api_key, bot_token и т.д.)
is_active bool Канал активен
is_verified bool Канал проверен и работоспособен
sender_name string Имя отправителя
sender_address string Адрес отправителя (email, номер телефона)
daily_limit int Дневной лимит сообщений
monthly_limit int Месячный лимит
monthly_budget float Месячный бюджет (в рублях)
monthly_spent float Потрачено в текущем месяце
total_sent int Всего отправлено
settings JSONB Дополнительные настройки
last_error string Последняя ошибка
last_used_at datetime Время последнего использования

Уникальное ограничение: одна конфигурация на (organization_id, channel_type).

Подключение канала

POST /api/v1/channels/connect
Authorization: Bearer {token}
Content-Type: application/json

Email (SMTP)

{
  "channel_type": "email",
  "provider": "smtp",
  "credentials": {
    "host": "smtp.yandex.ru",
    "port": 465,
    "username": "noreply@company.ru",
    "password": "app-password",
    "use_tls": true
  },
  "sender_name": "Компания",
  "sender_address": "noreply@company.ru"
}

Email (Unisender)

{
  "channel_type": "email",
  "provider": "unisender",
  "credentials": {
    "api_key": "your-unisender-api-key"
  },
  "sender_name": "Компания",
  "sender_address": "noreply@company.ru"
}

SMS (SMS.ru)

{
  "channel_type": "sms",
  "provider": "sms_ru",
  "credentials": {
    "api_id": "your-sms-ru-api-id"
  },
  "sender_name": "COMPANY"
}

Telegram (Bot API)

{
  "channel_type": "telegram",
  "provider": "telegram_bot",
  "credentials": {
    "bot_token": "123456:ABC-DEF..."
  }
}

При подключении Telegram Trigly автоматически:

  1. Вызывает getMe для проверки токена и получения имени бота
  2. Устанавливает вебхук через setWebhook на /hooks/telegram/{org_id}
  3. Помечает канал как is_verified = true

WhatsApp (Cloud API)

{
  "channel_type": "whatsapp",
  "provider": "whatsapp_cloud",
  "credentials": {
    "access_token": "your-meta-access-token",
    "phone_number_id": "123456789",
    "business_account_id": "987654321"
  }
}

Web Push (VAPID)

{
  "channel_type": "push",
  "provider": "webpush"
}

VAPID-ключи генерируются автоматически при подключении push-канала и сохраняются в credentials.

Тестирование соединения

POST /api/v1/channels/{channel_id}/test
Authorization: Bearer {token}

Выполняет health check адаптера: проверяет подключение, валидность креденшлов, доступность API провайдера. Возвращает:

{
  "healthy": true,
  "provider": "telegram_bot",
  "latency_ms": 145,
  "details": {
    "bot_name": "MyCompanyBot",
    "bot_username": "my_company_bot"
  }
}

CRUD-операции

GET    /api/v1/channels                          — Список каналов организации
GET    /api/v1/channels/{id}                      — Получить конфигурацию канала
PATCH  /api/v1/channels/{id}                      — Обновить настройки
DELETE /api/v1/channels/{id}                      — Удалить канал
POST   /api/v1/channels/{id}/health               — Health check
GET    /api/v1/channels/available                  — Доступные каналы для подключения

Умный выбор канала (Smart Select)

Trigly анализирует данные ClickHouse за последние 90 дней для каждого контакта и рекомендует оптимальный канал на основе engagement-скоринга.

Формула скоринга

score = (opens / delivered) × 0.4 + (clicks / delivered) × 0.6

Эндпоинты

GET /api/v1/channels/smart-select/{customer_id}

Ответ:

{
  "customer_id": "uuid",
  "recommended_channel": "telegram",
  "scores": {
    "email": 0.35,
    "telegram": 0.82,
    "sms": 0.15,
    "push": 0.45
  },
  "reason": "Наивысший engagement в Telegram (82% взаимодействий)"
}

POST /api/v1/channels/smart-select/bulk

{
  "segment_id": "uuid-сегмента"
}

Массовый выбор канала для всех контактов сегмента.

Бюджет и стоимость

Стоимость по каналам

Канал Провайдер Стоимость
Email SMTP Бесплатно
Email Unisender 0.1-0.5 руб./письмо
SMS SMS.ru 2.5 руб./сегмент
Telegram Bot API Бесплатно
WhatsApp Cloud API 5-8 руб./шаблонное сообщение
Push VAPID Бесплатно

Управление бюджетом

GET /api/v1/channels/{id}/budget

Ответ:

{
  "channel_type": "sms",
  "monthly_budget": 50000,
  "monthly_spent": 32500,
  "remaining": 17500,
  "usage_percent": 65.0,
  "forecast_monthly": 48750,
  "will_exceed": false,
  "daily_average": 1083.33
}

При достижении 80% бюджета генерируется предупреждение. При 100% канал автоматически переключается на бесплатную альтернативу (если настроена fallback-цепочка).

Оценка стоимости кампании

POST /api/v1/channels/cost/estimate

{
  "channel": "sms",
  "segment_id": "uuid-сегмента",
  "message_text": "Текст SMS-сообщения для оценки количества сегментов"
}

Ответ:

{
  "channel": "sms",
  "recipients": 5000,
  "segments_per_message": 2,
  "cost_per_message": 5.0,
  "total_cost": 25000.0,
  "within_budget": true
}

Адаптация контента

ContentAdapterService автоматически адаптирует один HTML-шаблон для каждого канала:

POST /api/v1/channels/preview/omni

{
  "template_id": "uuid-шаблона",
  "customer_id": "uuid-контакта"
}

Ответ:

{
  "email": {
    "subject": "Скидки для Ивана!",
    "body_html": "<h1>Привет, Иван!</h1>...",
    "tracking_pixel": true,
    "links_rewritten": true
  },
  "telegram": {
    "text": "**Привет, Иван!**\n\nСкидки до 50%...",
    "parse_mode": "Markdown",
    "photo_url": "https://example.com/banner.jpg",
    "inline_keyboard": [
      [{"text": "Перейти в магазин", "url": "https://shop.example.com"}]
    ]
  },
  "sms": {
    "text": "Privet, Ivan! Skidki do 50%. shop.example.com STOP",
    "segments": 2,
    "transliterated": true
  },
  "whatsapp": {
    "template_name": "promo_discount",
    "variables": ["Иван", "50%"]
  },
  "push": {
    "title": "Скидки для Ивана!",
    "body": "Скидки до 50% на весеннюю коллекцию",
    "icon": "https://example.com/icon.png",
    "url": "https://shop.example.com"
  }
}

Правила адаптации:

  • Email: HTML as-is + трекинг-пиксель + перезапись ссылок
  • Telegram: HTML → Markdown, извлечение фото, inline-кнопки, макс. 4096 символов
  • SMS: HTML → plain text, транслитерация, суффикс «СТОП», макс. 320 символов
  • WhatsApp: маппинг переменных в HSM-шаблон
  • Push: заголовок 50 символов, тело 100 символов, иконка, URL действия

Fallback-цепочки

Если основной канал недоступен (ошибка отправки, бюджет исчерпан, контакт отписан), Trigly автоматически пробует следующий канал из цепочки.

Настройка при создании кампании:

{
  "channel": "email",
  "fallback_channels": ["telegram", "sms"]
}

Логика:

  1. Попытка отправки через email
  2. При неудаче — отправка через Telegram
  3. При неудаче — отправка через SMS
  4. Все попытки логируются в ClickHouse delivery_events

Аналитика каналов

7 аналитических эндпоинтов на основе ClickHouse:

GET /api/v1/channels/analytics/dashboard         — Общая сводка по каналам
GET /api/v1/channels/analytics/compare            — Сравнение каналов
GET /api/v1/channels/analytics/timeline           — Временная шкала доставки
GET /api/v1/channels/analytics/funnel             — Воронка доставки
GET /api/v1/channels/analytics/costs              — Отчёт по затратам
GET /api/v1/channels/analytics/errors             — Анализ ошибок
GET /api/v1/channels/analytics/health-timeline    — Здоровье каналов во времени

Dashboard

GET /api/v1/channels/analytics/dashboard?period=30d

Ответ:

{
  "channels": [
    {
      "channel": "email",
      "total_sent": 125000,
      "delivered": 122000,
      "opened": 36600,
      "clicked": 7320,
      "delivery_rate": 97.6,
      "open_rate": 30.0,
      "click_rate": 6.0,
      "total_cost": 12500.0
    }
  ],
  "period": "30d"
}

Воронка доставки

GET /api/v1/channels/analytics/funnel?channel=email&period=30d

{
  "channel": "email",
  "funnel": [
    {"stage": "sent", "count": 125000, "rate": 100},
    {"stage": "delivered", "count": 122000, "rate": 97.6},
    {"stage": "opened", "count": 36600, "rate": 30.0},
    {"stage": "clicked", "count": 7320, "rate": 6.0},
    {"stage": "converted", "count": 1830, "rate": 1.5}
  ]
}

Виджеты подписки

Модель SubscriptionWidget

Поле Тип Описание
name string Название виджета
widget_type enum popup, inline, floating
channels JSONB Каналы для подписки
design JSONB Дизайн (title, colors, position)
targeting_rules JSONB Правила показа (pages, delay, scroll)
is_active bool Активен
total_views int Всего показов
total_subscriptions int Всего подписок

CRUD виджетов

POST   /api/v1/channels/widgets                   — Создать виджет
GET    /api/v1/channels/widgets                    — Список виджетов
GET    /api/v1/channels/widgets/{id}               — Получить виджет
PATCH  /api/v1/channels/widgets/{id}               — Обновить
DELETE /api/v1/channels/widgets/{id}               — Удалить

Для привязки Telegram-аккаунта к контакту CDP используются deep links с HMAC-подписью:

POST /api/v1/channels/telegram-link/{customer_id}
Authorization: Bearer {token}

Ответ:

{
  "link": "https://t.me/your_bot?start=base64_hmac_token",
  "expires_at": "2026-03-21T12:00:00Z"
}

Токен содержит org_id:customer_id:timestamp, подписан HMAC-SHA256. Срок действия — 24 часа. При переходе по ссылке пользователь открывает бота, отправляет /start, и Trigly автоматически привязывает telegram_chat_id к контакту.

Celery-задачи каналов

Задача Расписание Описание
update_preferred_channels Ежедневно 4:00 ClickHouse 90-day engagement → Customer.preferred_channel
reset_monthly_budgets 1-е число месяца Сброс monthly_spent = 0 для всех конфигураций

Коды ошибок

HTTP-код Описание
400 Некорректные параметры (невалидный провайдер, неверные креденшлы)
404 Канал не найден
409 Канал уже подключён (уникальное ограничение org_id + channel_type)
429 Превышен rate limit (500/мин)
503 Провайдер недоступен (health check failed)
Назад
Analytics API
Далее
Flow Builder

Не нашли ответ?

Swagger UI с интерактивной документацией и поддержка в Telegram.

Swagger UIНаписать в поддержку