Перейти к основному содержимому

Эндпоинты обмена сообщениями

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

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

Переписки​

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

МетодПутьАутентификацияПравоОписание
GET/timeline/ids?ids=JWT—Загрузить переписки по ID через запятую с первым и последним сообщениями
GET/messages/:contentType/:contentIdJWT—Загрузить переписки для контента с постраничными сообщениями (?page=&limit=)
GET/postsJWT—Получить переписки-посты для групп текущего пользователя
GET/posts/group/:groupIdJWT—Получить переписки-посты для конкретной группы
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/startJWT—Начать новую переписку с первым комментарием
DELETE/:churchId/:idJWT—Удалить переписку

Контроль доступа к заметкам о людях​

Переписки с 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/:conversationIdJWT—Загрузить все сообщения переписки
GET/catchup/:churchId/:conversationIdПубличный—Загрузить все сообщения переписки (публичная догрузка для чата в реальном времени)
GET/:churchId/:idПубличный—Загрузить одно сообщение по ID
POST/JWT—Сохранить сообщения (пакетно). Отправляет обновления в реальном времени и запускает уведомления. Чтобы изменить существующее сообщение, нужно быть его автором или иметь content.edit; сохранённый автор никогда не может быть переназначен
POST/sendПубличный—Отправить сообщения (пакетно, публично). Отправляет обновления в реальном времени через WebSocket и запускает уведомления
POST/setCalloutJWT—(устаревшее) Широковещательно отправить сообщение-выноску в реальном времени. Активного клиента нет; чат прямых трансляций больше не отображает выноски
DELETE/:churchId/:idJWT—Удалить сообщение и разослать удаление в реальном времени. См. Модерация сообщений

Модерация сообщений​

Удалить сообщение могут:

  • автор сообщения;
  • сотрудники с content.edit (в любом месте церкви);
  • руководители групп -- для переписок с contentType group или 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/:personIdJWT—Найти существующую личную переписку с конкретным человеком
GET/:idJWT—Загрузить личное сообщение по ID (очищает уведомление, если оно адресовано текущему пользователю)
POST/JWT—Отправить личные сообщения (пакетно). Запускает push-уведомление получателю

Уведомления​

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

МетодПутьАутентификацияПравоОписание
GET/unreadCountJWT—Получить количество непрочитанных уведомлений текущего пользователя
GET/myJWT—Загрузить все уведомления текущего пользователя (помечает все как прочитанные)
GET/tmpEmailПубличный—Запустить ежедневную email-сводку уведомлений (отладочный/cron-эндпоинт)
GET/:churchId/person/:personIdJWT—Загрузить уведомления конкретного человека
GET/:churchId/:idJWT—Загрузить уведомление по ID
POST/JWT—Создать или обновить уведомления (пакетно)
POST/createJWT—Создать уведомления для нескольких людей. Тело: { peopleIds, contentType, contentId, message, link }
POST/markRead/:churchId/:personIdJWT—Отметить все уведомления человека как прочитанные
POST/sendTestJWT—Отправить тестовое push-уведомление. Тело: { personId, title }
POST/pingПубличный—Создать уведомление из внешнего триггера. Тело: { personId, churchId, contentType, contentId, message, triggeredByPersonId }
DELETE/:churchId/:idJWT—Удалить уведомление
GET/groupPreview/:groupIdJWTgroupMembers.editПосчитать, сколько участников группы получит push
GET/churchPreviewJWTcontent.editПосчитать, сколько людей получит push всем, у кого есть приложение
POST/group/sendJWTgroupMembers.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/JWTgroupMembers.edit или content.editСписок запланированных и недавних уведомлений церкви
POST/JWTпо аудиторииСоздать запланированное уведомление или обновить его, если задан id. Тело: { id?, audience, groupId?, title, message, link?, imageUrl?, sendAt }. Обновление уведомления, которое уже не ожидает отправки, возвращает 409
POST/:id/sendNowJWTпо аудиторииОтправить ожидающее уведомление сейчас. Возвращает 409, если оно уже отправлено, отменено или отправляется
DELETE/:idJWTпо аудиторииОтменить ожидающее уведомление или убрать из списка отправленное, неудачное или отменённое. Возвращает 409, пока оно отправляется
DELETE/JWTgroupMembers.edit или content.editУдалить все отправленные, неудачные и отменённые уведомления для аудиторий, которым может отправлять пользователь. Возвращает { deleted }

