Конечные точки обмена сообщениями

Модуль "Обмена сообщениями" управляет беседами в реальном времени, сообщениями в чате, отправкой push-уведомлений, доставкой SMS/электронной почты, соединениями WebSocket, частными сообщениями, регистрацией устройств и поставщиками текстовых сообщений. Он предоставляет коммуникационный уровень, используемый во всех приложениях ChurchApps как для прямого чата трансляции, так и для асинхронных уведомлений.

Базовый путь: /messaging

Беседы

Базовый путь: /messaging/conversations

Метод	Путь	Auth	Разрешение	Описание
GET	/timeline/ids?ids=	JWT	—	Загрузите беседы по идентификаторам, разделённым запятыми, с первыми/последними сообщениями
GET	/messages/:contentType/:contentId	JWT	—	Загрузите беседы по содержанию с разбивкой на страницы сообщений (?page=&limit=)
GET	/posts	JWT	—	Получите беседы типа-публикации для групп текущего пользователя
GET	/posts/group/:groupId	JWT	—	Получите беседы типа-публикации для определённой группы
GET	/current/:churchId/:contentType/:contentId	Public	—	Получите или создайте текущую беседу по содержанию (автоматически расшифровывает contentId)
GET	/:churchId/:contentType/:contentId	Public	—	Загрузите беседы по типу содержания и ID
GET	/:churchId/:id	Public	—	Загрузите одну беседу по ID
POST	/	JWT	—	Создавайте или обновляйте беседы (пакет)
POST	/start	JWT	—	Начните новую беседу с начальным сообщением-комментарием
DELETE	/:churchId/:id	JWT	—	Удалите беседу

Контроль доступа к личным примечаниям

Беседы с contentType: "person" (вкладка "Примечания" в записи о человеке) или contentType: "personConfidential" (раздел "Конфиденциальные примечания") контролируются на каждом пути чтения и записи, включая в противном случае публичные маршруты выше, которые возвращают 401 для этих типов содержания. person требует разрешение MembershipApi Люди / Редактировать; personConfidential требует Люди / Просмотр конфиденциальных примечаний. Для ограниченных ключей API, people:write имеет оба действия (пользователь ключа должен всё ещё иметь базовое разрешение роли).

Пример: начните беседу

POST /messaging/conversations/start
Authorization: Bearer <token>

{
  "groupId": "group-123",
  "contentType": "group",
  "contentId": "group-123",
  "title": "Weekly Discussion",
  "comment": "Welcome to this week's discussion thread!"
}

{
  "id": "conv-456",
  "churchId": "church-789",
  "contentType": "group",
  "contentId": "group-123",
  "title": "Weekly Discussion",
  "dateCreated": "2026-02-17T10:00:00.000Z",
  "visibility": "public",
  "allowAnonymousPosts": false,
  "groupId": "group-123"
}

Сообщения

Базовый путь: /messaging/messages

Метод	Путь	Auth	Разрешение	Описание
GET	/conversation/:conversationId	JWT	—	Загрузите все сообщения для беседы
GET	/catchup/:churchId/:conversationId	Public	—	Загрузите все сообщения для беседы (публичное наверстывание для прямого чата)
GET	/:churchId/:id	Public	—	Загрузите одно сообщение по ID
POST	/	JWT	—	Сохраняйте сообщения (пакет). Отправляйте обновления в реальном времени и запускайте уведомления
POST	/send	Public	—	Отправьте сообщения (пакет, публичное). Отправляйте обновления в реальном времени через WebSocket и запускайте уведомления
POST	/setCallout	JWT	—	(устарелое) Транслируйте сообщение объявления в реальном времени. Без активного клиента; чат прямой трансляции больше не отображает объявления
DELETE	/:churchId/:id	JWT	—	Удалите сообщение и транслируйте удаление в реальном времени

Пример: отправьте сообщение

POST /messaging/messages/send

[
  {
    "churchId": "church-789",
    "conversationId": "conv-456",
    "personId": "person-123",
    "displayName": "John Smith",
    "content": "Hello everyone!",
    "messageType": "comment"
  }
]

[
  {
    "id": "msg-001",
    "churchId": "church-789",
    "conversationId": "conv-456",
    "personId": "person-123",
    "displayName": "John Smith",
    "timeSent": "2026-02-17T10:05:00.000Z",
    "content": "Hello everyone!",
    "messageType": "comment"
  }
]

Частные сообщения

Базовый путь: /messaging/privatemessages

Метод	Путь	Auth	Разрешение	Описание
GET	/	JWT	—	Загрузите все частные сообщения для текущего пользователя (включает последнее сообщение за беседу, помечает все как прочитанные)
GET	/existing/:personId	JWT	—	Найдите существующую приватную беседу с определённым человеком
GET	/:id	JWT	—	Загрузите частное сообщение по ID (очищает уведомление, если адресовано текущему пользователю)
POST	/	JWT	—	Отправьте частные сообщения (пакет). Запускайте отправку push-уведомления получателю

