Сообщения и SMS

Как биллинг пишет клиентам: каналы и шаблоны, тихий час и стоп-лист, почта организаций, SMS-шлюз «Телефоны СмИТ» и SMS-провайдеры.

Сообщения

Каналы, по которым биллинг пишет клиентам, и тексты этих сообщений. Вкладки: Email, SMS, Telegram, ВКонтакте, Push и «Шаблоны». У каждой свой адрес — /admin/settings/messaging/<вкладка>/, например /admin/settings/messaging/templates/.

Когда уходят сообщения

Над вкладками — сводка правил отправки: задан ли тихий час и идёт ли он сейчас, какие каналы выключены, в какие часы звонит робот (с модулем автообзвона). Кнопка «Изменить» ведёт в Настройки → Система → Сообщения (/admin/settings/system/messages/) — правила задаются там.

• Тихий час — SMS и push в это время не отправляются: сообщение получает статус «пропущено» и позже само не уйдёт. Письма, Telegram и ВКонтакте уходят сразу. Запланированные рассылки ждут конца тихого часа.
• Отправка выключена целиком (аварийная кнопка) — сообщения клиентам пропускаются по всем каналам и после включения не досылаются. Блок становится красным.
• Канал выключен — его название красным в конце строки; по нему ничего не уходит.

Сообщения и организации

С модулем «Мультиорганизация» каждый канал работает с организациями по-своему:

Как биллинг выбирает текст и канал, когда случилось событие (платёж, блокировка, порог баланса):