Настройки уведомлений​

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

МетодПутьАутентификацияПравоОписание
GET/categoriesJWT—Список категорий уведомлений с их каналами по умолчанию и допустимыми каналами
GET/myJWT—Загрузить настройки уведомлений текущего пользователя (создаёт значения по умолчанию, если их нет)
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/enrollJWT—Зарегистрировать или обновить устройство (регистрация push в мобильном приложении). Совпадение по токену FCM или ID устройства
POST/enrollAnonПубличный—Зарегистрировать анонимное устройство и создать 4-символьный код сопряжения
POST/Публичный—Сохранить устройства (пакетно)
GET/pair/:pairingCodeJWT—Сопрячь устройство по коду сопряжения. Необязательные ?contentType=&contentId= назначают контент
GET/status/:deviceIdПубличный—Проверить статус сопряжения устройства
GET/:churchIdJWT—Загрузить все устройства церкви
GET/:churchId/person/:personIdJWT—Загрузить все устройства человека
GET/:churchId/:idJWT—Загрузить устройство по ID
DELETE/:churchId/:idJWT—Удалить устройство

Пример: зарегистрировать устройство​

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/:deviceIdJWT—Загрузить назначения контента устройства
POST/JWT—Сохранить назначения контента устройства (пакетно)
DELETE/:idJWT—Удалить назначение контента устройства

SMS​

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

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

МетодПутьАутентификацияПравоОписание
GET/providersJWT—Загрузить провайдеров SMS церкви (учётные данные скрыты)
GET/statusJWT—{ enabled } -- есть ли у церкви включённый провайдер SMS. Любой вошедший участник церкви; используется, чтобы показывать опции SMS только тогда, когда текст может быть отправлен
GET/inboundUrlJWTtexting.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/:groupIdJWT—Предпросмотр получателей группового SMS (количество подходящих, отписавшихся и без телефона)
GET/sentJWT—Загрузить все записи отправленных SMS церкви
GET/sent/:id/detailsJWT—Загрузить отправленное SMS с журналами доставки по каждому получателю
POST/providersJWT—Сохранить провайдеров SMS (пакетно). Шифрует учётные данные API
POST/sendJWT—Отправить SMS всем подходящим участникам группы. Тело: { groupId, message }. Поля подстановки ({{firstName}}, {{lastName}}, {{displayName}}, {{churchName}}) подставляются для каждого получателя
POST/sendPersonJWT—Отправить SMS одному человеку. Тело: { personId, phoneNumber, message }. Поля подстановки подставляются, и в журнал записывается итоговый текст
DELETE/providers/:idJWT—Удалить провайдера 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/:idJWT—Загрузить один шаблон email по ID
GET/sendStatusJWTgroupMembers.edit или tasks.adminСтатус email для групп церкви: { approved, paused, remaining, requested }. Диалог Send Email в B1Admin и действие рабочего процесса Send email используют его, чтобы предупредить, если письма не уйдут
POST/requestApprovalJWTgroupMembers.editПопросить поддержку одобрить церковь для email групп (не чаще одного раза в неделю для церкви)
GET/preview/:groupIdJWT—Предпросмотр доставки email для группы (количество подходящих получателей, участники без email)
POST/JWT—Создать или обновить шаблоны email (пакетно)
POST/sendJWT—Отправить шаблонное письмо всем участникам группы. Тело: { groupId, subject, htmlContent }
DELETE/:idJWT—Удалить шаблон 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/clearJWT—Очистить все заблокированные IP для конкретных служб. Тело: [{ serviceId, churchId }]

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

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

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

МетодПутьАутентификацияПравоОписание
GET/content/:contentType/:contentIdJWT—Загрузить журналы доставки по типу и ID контента
GET/person/:personIdJWT—Загрузить журналы доставки человека. Необязательные ?startDate=&endDate= задают фильтр
GET/recentJWT—Загрузить недавние журналы доставки церкви. Необязательный ?limit= (по умолчанию 100)
GET/:idJWT—Загрузить журнал доставки по ID