Уведомления

Базовый путь: /messaging/notifications

Метод	Путь	Auth	Разрешение	Описание
GET	/unreadCount	JWT	—	Получите непрочитанное количество уведомлений для текущего пользователя
GET	/my	JWT	—	Загрузите все уведомления для текущего пользователя (помечает все как прочитанные)
GET	/tmpEmail	Public	—	Запустите дневное резюме уведомления по электронной почте (отладка/крон конечная точка)
GET	/:churchId/person/:personId	JWT	—	Загрузите уведомления для определённого человека
GET	/:churchId/:id	JWT	—	Загрузите уведомление по ID
POST	/	JWT	—	Создавайте или обновляйте уведомления (пакет)
POST	/create	JWT	—	Создавайте уведомления для нескольких людей. Тело: { peopleIds, contentType, contentId, message, link }
POST	/markRead/:churchId/:personId	JWT	—	Пометьте все уведомления как прочитанные для человека
POST	/sendTest	JWT	—	Отправьте тестовое push-уведомление. Тело: { personId, title }
POST	/ping	Public	—	Создайте уведомление из внешнего триггера. Тело: { personId, churchId, contentType, contentId, message, triggeredByPersonId }
DELETE	/:churchId/:id	JWT	—	Удалите уведомление

Пример: создавайте уведомления

POST /messaging/notifications/create
Authorization: Bearer <token>

{
  "peopleIds": ["person-123", "person-456"],
  "contentType": "group",
  "contentId": "group-789",
  "message": "New event posted in your group",
  "link": "/groups/group-789"
}

Предпочтения уведомлений

Базовый путь: /messaging/notificationpreferences

Расширяет стандартный CRUD. Базовый класс предоставляет POST / (создавайте или обновляйте, без требуемого разрешения).

Метод	Путь	Auth	Разрешение	Описание
POST	/	JWT	—	Создавайте или обновляйте предпочтения уведомлений (из базового класса CRUD)
GET	/my	JWT	—	Загрузите предпочтения уведомлений для текущего пользователя (автоматически создаёт значения по умолчанию, если они не существуют)

Соединения

Базовый путь: /messaging/connections

Управляет подключениями WebSocket/реального времени для чата, групповых бесед, частных сообщений и прямой трансляции. Полный протокол см. в Архитектура реального времени.

Метод	Путь	Auth	Разрешение	Описание
GET	/:churchId/:conversationId	Public	—	Загрузите все соединения для беседы
POST	/	Public	—	Регистрируйте соединения (пакет). Запускайте трансляцию присутствия на беседу. Элементы тела: { churchId, conversationId, socketId, displayName?, personId? }
POST	/setName	Public	—	Обновите отображаемое имя для соединения по ID сокета. Тело: { socketId, name }
DELETE	/:churchId/:conversationId/:socketId	Public	—	Удалите соединение из беседы. Запускайте трансляцию присутствия
POST	/tmpSendAlert	Public	—	Отправьте оповещение об уведомлении на соединения человека. Тело: { churchId, personId }

Устройства

Базовый путь: /messaging/devices

Управляет регистрацией устройств для отправки push-уведомлений и спаривания содержания (например, приложение уроков на дисплеях телевизора).

Метод	Путь	Auth	Разрешение	Описание
POST	/enroll	JWT	—	Зачислите или обновите устройство (регистрация мобильного push-сервиса). Совпадает по токену FCM или ID устройства
POST	/enrollAnon	Public	—	Зачислите анонимное устройство и создайте 4-значный код спаривания
POST	/	Public	—	Сохраняйте устройства (пакет)
GET	/pair/:pairingCode	JWT	—	Спарьте устройство с использованием его кода спаривания. Опционально ?contentType=&contentId= для назначения содержания
GET	/status/:deviceId	Public	—	Проверьте статус спаривания устройства
GET	/:churchId	JWT	—	Загрузите все устройства для церкви
GET	/:churchId/person/:personId	JWT	—	Загрузите все устройства для человека
GET	/:churchId/:id	JWT	—	Загрузите устройство по ID
DELETE	/:churchId/:id	JWT	—	Удалите устройство

Пример: зачислите устройство

POST /messaging/devices/enroll
Authorization: Bearer <token>

{
  "fcmToken": "firebase-token-abc123",
  "appName": "B1Mobile",
  "label": "John's iPhone",
  "deviceInfo": "iOS 17, iPhone 15"
}

{
  "id": "device-001",
  "churchId": "church-789",
  "fcmToken": "firebase-token-abc123",
  "appName": "B1Mobile",
  "label": "John's iPhone",
  "registrationDate": "2026-02-17T10:00:00.000Z",
  "lastActiveDate": "2026-02-17T10:00:00.000Z"
}

Содержание устройства

Базовый путь: /messaging/devicecontents

Управляет назначениями содержания для спаренных устройств (например, какой урок отображается на телевизоре).