flowchart TD
    E["Событие у клиента:
платёж, блокировка, порог баланса"] --> N["Шаблон по названию"]
    N --> O{"У организации клиента
есть свой шаблон?"}
    O -- "да" --> OW["Свой шаблон организации"]
    O -- "нет" --> SH["Общий шаблон"]
    OW --> ON{"Шаблон включён?"}
    SH --> ON
    ON -- "нет" --> STOP["Не отправлять"]
    ON -- "да" --> Q["Очередь сообщений:
каналы, отмеченные в шаблоне"]
    Q --> P{"Канал включён?
Тихий час для SMS и push?"}
    P -- "нельзя" --> SK["Пропущено"]
    P -- "можно" --> M["Email — SMTP организации
или общий"]
    P -- "можно" --> S["SMS — способ и SIM
организации"]
    P -- "можно" --> V["ВКонтакте — сообщество
организации или общее"]
    P -- "можно" --> T["Telegram · Push · ЛК —
общие на все организации"]

Вкладка «Email (SMTP)»

Общий SMTP — через него уходят письма клиентам, если у их организации нет своего: «От кого», сервер, порт, логин, пароль, режим шифрования и проверка сертификата. В полосе сверху — сколько писем отправлено и ждёт в очереди; «i» ведёт сюда.

Тестовая отправка — вверху правой колонки. В поле уже подставлен email из вашего профиля, его можно заменить. Письмо уходит с текущими значениями формы, даже несохранёнными, поэтому настройки можно проверить до сохранения. Можно выбрать оформление: обычный текст или один из фирменных макетов.

Автонастройка своим почтовым сервером

С модулем «Почтовый сервер» общий SMTP настраивается одной кнопкой — «Автонастройка» в заголовке «Email (SMTP)» или «Настроить общий SMTP» в блоке справа. Выберите домен: на почтовом сервере появится ящик noreply@домен (если он уже есть и его пароль известен — берётся готовый), а сервер mail.домен, порт 587 со STARTTLS, логин и пароль впишутся в общий SMTP. Если у домена подключён Cloudflare, сразу пропишутся записи MX, SPF, DKIM и DMARC — без них письма попадают в спам. Настраивать может администратор (root); без модуля кнопка неактивна, в подсказке написано почему. Действие пишется в журнал.

flowchart LR
    B["«Автонастройка»
домен noreply@…"] --> D["Домен на почтовом сервере"]
    D --> MB{"Ящик noreply@
уже есть?"}
    MB -- "нет" --> NEW["Создать ящик,
пароль — случайный"]
    MB -- "да, пароль известен" --> OLD["Взять готовый"]
    NEW --> DNS{"Cloudflare
у домена?"}
    OLD --> DNS
    DNS -- "да" --> REC["MX · SPF · DKIM · DMARC"]
    DNS -- "нет" --> S
    REC --> S["Общий SMTP:
mail.домен:587, STARTTLS"]

Шифрование SMTP — radio-группа

Тип шифрования задаётся одной radio-группой из трёх взаимоисключающих кнопок — включить два режима сразу нельзя:

• STARTTLS (587) — наиболее распространённый вариант, default. Подключение в plain-text с upgrade до TLS через команду STARTTLS.
• SSL (SMTPS) (465) — TLS с первого байта (implicit TLS).
• Без шифрования — порт 25, plain SMTP. Только для внутренних SMTP-relays/локальной тестовой инфраструктуры.

Авто-подстановка порта. При смене radio JS подставляет порт (587/465/25), если в поле сейчас стоит один из «дефолтных» портов. Если оператор задал кастомный порт (например, 2525) — он сохраняется.

Защита на back-end. Если из формы каким-то образом пришли email_use_tls=True и email_use_ssl=True одновременно (старый кэш браузера, legacy POST), email_test_send и email_settings_save применяют XOR-нормализацию: оставляют тот режим, который соответствует порту (465 → SSL, иначе STARTTLS), второй гасят. В SystemSettings теперь никогда не лежат оба True.

Поле «От кого» и политика отправителя

Большинство SMTP-серверов (включая SmitMailServ) применяют политику «отправитель должен совпадать с авторизованным пользователем». Если у вас логин noreply@вашдомен.ru, но в поле «От кого» вы указали billing@вашдомен.ru — сервер вернёт ошибку:

SMTPRecipientsRefused: 553 5.7.1 <billing@вашдомен.ru>:
Sender address rejected: not owned by user noreply@вашдомен.ru

Решения:

• Простое — в поле «От кого» укажите тот же адрес, что и в «Логин».
• Гибкое — создайте alias на mail-сервере, чтобы noreply@вашдомен.ru имел право отправлять от имени нужного адреса. Для SmitMailServ это делается через раздел «Почтовый сервер» → вкладка «Ящики» → редактирование ящика → поле sender_acl (или API edit_mailbox).

Отправитель писем по организациям

С модулем «Мультиорганизация» под настройками SMTP есть таблица организаций: от кого уходят письма, через какой сервер и чей SMTP — «свой», «не дозаполнен» (сервер указан, но нет логина или пароля) или «общий».

• «Проверить» — подключиться к SMTP организации и войти, письмо не отправляется. Ответ появится под бейджем: «подключение и авторизация успешны» или причина — неверный пароль, истёкший сертификат сервера.
• «Настроить» — автонастройка, как в карточке организации: ящик noreply@ на домене организации, DNS почты и SMTP организации. Кнопка есть, когда включён «Почтовый сервер», у организации указан домен и подключён Cloudflare; иначе — «Автонастройка недоступна» с причиной в подсказке.
• «Изменить» — карточка организации сразу на вкладке SMTP (Настройки → Организации).

Письмо клиенту организации уходит с её адреса, в теме — её название. Если свой SMTP не ответил (неверный пароль, истёк сертификат почтового сервера), письмо уходит через общий SMTP с этой вкладки — клиент его всё равно получит, а причина пишется в лог сервера. Поэтому общий SMTP стоит держать настроенным и при своих SMTP у всех организаций.

Свой SMTP организации включается, только когда заполнены сервер, логин и пароль. Если указан один сервер — письма идут через общий SMTP, а в таблице стоит «не дозаполнен». Такую строку лучше очистить в карточке организации или дозаполнить: поле «От кого» организации при этом сохраняется и используется для писем с договором и обмена с 1С.

Письмо ушло, но не дошло

«Отправлено» в истории сообщений значит, что письмо принял ваш почтовый сервер. Дальше его проверяет сервер получателя (Mail.ru, Яндекс, Gmail, iCloud) и может вернуть отказ — он приходит письмом в ящик отправителя (noreply@), в биллинге его не видно.

flowchart LR
    B["Биллинг"] --> S["Ваш почтовый сервер
письмо отправлено"]
    S --> R{"Сервер получателя
проверяет"}
    R -- "домен адреса есть
и принимает почту" --> C1{"Обратная запись IP
(PTR) есть?"}
    R -- "домена нет:
gmail.ru, gmal.com" --> X1["Отказ: адрес не существует"]
    C1 -- "нет" --> X2["Отказ или спам:
iCloud 550 5.7.1, «IP name lookup failed»"]
    C1 -- "да" --> C2{"SPF, DKIM, DMARC
совпадают?"}
    C2 -- "нет" --> X3["Папка «Спам»"]
    C2 -- "да" --> OK["Входящие"]

Опечатки в адресах. С версии 3415 сводка карточки клиента проверяет домен при сохранении почты (подробнее). Адреса, записанные раньше, можно найти по всей базе командой — она ничего не меняет, только показывает и сохраняет список:

python manage.py clean_bad_emails --domains --csv /tmp/bad_emails.csv

В списке — договор, клиент, адрес, что не так и вероятный правильный адрес. Исправлять лучше после звонка клиенту: amail.com мог быть и настоящим. Часть доменов-опечаток (iclaud.com, amail.com) скуплена посторонними и письма принимает — такое письмо со счётом уйдёт чужому человеку, поэтому их стоит исправить в первую очередь.

Вкладка «SMS»

Чем отправлять SMS клиентам, выбирается в поле «Чем отправлять»:

• Телефоны СмИТ — свои SIM-карты (рекомендуется, модуль «SMS-шлюз») — SMS уходят с SIM-карт ваших Android-телефонов с приложением «СмИТ SMS Gateway»;
• SMSAero, SMSC.ru, SMS.ru — платные SMS-агрегаторы, логин и пароль от их кабинета.

Прежняя схема «Android-телефон через sms-gate.app» в списке видна только там, где она уже выбрана; новые подключения — через «Телефоны СмИТ».

Свой способ у организации

С модулем «Мультиорганизация» под «Чем отправлять» есть таблица «Для организаций»: у каждой компании можно выбрать свой способ — например, своим SIM-картам одну организацию, а SMSAero другую. «Как выбрано выше» — организация отправляет способом по умолчанию. Логин и пароль SMSAero, SMSC.ru и SMS.ru общие для всех организаций. Таблица показывается, когда в навбаре выбрано «Все»; с выбранной организацией её нет, а настройки организаций не меняются.

Способ выбирается по организации клиента одинаково везде, где биллинг шлёт SMS: очередь уведомлений, CRM-автоматизация, ответы поддержки, голосовая почта, гостевой портал (код — billing/services/sms_router.py).

Телефоны СмИТ — свои SIM-карты

Android-телефон с одной или двумя SIM-картами становится SMS-шлюзом биллинга. Платите только за тариф SIM-карты — договор с агрегатором и плата за каждое сообщение не нужны. Телефонов может быть несколько; каждую SIM можно закрепить за организацией. Телефон подключается к биллингу по логину и паролю администратора — адреса серверов, ключи и вебхуки вводить не нужно.

flowchart TD
    B["Биллинг
(очередь SMS, CRM, поддержка)"] -- "SMS: номер, текст, организация" --> L["Сервер лицензий СмИТ
SMS-сервер"]
    L -- "задание: с какой SIM" --> P1["Телефон 1
SIM 1 · SIM 2"]
    L -- "задание" --> P2["Телефон 2
SIM 1"]
    P1 -- "SMS" --> OP["Оператор связи"] --> C["Клиент"]
    P1 -. "отправлено / доставлено,
входящие SMS, баланс SIM" .-> L
    L -. "события с подписью" .-> B

Как это устроено: биллинг отдаёт SMS серверу лицензий (модуль «SMS-шлюз» лицензии). Сервер выбирает SIM по организации клиента, основному номеру и лимитам и передаёт задание телефону. Телефон отправляет SMS, сообщает «отправлено» и «доставлено», пересылает входящие SMS и раз в минуту — своё состояние: заряд, сигнал, сеть, разрешения. Биллинг получает это событиями на тот же адрес /api/sms/webhook/sms-gate/, подпись — ключом лицензии.

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

1. Android-телефон 8.0 или новее с одной или двумя SIM — на зарядке и в сети.
2. Установите приложение «СмИТ SMS Gateway»: кнопки «Скачать в Google Play», «Скачать в RuStore» и «Скачать APK» на этой вкладке (приложение в RuStore, политика конфиденциальности) (постоянная ссылка на последнюю версию — sms.billing.smit34.ru/mobile/v1/app.apk).
3. В приложении нажмите «Подключить к биллингу», введите адрес своего биллинга, логин и пароль администратора или сотрудника с правом «Подключение телефонов-шлюзов SMS». Пароль на телефоне не сохраняется.
4. Выдайте разрешения: SMS, Телефон, Звонки (для баланса по USSD), уведомления; отключите экономию батареи. Приложение показывает, чего не хватает, — строки «Разрешить» и «Исправить» на главной.
5. Телефон появится в «Телефонах и номерах». Назначьте SIM-картам организации и лимиты.

Телефоны и номера

Уже 700 px (узкая колонка, телефон) каждая SIM показывается карточкой — без горизонтальной прокрутки.

С какой SIM уйдёт SMS

flowchart TD
    S["SMS клиенту организации N"] --> A{"У организации N есть SIM
на связи и с запасом по лимиту?"}
    A -- "да" --> P{"Есть основная?"}
    P -- "да, на связи" --> MAIN["Основная SIM организации"]
    P -- "нет" --> ANY["Любая SIM организации"]
    A -- "нет" --> F{"«Отправлять с общих номеров»
включено?"}
    F -- "да" --> SH["Общая SIM (без организации)"]
    F -- "нет" --> W["Ждёт в очереди до 24 ч"]
    MAIN -. "3 ошибки подряд" .-> NEXT["Другая SIM этой организации"]
    ANY -. "3 ошибки подряд" .-> NEXT

После трёх ошибок подряд SIM уступает очередь другой SIM той же организации — даже основная. Первая же удачная отправка возвращает её в строй. Чужой организации SMS не уйдёт никогда. Пауза между SMS (по умолчанию 3–6 секунд) и лимит в день защищают SIM от блокировки оператором за массовую рассылку. Без модуля «Мультиорганизация» все номера общие.

Баланс, остаток пакета и номер SIM

Телефон сам спрашивает у оператора USSD-запросом баланс и остаток пакета SMS — по расписанию (по умолчанию раз в 6 часов) и по кнопке «обновить» у SIM. Ответ оператора разбирает сервер: находит сумму и число SMS, полный текст виден в подсказке. Номер SIM приложение берёт из SIM-карты; если оператор его туда не прописал — запрашивает по USSD, а если и это не помогло — кнопкой «Узнать: SMS» телефон отправляет проверочную SMS с этой SIM на другую вашу SIM с известным номером (в журнал SMS она не попадает).

Рекламу, которую оператор дописывает к ответу («Новинки в книгах… Подкл. *440#»), сервер отрезает — в баланс попадает только «782.04 р.». SMS оператора о платеже, зачислении или списании («Платеж 200,00 руб. зачислен») балансом не считаются.

sequenceDiagram
    participant B as Биллинг
    participant S as SMS-сервер
    participant T as Телефон
    participant O as Оператор
    T->>S: ping (раз в минуту): SIM, сигнал, разрешения
    T->>S: какие USSD-запросы выполнить?
    S-->>T: SIM 1 — баланс *102#, пакет *107#
    T->>O: USSD *102#
    O-->>T: «Баланс 141,00 р.»
    T->>S: ответ оператора как есть
    S->>S: сумма 141,00 ₽, сравнение с порогом
    S-->>B: «мало денег» (если ниже порога, не чаще раза в сутки)
    B->>B: журнал + сообщение в Telegram

Это коды по умолчанию. Если у вашего тарифа другие — «коды» у SIM: пустое поле означает код оператора (он виден серым).

«Уведомлять в Telegram: мало денег на SIM, телефон пропал или вернулся» — три вида сообщений:

• мало денег — сумма на SIM или остаток пакета ниже порога (по умолчанию 100 ₽ и 50 SMS); по каждой SIM не чаще раза в сутки, после пополнения — снова при следующем снижении;
• телефон пропал — подключённый телефон молчит дольше, чем «Телефон пропал, мин» (по умолчанию 10 минут). Одно сообщение на каждый перерыв связи: имя телефона, сколько минут он молчит, его SIM-карты и что проверить;
• телефон вернулся — он снова на связи.

«Телефон пропал, мин» = 0 — о пропаже не сообщать. Телефоны, которые молчат больше суток, в проверку не попадают: о давно выключенном телефоне сообщений не будет. Чат выбирается из списка групп бота; не выбран — уходит в чат тревог (Настройки → Интеграции → Telegram). Все события пишутся и в журнал действий.

SMS на главной

Когда SMS настроены, на главной (/admin/welcome/) есть блок «SMS»: сколько отправлено, доставлено, с ошибкой и в очереди за 30 дней, сколько ушло сегодня и сколько ждут у телефонов. Справа — SIM-карты: номер, организация, оператор и телефон, баланс и «сегодня N из лимита». Точка слева — состояние SIM. Стрелка открывает вкладку SMS. Блок видят сотрудники с доступом к настройкам сообщений; его можно скрыть или переставить, как другие блоки главной.

Статусы доставки

sequenceDiagram
    participant B as Биллинг
    participant S as SMS-сервер
    participant T as Телефон
    B->>S: SMS (msg:id)
    Note over B: в очереди
    S->>T: задание
    T->>S: Sent
    S-->>B: sms:sent
    Note over B: отправлено
    T->>S: Delivered (отчёт оператора)
    S-->>B: sms:delivered
    Note over B: доставлено

Телефон просит у оператора отчёт о доставке. «Доставлено» появляется, когда оператор его прислал; ошибка — с текстом причины. Статус не откатывается назад. Событие, которое биллинг не принял, сервер повторяет: через 1, 5, 15, 60, 180, 720 минут.

Повтор при временной ошибке телефона. Если телефон не смог отправить SMS из-за того, что пропала сеть, был сбой радиомодуля или включён режим полёта, сервер сам повторит отправку через 30 секунд, 2 и 10 минут. Биллинг в это время видит «в очереди». Каждая неудача засчитывается SIM-карте: после трёх подряд повтор уйдёт с другой SIM той же организации. Не вышло за три повтора — статус «ошибка» с причиной словами: «на SIM нет сети», «сбой радиомодуля или SIM» и т. п. Постоянные ошибки (номер запрещён настройками SIM, короткий номер) не повторяются.

flowchart TD
    T["Телефон: не отправилось"] --> Q{"Ошибка временная?
нет сети, сбой радиомодуля"}
    Q -- "нет" --> F["Ошибка — причина словами"]
    Q -- "да" --> R{"Повторов уже три?"}
    R -- "нет" --> W["Повтор через 30 с, 2 или 10 мин
SIM выбирается заново"]
    W --> T2["Телефон отправляет снова"]
    R -- "да" --> F2["Ошибка: «после 3 повторов: …»"]

    style F fill:#7f1d1d,stroke:#dc2626,color:#fff
    style F2 fill:#7f1d1d,stroke:#dc2626,color:#fff

В «Последних SMS» номер получателя показывается в одном виде (+7 905 123-45-67); подсказка у номера — организация, чем отправлено и с какого номера SIM, у текста — полный текст сообщения.

Входящие SMS от клиентов

Блок есть только у «Телефонов СмИТ». Биллинг читает SMS, пришедшие на ваши SIM, выполняет команды клиентов и отвечает с того же номера: Баланс — баланс и тариф, Оп — обещанный платёж, Да — согласие с его условиями, Блок / Вкл — добровольная блокировка. Остальные SMS становятся обращениями в Поддержке — в ящике организации номера. SMS с буквенных имён и коротких номеров — оповещения МЧС, сообщения оператора, рассылки — в журнал как SMS клиента не попадают (баланс SIM от оператора по-прежнему разбирается). В таблице «По номерам» у каждой SIM свой переключатель «Принимать» и свой набор команд; номер без своих настроек выполняет команды, отмеченные выше. Выключенный номер не принимает SMS клиентов, а сообщения оператора о балансе SIM разбираются всё равно.

Приложение «СмИТ SMS Gateway»

• Главная — одна карточка состояния с кнопкой «Подключить к биллингу» / «Запустить» / «Остановить», SIM-карты с оператором и номером, «Готовность»: разрешения, работа в фоне, автозапуск.
• Сообщения — исходящие и входящие на этом телефоне.
• Настройки — биллинг, «Настройки SMS в биллинге» (открывает в браузере вкладку SMS этого биллинга, с версии 2.5.3) и «Выйти из аккаунта» (телефон отвязывается и пропадает из списка в биллинге), «Компания» — организация, ИНН/КПП, адрес и лицензия с сервера лицензий, «Оформление» — тема как в системе, светлая или тёмная, «Для специалиста» — сервер шлюза и журнал, «Как это работает» — повторный онбординг.
• Раз в минуту телефон передаёт в биллинг заряд, сигнал, тип сети, роуминг, состояние SIM, разрешения и версию приложения.
• После перезагрузки телефона и (с версии 2.5.5) после обновления приложения служба запускается сама — открывать приложение не нужно.
• Новая версия всегда по одной ссылке: sms.billing.smit34.ru/mobile/v1/app.apk; ставится поверх прежней, подключение сохраняется.

Решение проблем

Телефон «нет связи»

Нет интернета, приложение остановлено или Android «усыпил» его в фоне. Откройте приложение: на главной — «Запустить» и «Работа в фоне → Исправить».

Жёлтая плашка «нет разрешения отправлять SMS»

Разрешения не выданы — см. блок про ограниченные настройки Android 13 выше. SMS при этом стоят в очереди и уйдут после исправления.

Баланс не обновляется, у SIM ошибка USSD

Нет разрешения «Звонки», USSD недоступен на SIM или код не подходит к тарифу — задайте свои коды в «коды».

SMS организации стоят в очереди

У организации нет SIM на связи или исчерпан лимит в день, а «отправлять с общих номеров» выключено. Через 24 часа такие SMS получают статус «ошибка».

Ошибка «на SIM нет сети» или «сбой радиомодуля или SIM»

Телефон три раза пробовал отправить и не смог. Проверьте сигнал и SIM (не заблокирована ли, есть ли деньги), режим полёта. Если у организации есть вторая SIM, повторы уже шли с неё.

Номер «не определён»

Оператор не прописал номер в SIM: «Узнать: по USSD» или «SMS» (нужна вторая SIM с известным номером).

Баланс

Справа на вкладке SMS — карточка «Баланс». Что в ней, зависит от выбранного способа отправки:

• Телефоны СмИТ — баланс и остаток пакета каждой SIM, дата ответа оператора. Меньше порога (настройка в блоке «Телефоны») — красным. «Запросить баланс» отправляет USSD-запрос на все SIM: телефон спросит оператора при ближайшей связи, обычно за минуту, карточка обновится сама. Кнопка доступна сотруднику с правом управлять телефонами.
• SMSAero, SMSC.ru, SMS.ru — баланс аккаунта у провайдера, по логину и ключу из настроек.
• Прежняя схема (sms-gate.app) — баланс из ответного SMS оператора, как раньше.

flowchart LR
    G{"Способ отправки"} -- "Телефоны СмИТ" --> U["USSD с каждой SIM
→ баланс и пакет"]
    G -- "SMSAero / SMSC / SMS.ru" --> API["Запрос баланса
аккаунта у провайдера"]
    G -- "sms-gate.app" --> IN["Ответное SMS оператора
(нужен приём входящих)"]
    U --> C["Карточка «Баланс»"]
    API --> C
    IN --> C

SMSAero, SMSC.ru, SMS.ru

Подпись отправителя регистрируется в кабинете сервиса. «Как подключить» на вкладке показывает инструкцию только для выбранных способов.

Прежняя схема: телефон через sms-gate.app

До модуля «SMS-шлюз» телефон подключался к облаку sms-gate.app, а в биллинге вводились логин, пароль и адрес облака; статусы доставки приходили на /api/sms/webhook/sms-gate/ с подписью SMS_GATE_WEBHOOK_SECRET. Схема работает у тех, у кого она уже выбрана, но не развивается: для перехода установите «СмИТ SMS Gateway» 2.x, подключите телефон по логину и паролю биллинга и выберите «Телефоны СмИТ». Старое приложение подписано другим ключом — его нужно удалить перед установкой нового.

Вкладка «Telegram»

Биллинг пишет клиенту в Telegram, когда в шаблоне сообщения включён этот канал: платёж, низкий баланс, блокировка, обещанный платёж, рассылки. Писать человеку первым бот не может, поэтому сообщения получают только клиенты, которые привязали Telegram в личном кабинете: «Профиль» → «Привязать Telegram» → «Старт» в чате с ботом. В полосе сверху — сколько отправлено и ждёт в очереди за 30 дней и сколько клиентов привязали Telegram.

Вкладки Telegram, MAX и ВКонтакте устроены одинаково, в две колонки. Слева — то, что настраивают: бот или сообщество, аккаунт агента с бейджем его организации, проверка клиентов и таблица по организациям. Справа — то, что смотрят каждый день: «Проверка связи» (переключатель «Аккаунт агента / Бот»), «Последние сообщения» (агента и бота отдельно), справка «Как это устроено» и «Журнал» — подключения и падения сессии аккаунта, ошибки доставки.

• По организациям (модуль «Мультиорганизация») — сколько клиентов каждой организации привязали Telegram и из скольких, сколько сообщений ушло за 30 дней и есть ли у организации свой бот для сотрудников.
• Бот клиентов один — служебный бот личного кабинета, для клиентов всех организаций. Боты организаций (Настройки → Организации → Telegram) пишут сотрудникам: заявки, тревоги, отчёты.
• Тестовое сообщение — вверху правой колонки: от бота ЛК в админ-чат из Интеграции → Telegram или в указанный чат. Тревоги о NAS, IP-пулах и RADIUS — тоже в админ-чат.
• Последние в Telegram — пять последних сообщений: дата, договор со ссылкой на карточку и организация.

flowchart LR
    C["Клиент: ЛК → «Привязать
Telegram» → «Старт»"] --> ID["Чат запомнен
в карточке клиента"]
    E["Событие + шаблон
с каналом Telegram"] --> Q["Очередь сообщений"]
    Q --> W{"Чат привязан?
Ключ бота задан?"}
    ID -.-> W
    W -- "да" --> BOT["Бот ЛК → чат клиента"]
    W -- "нет" --> SK["Пропущено,
причина в журнале"]

Вкладка «ВКонтакте»

Биллинг пишет клиенту от сообщества ВКонтакте, когда в шаблоне сообщения включён этот канал. Сообщения получают клиенты, которые вошли в личный кабинет через VK или написали сообществу в Поддержку. Нужны App ID и Secret Key приложения (для входа в ЛК) и ключ сообщества с правом «Сообщения сообщества» (для отправки).

• От какого сообщества. Сообщение клиенту уходит от сообщества его организации — VK-канала её ящика в Поддержке (Поддержка → Ящики → Каналы). Своего канала нет — от общего сообщества, ключ которого задан в Интеграции → VK. В таблице «По организациям»: «своё» с названием ящика, «общее» или «нет» — ни своего канала, ни общего ключа, сообщения этой организации не уйдут.
• Привязали VK — клиенты, у которых есть привязка VK (вход в ЛК или переписка с сообществом), по организации из шапки. До сборки 3394 счётчик всегда показывал 0.
• Проверка доставки — админ-чата у ВКонтакте нет: сообщество пишет только конкретному человеку. Проверяйте на своём тестовом клиенте, вошедшем в ЛК через VK.

flowchart LR
    M["Сообщение клиенту
организации N"] --> L{"Клиент привязал VK?"}
    L -- "нет" --> SK["Пропущено:
VK не привязан"]
    L -- "да" --> CH{"У ящика Поддержки
организации N есть
VK-канал с ключом?"}
    CH -- "да" --> OWN["Сообщество
организации N"]
    CH -- "нет" --> G{"Общий ключ
сообщества задан?"}
    G -- "да" --> SH["Общее сообщество"]
    G -- "нет" --> SK2["Пропущено:
не задан ключ"]

Вкладка «Push»

Push-уведомления в мобильном приложении клиента через Firebase Cloud Messaging. Приложение одно на все организации.

• Файл ключа сервисного аккаунта. На сервере нужен JSON-ключ Firebase того проекта, что и мобильное приложение. Кладётся в /opt/smit-billing/secrets/firebase-key.json (права только у root) — в контейнерах биллинга он виден как /app/secrets/firebase-key.json, этот путь и вписывается в поле. Найден — под полем проект и сервисный аккаунт; нет — «Файл не найден», статус «Не настроено» и push не уходят.
• С приложением — клиенты, у которых приложение хотя бы раз запускалось и прислало токен; в таблице «По организациям» — по каждой организации, из скольких клиентов.
• Тестовый push — по ID клиента, придёт на его телефон: проверяйте на своём тестовом клиенте.
• Тихий час действует на push так же, как на SMS: в это время push по событиям получают статус «пропущено».

flowchart LR
    APP["Приложение клиента
первый запуск"] --> TOK["Токен push
в карточке клиента"]
    E["Событие + шаблон
с каналом Push"] --> Q["Очередь сообщений"]
    Q --> W{"Токен есть?
Файл ключа найден?
Не тихий час?"}
    TOK -.-> W
    W -- "да" --> FCM["Firebase Cloud Messaging"] --> PH["Телефон клиента"]
    W -- "нет" --> SK["Пропущено,
причина в журнале"]

Важно (сборка 3393). До неё служба отправки брала ключ бота Telegram и путь к ключу Firebase не из настроек биллинга, а из файла окружения сервера, где их не было: сообщения Telegram и push из очереди молча считались отправленными, хотя не уходили. Теперь ключи берутся из настроек, а причина пропуска пишется в журнал.

Подключение аккаунтов Telegram и MAX (агент, который пишет первым)

Бот не может написать человеку первым, пока тот сам не нажал «Старт». Поэтому агент пишет клиенту от аккаунта компании — по номеру из карточки клиента или заявки CRM. Чтобы агент вошёл в этот аккаунт без ввода кода при каждом запуске, используется браузерное расширение «СмИТ — ключ сессии MAX / Telegram»: оно берёт ключ уже открытой в браузере сессии и показывает его для вставки в биллинг.

Расширение работает только на web.telegram.org и web.max.ru, только по клику на иконку и ничего не отправляет во внешнюю сеть — значения видны только в его окне.

Установка из Chrome Web Store: расширение «Ключ сессии СмИТ» (по прямой ссылке; в поиске магазина не публикуется). Ставится в Chrome одной кнопкой «Установить».

Установка без Chrome Web Store (по прямой ссылке — для закрытого контура или пока расширение на проверке):

1. Скачайте архив: smit-session-key.zip и распакуйте его в постоянную папку (Chrome читает расширение прямо из неё — не удаляйте и не переносите папку после установки).
2. Откройте chrome://extensions, включите справа вверху «Режим разработчика».
3. Нажмите «Загрузить распакованное расширение» и выберите распакованную папку.
4. Значок «Ключ сессии СмИТ» появится на панели Chrome — дальше всё как описано ниже.

Обновление: скачайте новую версию, распакуйте поверх той же папки и нажмите «Обновить» на chrome://extensions. Разрешения те же — Chrome не будет переспрашивать.

Как подключить:

1. Войдите служебным аккаунтом: для Telegram откройте web.telegram.org, для MAX — web.max.ru (это отдельный аккаунт, не аккаунт Поддержки).
2. Нажмите иконку расширения «Ключ сессии СмИТ» на этой вкладке. Оно само определит мессенджер и покажет значения:
   • Telegram — «Строку сессии (Telethon)», кнопка «Копировать».
   • MAX — «Токен MAX (__oneme_auth)» и «Device ID».
3. В биллинге: Настройки → Сообщения → вкладка «Telegram» или «MAX», карточка «Аккаунт, который пишет первым» → кнопка «Подключить» (или «Обновить сессию/токен») → вставьте скопированное → «Сохранить».
4. Через 10–20 секунд статус аккаунта станет «онлайн». Сценарии, лимиты и журнал — на вкладке «Агент».

• Запасной путь — вход по номеру. Если расширение недоступно или сессия перестала работать, в той же карточке есть «Вход по номеру»: код придёт по SMS (для MAX) или в Telegram.
• Не завершайте эту сессию в Telegram → «Устройства»: агент войдёт по той же сессии и иначе отключится.
• MAX — отдельный аккаунт агента, а не аккаунт Поддержки: если MAX ограничит агента, входящие сообщения Поддержки продолжат работать.
• api_id / api_hash для Telegram не нужны, когда есть строка сессии из расширения.

MAX — токен и Device ID. Для MAX то же расширение берёт из открытой вкладки web.max.ru два значения — «Токен MAX (__oneme_auth)» и «Device ID» — и показывает их для вставки в карточку «Аккаунт MAX, который пишет первым» (Настройки → Сообщения → MAX). Это отдельный аккаунт агента, а не аккаунт Поддержки.

Аккаунт ВКонтакте, который пишет первым

Во ВКонтакте агент тоже может писать клиенту первым — от личного аккаунта компании, а не только от сообщества. Нужен токен аккаунта VK: расширение «Ключ сессии СмИТ» на вкладке vk.com или vk.ru отдаёт его по уже открытой сессии, без повторного входа. Токен вставляют в карточку «Аккаунт VK, который пишет первым» (Настройки → Сообщения → VK).

Это отдельный путь от сообщения от сообщества (см. «Вкладку ВКонтакте» выше): сообществу человек должен сам разрешить сообщения, а аккаунт пишет первым. VK ограничивает аккаунты за массовую рассылку незнакомым — начинайте с низких лимитов.

Кто из клиентов есть в мессенджере — проверка номеров

На вкладках Telegram, MAX и VK под аккаунтом агента есть блок «Кто из клиентов есть в …». Он постепенно проходит клиентов организации аккаунта и узнаёт, есть ли номер в мессенджере — можно ли написать клиенту первым. Сообщения клиентам при этом не уходят.

• Есть — номер найден. Агент потом пишет такому клиенту сразу, без повторного поиска.
• Нет или скрыт — номера нет в мессенджере или клиент закрыл поиск по номеру. Агент 30 дней не тратит на него попытку и сразу переходит к следующему каналу сценария.
• Не проверены — до них проверка ещё не дошла.

«Проверить клиентов» открывает окно с настройками:

Пока проверка идёт, видны процент и полоса хода, сколько найдено, сколько нет, сколько осталось дней при текущем лимите, и последние номера. Проверку можно поставить на паузу, продолжить или остановить — найденное останется.

Мессенджеры ограничивают массовый поиск по номерам. Если Telegram или MAX временно запретит аккаунту поиск (FLOOD), проверка сама встанет на паузу, а в чат тревог придёт сообщение — продолжите через несколько часов. VK находит только тех, кто разрешил поиск по номеру; клиенты с привязанным VK из личного кабинета отмечаются сразу, без запроса.

Как идёт проверка:

sequenceDiagram
    autonumber
    participant B as Биллинг (раз в минуту)
    participant A as Аккаунт агента
    participant M as Мессенджер
    participant K as Карточка клиента
    B->>B: следующие клиенты организации с номером
(пропуск проверенных и тех, кто писал сам)
    B->>A: номера — с паузами, не больше лимита в минуту и в день
    A->>M: поиск по номеру, без сообщения
    alt номер найден
        M-->>A: есть, имя в мессенджере
        A-->>B: «есть» → агент потом пишет без поиска
    else нет или скрыт
        M-->>A: не найден
        A-->>B: «нет» → 30 дней агент сразу идёт к следующему каналу
    else мессенджер ограничил (FLOOD)
        M-->>A: временный запрет
        A-->>B: пауза проверки и сообщение в чат тревог
    end
    B->>K: «есть / нет · дата» во вкладке «Сообщения»

Итог виден в карточке клиента: вкладка «Сообщения», рядом с каналами Telegram и MAX — отметка «есть» или «нет» с датой проверки.

На демо-стенде показаны примерные данные, запуск проверки там недоступен.

Сценарии агента: каналы и порядок

В окне сценария на вкладке «Каналы и порядок» — список каналов с номером шага. Переключатель включает канал, стрелки меняют порядок. У каждого канала пояснение: «Где клиент уже писал» — мессенджер, где клиент уже переписывался с нами; Telegram, MAX и ВКонтакте — аккаунты компании; SMS — запасной вариант, текст на вкладке «Сообщения». Если аккаунта мессенджера у организации нет, под ним сказано «аккаунт не подключён — канал пропустится».

flowchart TD
    S["Повод сценария:
долг, выезд, заявка, недозвон"] --> C1{"Шаг 1: где клиент
уже писал?"}
    C1 -- "есть такой мессенджер" --> SEND["Сообщение от аккаунта агента"]
    C1 -- "нет" --> C2{"Следующий канал по порядку:
аккаунт подключён и номер найден?"}
    C2 -- "да" --> SEND
    C2 -- "нет — следующий шаг" --> C2
    C2 -- "мессенджеры кончились" --> SMS{"SMS включена
в сценарии?"}
    SMS -- "да" --> SENDSMS["SMS с текстом сценария"]
    SMS -- "нет" --> NF["«Нет в мессенджерах»
в журнале агента"]

Вкладка «Шаблоны»

Тексты сообщений клиентам. Системные шаблоны биллинг отправляет сам по событию и находит по названию — «Низкий баланс», «Блокировка», «Задолженность», «Новая услуга» и другие, поэтому название системного шаблона лучше не менять. Остальные выбирают вручную — в рассылке или в ответе клиенту.

Сводка над таблицей: включено из всех, по событию и вручную, отправлено за 30 дней, «Требуют внимания» (включён без каналов, пустой текст, SMS длиннее двух частей, ошибки доставки) и, с модулем «Мультиорганизация», сколько своих шаблонов у организаций. Клик по карточке оставляет в таблице только эти шаблоны, повторный клик снимает фильтр.

Ниже — кнопка «+» (новый шаблон), поиск по названию и тексту (Ctrl+K), фильтр каналов цветными значками с числом шаблонов (можно выбрать несколько) и ряд организаций бейджами: «Все», «Общие» и каждая организация. Под названием шаблона видно «своя версия у N орг.» у общего, «заменяет общий» у своего и причину у проблемного. Кнопка с колонками — какие колонки показывать, набор сохраняется в профиле. На телефоне каждый шаблон — карточка.

Массовые действия

Отметьте шаблоны галочками — сверху появится панель:

• Включить и Выключить — выключение спрашивает подтверждение: по событиям шаблоны перестанут уходить;
• Канал — включить или выключить один канал сразу у всех отмеченных;
• Копия для организации — свой шаблон организации с тем же названием и текстом (с модулем «Мультиорганизация»);
• Удалить — системные шаблоны не удаляются, их можно только выключить; пропущенные показываются списком.

Шаблоны организаций

Шаблон бывает общим — для клиентов всех организаций — или своим у организации. Свой шаблон с тем же названием заменяет общий для её клиентов: например, у организации свой «Низкий баланс» с её названием и телефоном. Выключенный свой шаблон значит «клиентам этой организации не отправлять» — общий вместо него тоже не уйдёт.

Сотрудник с доступом ко всем организациям правит общие шаблоны и шаблоны любой организации. Сотрудник с доступом только к части организаций видит общие шаблоны и шаблоны своих организаций, а править может только свои: общий открывается для просмотра, вместо правки — «Копия для организации». Организация, выбранная в шапке, сужает список до общих и её шаблонов.

Окно шаблона

Четыре вкладки, внизу — «Отмена», «Копия» и «Сохранить».

• Текст — название, заголовок (тема письма и заголовок push) и текст в редакторе с подсветкой. Справа подстановки: нажатие вставляет её в место курсора. Над текстом — счётчик знаков и SMS и кнопка «AI».
• Письмо — HTML-версия для email. Уходит внутри фирменного макета: логотип и подвал с реквизитами добавятся сами. Пусто — письмо соберётся из текста. «Готовые письма» — заготовки, от которых можно оттолкнуться.
• Предпросмотр — SMS так, как его увидит клиент на телефоне, и письмо целиком, с примерными значениями (договор 10245, Иванов Иван Петрович, баланс 150.00). Ничего не отправляется.
• Параметры — организация (или «Общий — для всех организаций»), каналы и режим: «Включён — уходит клиентам», «Системный — отправляет биллинг по событию», «Повторять каждый день, пока условие держится».

Подстановки

Длина SMS: кириллица — 70 знаков в одной SMS, длинная склеивается по 67; только латиница — 160 и 153. Счётчик считает текст без подстановок, а ФИО и тариф добавят знаков, поэтому оставляйте запас.

AI-помощник

Кнопка «AI» над текстом и помощник раздела («Помощник по шаблонам») пишут и правят шаблоны: «напиши SMS о плановых работах завтра с 2 до 4 ночи», «сократи до одной SMS», «сделай HTML-письмо для этого текста». Помощник видит открытый шаблон, его каналы и список подстановок. Готовый черновик открывается кнопкой «Открыть в окне шаблона» — проверьте предпросмотр и сохраните. Сам помощник ничего не сохраняет и не отправляет.

Что берёт каждый канал

flowchart LR
    T["Шаблон"] --> H{"Заполнено
«Письмо»?"}
    H -- "да" --> L["HTML в фирменном макете"]
    H -- "нет" --> P["Текст шаблона во встроенном
письме по событию"]
    L --> S{"У организации клиента
свой SMTP?"}
    P --> S
    S -- "да" --> OS["SMTP организации"]
    S -- "нет" --> GS["Общий SMTP"]
    OS -. "не ответил" .-> GS