Эндпоинты обмена сообщениями
Модуль Messaging управляет диалогами в реальном времени, сообщениями чата, push-уведомлениями, доставкой SMS и email, WebSocket-соединениями, личными сообщениями, регистрацией устройств и провайдерами SMS. Он обеспечивает слой связи, который используется во всех приложениях ChurchApps как для чата прямых трансляций, так и для асинхронных уведомлений.
Базовый путь: /messaging
Переписки
Базовый путь: /messaging/conversations
| Метод | Путь | Аутентификация | Право | Описание |
|---|---|---|---|---|
| GET | /timeline/ids?ids= | JWT | — | Загрузить переписки по ID через запятую с первым и последним сообщениями |
| GET | /messages/:contentType/:contentId | JWT | — | Загрузить переписки для контента с постраничными сообщениями (?page=&limit=) |
| GET | /posts | JWT | — | Получить переписки-посты для групп текущего пользователя |
| GET | /posts/group/:groupId | JWT | — | Получить переписки-посты для конкретной группы |
| GET | /notes/feed?section=&limit=&before= | JWT | — | Новейшие заметки по всем записям для страницы Notes в B1 Admin. section -- people, groups, events или workflows (иначе 400); limit по умолчанию 25 (максимум 100); before -- курсор из предыдущей страницы. Каждая заметка по-прежнему проходит правило своего типа (право People Edit / доступ к конфиденциальным заметкам, руководители группы, просматривающие события, просматривающие карточки рабочих процессов), поэтому вызывающий видит только те заметки, которые мог бы открыть. Текст заметки обрезается до 300 символов |
| GET | /current/:churchId/:contentType/:contentId | Публичный | — | Получить или создать текущую переписку для контента (автоматически расшифровывает contentId) |
| GET | /:churchId/:contentType/:contentId | Публичный | — | Загрузить переписки по типу контента и ID |
| GET | /:churchId/:id | Публичный | — | Загрузить одну переписку по ID |
| POST | / | JWT | — | Создать или обновить переписки (пакетно) |
| POST | /start | JWT | — | Начать новую переписку с первым комментарием |
| DELETE | /:churchId/:id | JWT | — | Удалить переписку |
Контроль доступа к заметкам о людях
Переписки с contentType: "person" (вкладка Notes в карточке человека) или contentType: "personConfidential" (раздел конфиденциальных заметок) закрыты на каждом пути чтения и записи, включая публичные маршруты выше, которые для этих типов контента возвращают 401. Для person требуется право MembershipApi People / Edit, для personConfidential -- People / View Confidential Notes. Для ключей API с ограниченными областями people:write покрывает оба действия (пользователь ключа по-прежнему должен иметь соответствующее право роли).
Контроль доступа к заметкам групп и событий
Два других типа заметок закрыты так же, на каждом пути чтения и записи (включая публичные маршруты выше), и никогда не открыты для анонимной публикации:
groupNote(contentId= ID группы) -- лента Заметки руководителей в группе. Читать или писать могут только руководители этой группы (leaderGroupIdsв JWT). Никакое право сотрудника не даёт доступа, включаяcontent.editи права участия в группах.eventNote(contentId= ID события) -- заметки к событию календаря. Сотрудники сcontent.editили Calendars / Admin всегда могут читать и писать. В остальных случаях доступ определяетсяnotesViewRole(чтение) иnotesPostRole(запись) события:staff(по умолчанию, если поле равноnull) не даёт доступа никому другому,leadersдаёт доступ руководителям группы события, аmembers-- участникам и руководителям группы события. Событие безgroupIdдоступно только сотрудникам.
Контроль доступа к заметкам карточек рабочих процессов
Переписки с contentType: "workflowCard" (заметки к карточке рабочего процесса, где contentId -- ID задачи карточки) доступны для чтения и записи только тем, кто может открыть эту карточку: пользователю с правом DoingApi Tasks / View, либо человеку или группе, которым карточка назначена, создана или которые в ней упоминаются. Всем остальным возвращается 401 на каждом пути чтения, включая публичные маршруты выше. Переписка карточки прикрепляется через саму карточку, POST /doing/tasks/:id/conversation (тело { "conversationId": "..." }; побеждает первая прикреплённая переписка), что могут вызывать редакторы карточки и её исполнитель.
Пример: начать переписку
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
| Метод | Путь | Аутентификация | Право | Описание |
|---|---|---|---|---|
| GET | /conversation/:conversationId | JWT | — | Загрузить все сообщения переписки |
| GET | /catchup/:churchId/:conversationId | Публичный | — | Загрузить все сообщения переписки (публичная догрузка для чата в реальном времени) |
| GET | /:churchId/:id | Публичный | — | Загрузить одно сообщение по ID |
| POST | / | JWT | — | Сохранить сообщения (пакетно). Отправляет обновления в реальном времени и запускает уведомления. Чтобы изменить существующее сообщение, нужно быть его автором или иметь content.edit; сохранённый автор никогда не может быть переназначен |
| POST | /send | Публичный | — | Отправить сообщения (пакетно, публично). Отправляет обновления в реальном времени через WebSocket и запускает уведомления |
| POST | /setCallout | JWT | — | (устаревшее) Широковещательно отправить сообщение-выноску в реальном времени. Активного клиента нет; чат прямых трансляций больше не отображает выноски |
| DELETE | /:churchId/:id | JWT | — | Удалить сообщение и разослать удаление в реальном времени. См. Модерация сообщений |
Модерация сообщений
Удалить сообщение могут:
- автор сообщения;
- сотрудники с
content.edit(в любом месте церкви); - руководители групп -- для переписок с
contentTypegroupилиgroupAnnouncement, у которыхcontentId-- группа, которой они руководят (leaderGroupIdsв JWT).
Переписки с заметками о людях (person / personConfidential) не модерируются руководителями -- для них действуют права на заметки (people.edit, people.viewConfidentialNotes).
Руководители могут только удалять, но не редактировать: переписывать чужое сообщение по-прежнему могут только автор и сотрудники с content.edit.
Пример: отправить сообщение
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
| Метод | Путь | Аутентификация | Право | Описание |
|---|---|---|---|---|
| GET | / | JWT | — | Загрузить все личные сообщения текущего пользователя (включает последнее сообщение каждой переписки, помечает все как прочитанные) |
| GET | /existing/:personId | JWT | — | Найти существующую личную переписку с конкретным человеком |
| GET | /:id | JWT | — | Загрузить личное сообщение по ID (очищает уведомление, если оно адресовано текущему пользователю) |
| POST | / | JWT | — | Отправить личные сообщения (пакетно). Запускает push-уведомление получателю |
Уведомления
Базовый путь: /messaging/notifications
| Метод | Путь | Аутентификация | Право | Описание |
|---|---|---|---|---|
| GET | /unreadCount | JWT | — | Получить количество непрочитанных уведомлений текущего пользователя |
| GET | /my | JWT | — | Загрузить все уведомления текущего пользователя (помечает все как прочитанные) |
| GET | /tmpEmail | Публичный | — | Запустить ежедневную email-сводку уведомлений (отладочный/cron-эндпоинт) |
| 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 | Публичный | — | Создать уведомление из внешнего триггера. Тело: { personId, churchId, contentType, contentId, message, triggeredByPersonId } |
| DELETE | /:churchId/:id | JWT | — | Удалить уведомление |
| GET | /groupPreview/:groupId | JWT | groupMembers.edit | Посчитать, сколько участников группы получит push |
| GET | /churchPreview | JWT | content.edit | Посчитать, сколько людей получит push всем, у кого есть приложение |
| POST | /group/send | JWT | groupMembers.edit | Отправить push участникам группы сейчас |
Пример: создать уведомления
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/scheduledNotifications
Push, отправляемые заранее по расписанию. audience -- church (все, у кого есть приложение; нужно content.edit) или group (нужны groupMembers.edit и groupId). Заголовок ограничен 80 символами, сообщение -- 240. Строка, время отправки которой наступило, отправляется таймером раз в минуту.
| Метод | Путь | Аутентификация | Право | Описание |
|---|---|---|---|---|
| GET | / | JWT | groupMembers.edit или content.edit | Список запланированных и недавних уведомлений церкви |
| POST | / | JWT | по аудитории | Создать запланированное уведомление или обновить его, если задан id. Тело: { id?, audience, groupId?, title, message, link?, imageUrl?, sendAt }. Обновление уведомления, которое уже не ожидает отправки, возвращает 409 |
| POST | /:id/sendNow | JWT | по аудитории | Отправить ожидающее уведомление сейчас. Возвращает 409, если оно уже отправлено, отменено или отправляется |
| DELETE | /:id | JWT | по аудитории | Отменить ожидающее уведомление или убрать из списка отправленное, неудачное или отменённое. Возвращает 409, пока оно отправляется |
| DELETE | / | JWT | groupMembers.edit или content.edit | Удалить все отправленные, неудачные и отменённые уведомления для аудиторий, которым может отправлять пользователь. Возвращает { deleted } |
Настройки уведомлений
Базовый путь: /messaging/notificationpreferences
| Метод | Путь | Аутентификация | Право | Описание |
|---|---|---|---|---|
| GET | /categories | JWT | — | Список категорий уведомлений с их каналами по умолчанию и допустимыми каналами |
| GET | /my | JWT | — | Загрузить настройки уведомлений текущего пользователя (создаёт значения по умолчанию, если их нет) |
| POST | / | JWT | — | Сохранить настройки текущего пользователя. Тело: любые из allowPush, allowSms, emailFrequency, masterMute, quietHoursStart, quietHoursEnd, timeZone, maxPushPerDay, а также необязательные overrides: [{ categoryKey, channel, optedIn }] (channel может быть push, email, in_app или sms; заблокированные категории игнорируются). allowSms -- согласие участника на текстовые напоминания. Устаревший формат тела в виде массива строк по-прежнему принимается |
Соединения
Базовый путь: /messaging/connections
Управляет WebSocket-соединениями в реальном времени для чата, групповых переписок, личных сообщений и прямых трансляций. Сквозной протокол см. в архитектуре реального времени.
| Метод | Путь | Аутентификация | Право | Описание |
|---|---|---|---|---|
| GET | /:churchId/:conversationId | Публичный | — | Загрузить все соединения переписки |
| POST | / | Публичный | — | Зарегистрировать соединения (пакетно). Запускает широковещательное обновление посещаемости переписки. Элементы тела: { churchId, conversationId, socketId, displayName?, personId? } |
| POST | /setName | Публичный | — | Обновить отображаемое имя соединения по ID сокета. Тело: { socketId, name } |
| DELETE | /:churchId/:conversationId/:socketId | Публичный | — | Удалить соединение из переписки. Запускает широковещательное обновление посещаемости |
| POST | /tmpSendAlert | Публичный | — | Отправить оповещение о уведомлении всем соединениям человека. Тело: { churchId, personId } |
Устройства
Базовый путь: /messaging/devices
Управляет регистрацией устройств для push-уведомлений и привязкой контента (например, приложение Lessons на телевизорах).
| Метод | Путь | Аутентификация | Право | Описание |
|---|---|---|---|---|
| POST | /enroll | JWT | — | Зарегистрировать или обновить устройство (регистрация push в мобильном приложении). Совпадение по токену FCM или ID устройства |
| POST | /enrollAnon | Публичный | — | Зарегистрировать анонимное устройство и создать 4-символьный код сопряжения |
| POST | / | Публичный | — | Сохранить устройства (пакетно) |
| GET | /pair/:pairingCode | JWT | — | Сопрячь устройство по коду сопряжения. Необязательные ?contentType=&contentId= назначают контент |
| GET | /status/:deviceId | Публичный | — | Проверить статус сопряжения устройства |
| 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": "B1App",
"label": "John's iPhone",
"deviceInfo": "iOS 17, iPhone 15"
}
{
"id": "device-001",
"churchId": "church-789",
"fcmToken": "firebase-token-abc123",
"appName": "B1App",
"label": "John's iPhone",
"registrationDate": "2026-02-17T10:00:00.000Z",
"lastActiveDate": "2026-02-17T10:00:00.000Z"
}
Содержимое устройств
Базовый путь: /messaging/devicecontents
Управляет назначением контента сопряжённым устройствам (например, какой урок показан на телевизоре).
| Метод | Путь | Аутентификация | Право | Описание |
|---|---|---|---|---|
| GET | /deviceId/:deviceId | JWT | — | Загрузить назначения контента устройства |
| POST | / | JWT | — | Сохранить назначения контента устройства (пакетно) |
| DELETE | /:id | JWT | — | Удалить назначение контента устройства |
SMS
Базовый путь: /messaging/texting
Управляет провайдерами SMS, групповой отправкой текстовых сообщений и отслеживанием доставки.
| Метод | Путь | Аутентификация | Право | Описание |
|---|---|---|---|---|
| GET | /providers | JWT | — | Загрузить провайдеров SMS церкви (учётные данные скрыты) |
| GET | /status | JWT | — | { enabled } -- есть ли у церкви включённый провайдер SMS. Любой вошедший участник церкви; используется, чтобы показывать опции SMS только тогда, когда текст может быть отправлен |
| GET | /inboundUrl | JWT | texting.send или settings.edit | { url } -- входящий (STOP) webhook-адрес церкви, который нужно вставить в провайдера |
| POST | /inbound/:churchId/:token | Публичный | — | Webhook входящих сообщений провайдера. token -- HMAC от ID церкви. Ответ, состоящий ровно из стоп-слова (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, REVOKE), помечает всех совпадающих людей как optedOut и выключает их allowSms. Возвращает { optedOut: <count> }; другие ответы возвращают { optedOut: 0 } |
| GET | /preview/:groupId | JWT | — | Предпросмотр получателей группового SMS (количество подходящих, отписавшихся и без телефона) |
| GET | /sent | JWT | — | Загрузить все записи отправленных SMS церкви |
| GET | /sent/:id/details | JWT | — | Загрузить отправленное SMS с журналами доставки по каждому получателю |
| POST | /providers | JWT | — | Сохранить провайдеров SMS (пакетно). Шифрует учётные данные API |
| POST | /send | JWT | — | Отправить SMS всем подходящим участникам группы. Тело: { groupId, message }. Поля подстановки ({{firstName}}, {{lastName}}, {{displayName}}, {{churchName}}) подставляются для каждого получателя |
| POST | /sendPerson | JWT | — | Отправить SMS одному человеку. Тело: { personId, phoneNumber, message }. Поля подстановки подставляются, и в журнал записывается итоговый текст |
| DELETE | /providers/:id | JWT | — | Удалить провайдера SMS |
Пример: групповое SMS
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
}
Шаблоны email
Базовый путь: /messaging/emailTemplates
Управляет многократно используемыми шаблонами email и отправкой шаблонных писем группам.
| Метод | Путь | Аутентификация | Право | Описание |
|---|---|---|---|---|
| GET | / | JWT | — | Загрузить все шаблоны email церкви |
| GET | /:id | JWT | — | Загрузить один шаблон email по ID |
| GET | /sendStatus | JWT | groupMembers.edit или tasks.admin | Статус email для групп церкви: { approved, paused, remaining, requested }. Диалог Send Email в B1Admin и действие рабочего процесса Send email используют его, чтобы предупредить, если письма не уйдут |
| POST | /requestApproval | JWT | groupMembers.edit | Попросить поддержку одобрить церковь для email групп (не чаще одного раза в неделю для церкви) |
| GET | /preview/:groupId | JWT | — | Предпросмотр доставки email для группы (количество подходящих получателей, участники без email) |
| POST | / | JWT | — | Создать или обновить шаблоны email (пакетно) |
| POST | /send | JWT | — | Отправить шаблонное письмо всем участникам группы. Тело: { groupId, subject, htmlContent } |
| DELETE | /:id | JWT | — | Удалить шаблон email |
Пример: отправить email группе
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, когда сохраняются потоковые службы.
| Метод | Путь | Аутентификация | Право | Описание |
|---|---|---|---|---|
| POST | / | JWT | — | (устаревшее) Сохранить заблокированные IP (пакетно). Активного клиента нет |
| POST | /clear | JWT | — | Очистить все заблокированные IP для конкретных служб. Тело: [{ serviceId, churchId }] |
Журналы доставки
Базовый путь: /messaging/deliverylogs
Отслеживает статус доставки отправленных сообщений (SMS, push-уведомления, email).
| Метод | Путь | Аутентификация | Право | Описание |
|---|---|---|---|---|
| GET | /content/:contentType/:contentId | JWT | — | Загрузить журналы доставки по типу и ID контента |
| GET | /person/:personId | JWT | — | Загрузить журналы доставки человека. Необязательные ?startDate=&endDate= задают фильтр |
| GET | /recent | JWT | — | Загрузить недавние журналы доставки церкви. Необязательный ?limit= (по умолчанию 100) |
| GET | /:id | JWT | — | Загрузить журнал доставки по ID |
Связанные страницы
- Архитектура реального времени -- протокол WebSocket, подписки на комнаты и единая система доставки
- Web Push-уведомления -- регистрация в браузерном push и доставка
- Эндпоинты участников -- люди, группы, роли и базовая идентичность
- Эндпоинты посещаемости -- учёт служб и посещений
- Аутентификация и права -- вход, JWT, OAuth, модель прав
- Структура модуля -- принципы организации кода