Кампании рассылки
| Название | Статус | Прогресс | Действие |
|---|
Компании
Внешние чаты и пользователи
Кнопка синхронизирует чаты из подключенных каналов, после чего их можно отметить и добавить в аудиторию.
| Название | Тип | Канал | ID |
|---|
Аудитории Mercury CRM
| Аудитория | Участников | Действия |
|---|
Подключение аккаунтов (QR)
Глобальные API ключи задаются администратором. Здесь подключаются рабочие аккаунты Telegram и WhatsApp.
| Название | Канал | ID профиля | Статус | Действия |
|---|
Лимиты отправки
Лимиты отправки задаются отдельно для каждого пользователя.
Админ: API настройки и заявки
Пользователи
Все пользователи
| Логин | Имя | Роль | Статус |
|---|
Заявки пользователей
| Логин | Имя | Статус | Действие |
|---|
Техническая карта Mercury CRM
Архитектура и данные
Mercury CRM разделяет интерфейс, прикладной API, очередь отправки, локальное хранилище и внешние каналы. Данные пользователя изолированы по владельцу, а отправка выполняется серверным воркером с лимитами и повторными попытками.
Рабочее место
Браузер
Интерфейс, авторизация, выбор аудитории и контроль кампаний
API
Ядро CRM
Express + бизнес-логика
Права доступа, аудитории, очередь, статусы и настройки
Данные
Хранилище
SQLite
Пользователи, интеграции, аудитории, кампании и журнал событий
Исходящая отправка
Воркер очереди -> Whapi.Cloud / TDLib
Обратные события
Webhook провайдера -> API -> журнал и статус сообщения
Сессии Telegram
TDLib хранит авторизацию на сервере отдельно от базы CRM
Модель данных
Что и где хранится
Секреты и пароли не выводятся в интерфейсе. Токены интеграций хранятся на стороне сервера.
| Сущность | Назначение | Связи и ключевые поля | Правило жизненного цикла |
|---|---|---|---|
users | Учётные записи и роли сотрудников. | id, логин, роль, статус доступа. | Новый пользователь ожидает одобрения администратора. |
sessions | Серверные сессии авторизации. | Привязаны к user_id, токен хранится в виде хеша. | Истекают по сроку, заданному в настройках сервера. |
integrations | Подключённые WhatsApp и Telegram аккаунты. | Владелец, канал, профиль, серверный токен, признак активности. | Не удаляются, пока на них ссылаются сообщения кампаний. |
external_targets | Чаты, группы, каналы и пользователи, полученные из интеграции. | Привязаны к интеграции; внешний ID уникален в её пределах. | Обновляются синхронизацией. Доступность зависит от текущего аккаунта. |
audiences | Именованные сегменты для запуска рассылок. | Владелец, название, описание. | Не удаляются, пока используются кампаниями. |
audience_members | Состав аудитории. | Связка audience_id и target_id. | Один получатель не дублируется в одной аудитории. |
campaigns | Кампания и её текст. | Владелец, аудитория, статус, даты запуска и завершения. | Черновик -> запуск -> завершение, остановка или ошибка. |
campaign_messages | Индивидуальная очередь отправки. | Кампания, интеграция, получатель, попытки, ошибка, ответ провайдера. | Каждому получателю кампании соответствует одна запись очереди. |
webhook_events | Технический журнал событий от провайдеров. | Канал, интеграция, тип события, исходный payload. | Используется для уточнения финального статуса доставки. |
app_settings / user_settings | Глобальные ключи и персональные лимиты отправки. | Пары ключ-значение; пользовательские настройки привязаны к владельцу. | Глобальные ключи доступны только администратору. |
Поток кампании
Как сообщение проходит систему
- Синхронизация: CRM получает доступные чаты и контакты из выбранного аккаунта.
- Аудитория: пользователь добавляет выбранные сущности в сегмент без дублей.
- Запуск: для каждого активного участника создаётся отдельная запись
campaign_messages. - Очередь: воркер каждые 2,5 секунды выбирает готовые сообщения и проверяет персональные лимиты.
- Провайдер: WhatsApp получает задачу через Whapi.Cloud, Telegram отправляется через TDLib.
- Результат: ответ записывается в сообщение; webhook может дополнительно подтвердить доставку или ошибку.
Статусы и контроль
Что означают результаты
- Черновик
- Кампания сохранена, очередь ещё не создана.
- Запущена
- Очередь обрабатывается в пределах заданных лимитов.
- Отправлено
- Telegram принял сообщение, а WhatsApp-провайдер принял задачу на отправку. Финальная доставка WhatsApp подтверждается только webhook-событием.
- Ошибка
- После трёх неудачных попыток сообщение помечается как неотправленное, а текст причины сохраняется в журнале.
- Пауза / стоп
- Неотправленные элементы очереди больше не передаются провайдеру.
Эксплуатация и безопасность
Правила для команды
Доступ и секреты
- Администратор управляет глобальным токеном Whapi.Cloud и Telegram API credentials.
- Пользователь видит и использует только свои интеграции, аудитории, кампании и лимиты.
- Пароли, сессии Telegram и API-токены не должны попадать в переписку, скриншоты и клиентский код.
Синхронизация получателей
- Перед массовой отправкой обновляйте список чатов по каждому каналу.
- Если Telegram возвращает
Chat not found, текущий аккаунт больше не имеет доступа к этому чату или изменился его контекст. - Проверяйте состав аудитории перед стартом: устаревшие записи не должны участвовать в новой кампании.
Надёжность и восстановление
- Перед обновлением сервера делается резервная копия приложения и базы данных.
- SQLite работает в WAL-режиме: резервная копия должна включать основную базу и актуальное состояние журнала.
- При инциденте сначала фиксируются ID кампании, ошибка и время, затем проверяются журнал сервиса и
campaign_messages.
Как пользоваться: инструкция для пользователя
1. Подключение и подготовка
- Войдите в Mercury CRM под своим логином и паролем (после одобрения администратором).
- Откройте вкладку Настройки и создайте свой профиль для нужного канала.
- Для WhatsApp создайте профиль и отсканируйте QR код со своего телефона.
- Для Telegram создайте профиль, нажмите Вход TG и последовательно введите номер, код из Telegram и пароль 2FA, если он включен.
- После подключения профиля нажмите Синхр, чтобы загрузить чаты и контакты в CRM.
2. Формирование аудитории
- Откройте вкладку Аудитория.
- В левом блоке Внешние чаты и пользователи выберите интеграцию и при необходимости введите поиск по имени/ID.
- Нажмите Синхронизировать, чтобы получить актуальные чаты и контакты из выбранной интеграции.
- Отметьте нужные записи галочками.
- В правом блоке выберите аудиторию и нажмите Добавить отмеченные.
- Кнопкой Показать участников проверьте, кто уже входит в выбранную аудиторию.
3. Создание и запуск кампании
- Перейдите во вкладку Компании.
- Заполните: название кампании, аудитория, текст сообщения.
- Текст сообщения вводится полностью вручную. Эмодзи поддерживаются.
- Нажмите Создать кампанию, затем в таблице нажмите Старт.
- При необходимости нажмите Стоп для остановки отправки.
- Кнопка Удалить удаляет кампанию и ее очередь сообщений.
4. Статусы и контроль результата
- Статус Черновик означает, что кампания создана, но не запущена.
- Статус Запущена означает активную отправку сообщений по очереди.
- В поле Прогресс видно, сколько сообщений отправлено и сколько завершилось ошибкой.
- Если есть ошибки, проверьте статус своего профиля в Настройках, затем повторите синхронизацию и проверьте корректность выбранных чатов.
Как пользоваться: инструкция для администратора
1. Первичная настройка системы
- Откройте вкладку Настройки.
- В блоке API-настроек укажите токен Whapi.Cloud для WhatsApp.
- Проверьте публичный URL сервера (для вебхуков и обратных уведомлений, если используются).
- Для Telegram TDLib заполните прямо в админке поля Telegram API ID и Telegram API Hash (значения берутся на
my.telegram.org). - После сохранения API настроек пользователи и администратор смогут создавать собственные интеграции и подключать свои аккаунты.
2. Подключение рабочих каналов команды
- Проверьте, что пользователи могут самостоятельно создавать интеграции WhatsApp и Telegram.
- При необходимости создайте и свои рабочие профили, если администратор тоже будет делать рассылки.
- Если в команде используются общие профили, не удаляйте их без понимания, какие аудитории и кампании на них завязаны.
- Рекомендуемая схема для экономии: использовать общие API ключи провайдеров, но подключать личные аккаунты пользователей как отдельные профили.
3. Управление пользователями и безопасностью
- В блоке Заявки пользователей одобряйте или отклоняйте регистрацию.
- В блоке Все пользователи контролируйте роли и статусы доступа.
- Администратор управляет регистрациями и одобрением пользователей.
- Глобальные API токены и серверные ключи не должны передаваться пользователям напрямую вне CRM.
4. Эксплуатация и поддержка
- Если чаты не подтягиваются, сначала проверьте статус интеграции, затем повторите синхронизацию.
- При ошибках Telegram проверьте состояние TDLib-авторизации и повторите шаги входа.
- При каждом деплое делайте серверный бэкап перед обновлением.
- Периодически проверяйте логи сервиса и состояние очередей кампаний.