Метод	Путь	Auth	Разрешение	Описание
GET	/deviceId/:deviceId	JWT	—	Загрузите назначения содержания для устройства
POST	/	JWT	—	Сохраняйте назначения содержания устройства (пакет)
DELETE	/:id	JWT	—	Удалите назначение содержания устройства

Обмен текстовыми сообщениями

Базовый путь: /messaging/texting

Управляет поставщиками SMS, групповыми текстовыми сообщениями и отслеживанием доставки.

Метод	Путь	Auth	Разрешение	Описание
GET	/providers	JWT	—	Загрузите поставщиков текстовых сообщений для церкви (учётные данные маскируются)
GET	/preview/:groupId	JWT	—	Просмотрите получателей для текстового сообщения группы (подходящие, отказано, количество без телефона)
GET	/sent	JWT	—	Загрузите все отправленные записи текстовых сообщений для церкви
GET	/sent/:id/details	JWT	—	Загрузите отправленный текст с логами доставки для каждого получателя
POST	/providers	JWT	—	Сохраняйте поставщиков текстовых сообщений (пакет). Шифрует учётные данные API
POST	/send	JWT	—	Отправьте SMS всем подходящим членам группы. Тело: { groupId, message }
POST	/sendPerson	JWT	—	Отправьте SMS одному человеку. Тело: { personId, phoneNumber, message }
DELETE	/providers/:id	JWT	—	Удалите поставщика текстовых сообщений

Пример: отправьте групповой текст

POST /messaging/texting/send
Authorization: Bearer <token>

{
  "groupId": "group-123",
  "message": "Reminder: Service starts at 10 AM this Sunday!"
}

{
  "totalMembers": 50,
  "recipientCount": 42,
  "successCount": 40,
  "failCount": 2,
  "optedOutCount": 5,
  "noPhoneCount": 3
}

Шаблоны писем

Базовый путь: /messaging/emailTemplates

Управляет повторно используемыми шаблонами писем и отправкой писем на основе шаблонов группам.

Метод	Путь	Auth	Разрешение	Описание
GET	/	JWT	—	Загрузите все шаблоны писем для церкви
GET	/:id	JWT	—	Загрузите один шаблон письма по ID
GET	/preview/:groupId	JWT	—	Просмотрите доставку писем для группы (количество подходящих получателей, члены без электронной почты)
POST	/	JWT	—	Создавайте или обновляйте шаблоны писем (пакет)
POST	/send	JWT	—	Отправьте письмо на основе шаблона всем членам группы. Тело: { groupId, subject, htmlContent }
DELETE	/:id	JWT	—	Удалите шаблон письма

Пример: отправьте письмо группе

POST /messaging/emailTemplates/send
Authorization: Bearer <token>

{
  "groupId": "group-123",
  "subject": "This Week's Update - {{churchName}}",
  "htmlContent": "<p>Hello {{firstName}},</p><p>Here's what's happening this week...</p>"
}

{
  "totalMembers": 50,
  "recipientCount": 45,
  "successCount": 44,
  "failCount": 1,
  "noEmailCount": 5
}

Поддерживаемые поля слияния: {{firstName}}, {{lastName}}, {{displayName}}, {{email}}, {{churchName}}

Заблокированные IP-адреса

Базовый путь: /messaging/blockedips

(устарелое) Блокировка IP для чата прямой трансляции. Клиент B1App больше не вызывает POST / — блокировка IP была удалена при миграции унифицированной доставки. Маршрут /clear всё ещё вызывается сервер-к-серверу StreamingServiceController при сохранении служб трансляции.

Метод	Путь	Auth	Разрешение	Описание
POST	/	JWT	—	(устарелое) Сохраняйте заблокированные IP-адреса (пакет). Без активного клиента
POST	/clear	JWT	—	Очистите все заблокированные IP-адреса для определённых служб. Тело: [{ serviceId, churchId }]

Журналы доставки

Базовый путь: /messaging/deliverylogs

Отслеживает статус доставки отправленных сообщений (SMS, push-уведомления, электронная почта).

Метод	Путь	Auth	Разрешение	Описание
GET	/content/:contentType/:contentId	JWT	—	Загрузите журналы доставки по типу содержания и ID
GET	/person/:personId	JWT	—	Загрузите журналы доставки для человека. Опционально ?startDate=&endDate= фильтры
GET	/recent	JWT	—	Загрузите недавние журналы доставки для церкви. Опционально ?limit= (по умолчанию 100)
GET	/:id	JWT	—	Загрузите журнал доставки по ID

Связанные страницы

• Архитектура реального времени — протокол WebSocket, подписки на комнаты и унифицированная платформа доставки
• Web Push Уведомления — регистрация отправки в браузер и доставка
• Конечные точки членства — люди, группы, роли и основная идентичность
• Конечные точки посещаемости — служба и отслеживание посещений
• Аутентификация и разрешения — поток входа, JWT, OAuth, модель разрешений
• Структура модуля — шаблоны организации кода