Zum Hauptinhalt springen

Messaging-Endpunkte

Das Messaging-Modul verwaltet Echtzeit-Unterhaltungen, Chat-Nachrichten, Push-Benachrichtigungen, SMS- und E-Mail-Zustellung, WebSocket-Verbindungen, private Nachrichten, Geräteregistrierung und Texting-Anbieter. Es stellt die Kommunikationsschicht bereit, die in allen ChurchApps-Anwendungen sowohl für den Live-Chat im Stream als auch für asynchrone Benachrichtigungen genutzt wird.

Basispfad: /messaging

Unterhaltungen​

Basispfad: /messaging/conversations

MethodePfadAuthBerechtigungBeschreibung
GET/timeline/ids?ids=JWT—Lädt Unterhaltungen anhand kommagetrennter IDs mit erster und letzter Nachricht
GET/messages/:contentType/:contentIdJWT—Lädt Unterhaltungen für einen Inhalt mit paginierten Nachrichten (?page=&limit=)
GET/postsJWT—Ruft Beitrags-Unterhaltungen für die Gruppen des aktuellen Benutzers ab
GET/posts/group/:groupIdJWT—Ruft Beitrags-Unterhaltungen für eine bestimmte Gruppe ab
GET/notes/feed?section=&limit=&before=JWT—Neueste Notizen aller Datensätze für die Seite Notizen im B1 Admin. section ist people, groups, events oder workflows (sonst 400); limit ist standardmäßig 25 (maximal 100); before ist der Cursor der vorherigen Seite. Jede Notiz besteht weiterhin die Regel ihres eigenen Typs (Berechtigung Personen bearbeiten / vertrauliche Notizen, Leiter der Gruppe, Veranstaltungsbetrachter, Betrachter von Workflow-Karten), sodass Aufrufer nur Notizen sehen, die sie öffnen dürften. Der Notiztext wird auf 300 Zeichen gekürzt
GET/current/:churchId/:contentType/:contentIdÖffentlich—Ruft die aktuelle Unterhaltung für einen Inhalt ab oder erstellt sie (entschlüsselt contentId automatisch)
GET/:churchId/:contentType/:contentIdÖffentlich—Lädt Unterhaltungen nach Inhaltstyp und ID
GET/:churchId/:idÖffentlich—Lädt eine einzelne Unterhaltung nach ID
POST/JWT—Erstellt oder aktualisiert Unterhaltungen (Stapel)
POST/startJWT—Startet eine neue Unterhaltung mit einer ersten Kommentarnachricht
DELETE/:churchId/:idJWT—Löscht eine Unterhaltung

Zugriffskontrolle für Personennotizen​

Unterhaltungen mit contentType: "person" (der Reiter Notizen eines Personendatensatzes) oder contentType: "personConfidential" (der Abschnitt Vertrauliche Notizen) sind bei jedem Lese- und Schreibpfad geschützt, auch bei den oben genannten öffentlichen Routen, die für diese Inhaltstypen mit 401 antworten. person erfordert die Berechtigung MembershipApi Personen / Bearbeiten; personConfidential erfordert Personen / Vertrauliche Notizen anzeigen. Bei eingeschränkten API-Schlüsseln deckt people:write beide Aktionen ab (der Benutzer des Schlüssels muss weiterhin die zugrunde liegende Rollenberechtigung besitzen).

Zugriffskontrolle für Gruppen- und Veranstaltungsnotizen​

Zwei weitere Notiz-Inhaltstypen sind auf die gleiche Weise bei jedem Lese- und Schreibpfad geschützt (einschließlich der oben genannten öffentlichen Routen) und stehen nie für anonyme Beiträge offen:

  • groupNote (contentId = Gruppen-ID) -- der Feed Leiternotizen einer Gruppe. Nur die Leiter dieser Gruppe (leaderGroupIds im JWT) können lesen oder schreiben. Keine Mitarbeiterberechtigung gewährt Zugriff, auch nicht content.edit und die Berechtigungen für Gruppenmitgliedschaften.
  • eventNote (contentId = Veranstaltungs-ID) -- die Notizen zu einer Kalenderveranstaltung. Mitarbeiter mit content.edit oder Kalender / Administrator können immer lesen und schreiben. Ansonsten richtet sich der Zugriff nach notesViewRole (Lesen) und notesPostRole (Schreiben) der Veranstaltung: staff (der Standard, wenn das Feld null ist) lässt niemand anderen zu, leaders lässt Leiter der Gruppe der Veranstaltung zu, und members lässt Mitglieder und Leiter der Veranstaltungsgruppe zu. Eine Veranstaltung ohne groupId ist nur für Mitarbeiter zugänglich.

Zugriffskontrolle für Notizen zu Workflow-Karten​

Unterhaltungen mit contentType: "workflowCard" (die Notizen zu einer Workflow-Karte, wobei contentId die Aufgaben-ID der Karte ist) sind nur für Personen lesbar und beschreibbar, die diese Karte öffnen dürfen: ein Benutzer mit der Berechtigung DoingApi Aufgaben / Anzeigen oder die Person bzw. Gruppe, der die Karte zugewiesen, von der sie erstellt oder für die sie bestimmt ist. Alle anderen erhalten bei jedem Lesepfad 401, einschließlich der oben genannten öffentlichen Routen. Die Unterhaltung einer Karte wird über die Karte selbst mit POST /doing/tasks/:id/conversation angehängt (Body { "conversationId": "..." }; die zuerst angehängte Unterhaltung gewinnt), was die Bearbeiter der Karte und ihr Verantwortlicher aufrufen dürfen.

Beispiel: Eine Unterhaltung starten​

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"
}

Nachrichten​

Basispfad: /messaging/messages

MethodePfadAuthBerechtigungBeschreibung
GET/conversation/:conversationIdJWT—Lädt alle Nachrichten einer Unterhaltung
GET/catchup/:churchId/:conversationIdÖffentlich—Lädt alle Nachrichten einer Unterhaltung (öffentlicher Nachholmechanismus für Live-Chat)
GET/:churchId/:idÖffentlich—Lädt eine einzelne Nachricht nach ID
POST/JWT—Speichert Nachrichten (Stapel). Sendet Echtzeit-Updates und löst Benachrichtigungen aus. Das Aktualisieren einer bestehenden Nachricht erfordert, dass man ihr Autor ist oder content.edit besitzt; der gespeicherte Autor kann nie neu zugewiesen werden
POST/sendÖffentlich—Sendet Nachrichten (Stapel, öffentlich). Sendet Echtzeit-Updates über WebSocket und löst Benachrichtigungen aus
POST/setCalloutJWT—(veraltet) Sendet eine Hinweisnachricht in Echtzeit. Kein aktiver Client; der Live-Stream-Chat zeigt Hinweise nicht mehr an
DELETE/:churchId/:idJWT—Löscht eine Nachricht und sendet die Löschung in Echtzeit. Siehe Moderation von Nachrichten

Moderation von Nachrichten​

Das Löschen einer Nachricht ist erlaubt für:

  • den Autor der Nachricht;
  • Mitarbeiter mit content.edit (überall in der Gemeinde);
  • Gruppenleiter bei Unterhaltungen mit contentType group oder groupAnnouncement, deren contentId eine Gruppe ist, die sie leiten (leaderGroupIds im JWT).

Unterhaltungen über Personennotizen (person / personConfidential) werden nie von Leitern moderiert -- sie folgen stattdessen den Notizberechtigungen (people.edit, people.viewConfidentialNotes).

Leiter dürfen nur löschen, nicht bearbeiten: Das Umschreiben der Nachricht eines anderen Mitglieds bleibt auf den Autor und Mitarbeiter mit content.edit beschränkt.

Beispiel: Eine Nachricht senden​

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"
}
]

Private Nachrichten​

Basispfad: /messaging/privatemessages

MethodePfadAuthBerechtigungBeschreibung
GET/JWT—Lädt alle privaten Nachrichten des aktuellen Benutzers (inklusive letzter Nachricht je Unterhaltung; markiert alle als gelesen)
GET/existing/:personIdJWT—Findet eine bestehende private Unterhaltung mit einer bestimmten Person
GET/:idJWT—Lädt eine private Nachricht nach ID (löscht die Benachrichtigung, wenn sie an den aktuellen Benutzer adressiert ist)
POST/JWT—Sendet private Nachrichten (Stapel). Löst eine Push-Benachrichtigung an den Empfänger aus

Benachrichtigungen​

Basispfad: /messaging/notifications

MethodePfadAuthBerechtigungBeschreibung
GET/unreadCountJWT—Ruft die Anzahl ungelesener Benachrichtigungen des aktuellen Benutzers ab
GET/myJWT—Lädt alle Benachrichtigungen des aktuellen Benutzers (markiert alle als gelesen)
GET/tmpEmailÖffentlich—Löst die tägliche E-Mail-Zusammenfassung der Benachrichtigungen aus (Debug-/Cron-Endpunkt)
GET/:churchId/person/:personIdJWT—Lädt Benachrichtigungen für eine bestimmte Person
GET/:churchId/:idJWT—Lädt eine Benachrichtigung nach ID
POST/JWT—Erstellt oder aktualisiert Benachrichtigungen (Stapel)
POST/createJWT—Erstellt Benachrichtigungen für mehrere Personen. Body: { peopleIds, contentType, contentId, message, link }
POST/markRead/:churchId/:personIdJWT—Markiert alle Benachrichtigungen einer Person als gelesen
POST/sendTestJWT—Sendet eine Test-Push-Benachrichtigung. Body: { personId, title }
POST/pingÖffentlich—Erstellt eine Benachrichtigung aus einem externen Auslöser. Body: { personId, churchId, contentType, contentId, message, triggeredByPersonId }
DELETE/:churchId/:idJWT—Löscht eine Benachrichtigung
GET/groupPreview/:groupIdJWTgroupMembers.editZählt, wie viele Mitglieder einer Gruppe ein Push erreichen würde
GET/churchPreviewJWTcontent.editZählt, wie viele Personen ein Push an alle mit der App erreichen würde
POST/group/sendJWTgroupMembers.editSendet sofort ein Push an die Mitglieder einer Gruppe

Beispiel: Benachrichtigungen erstellen​

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"
}

Geplante Benachrichtigungen​

Basispfad: /messaging/scheduledNotifications

Im Voraus geplante Pushes. audience ist church (alle mit der App; erfordert content.edit) oder group (erfordert groupMembers.edit und eine groupId). Der Titel ist auf 80 Zeichen begrenzt, die Nachricht auf 240. Eine fällige Zeile wird vom Minuten-Timer gesendet.

MethodePfadAuthBerechtigungBeschreibung
GET/JWTgroupMembers.edit oder content.editListet geplante und kürzlich versendete Benachrichtigungen der Gemeinde auf
POST/JWTje nach ZielgruppeErstellt eine geplante Benachrichtigung oder aktualisiert eine, wenn id gesetzt ist. Body: { id?, audience, groupId?, title, message, link?, imageUrl?, sendAt }. Die Aktualisierung einer nicht mehr ausstehenden gibt 409 zurück
POST/:id/sendNowJWTje nach ZielgruppeSendet eine ausstehende Benachrichtigung sofort. Gibt 409 zurück, wenn sie bereits gesendet, storniert wurde oder gerade gesendet wird
DELETE/:idJWTje nach ZielgruppeStorniert eine ausstehende Benachrichtigung oder entfernt eine gesendete, fehlgeschlagene oder stornierte aus der Liste. Gibt 409 zurück, während sie gesendet wird
DELETE/JWTgroupMembers.edit oder content.editEntfernt alle gesendeten, fehlgeschlagenen und stornierten Benachrichtigungen für die Zielgruppen, an die der Benutzer senden darf. Gibt { deleted } zurück

Benachrichtigungseinstellungen​

Basispfad: /messaging/notificationpreferences

MethodePfadAuthBerechtigungBeschreibung
GET/categoriesJWT—Listet Benachrichtigungskategorien mit ihren Standard- und erlaubten Kanälen auf
GET/myJWT—Lädt die Benachrichtigungseinstellungen des aktuellen Benutzers (legt Standardwerte automatisch an, falls keine existieren)
POST/JWT—Speichert die Einstellungen des aktuellen Benutzers. Body: beliebige der Felder allowPush, allowSms, emailFrequency, masterMute, quietHoursStart, quietHoursEnd, timeZone, maxPushPerDay sowie optional overrides: [{ categoryKey, channel, optedIn }] (channel kann push, email, in_app oder sms sein; gesperrte Kategorien werden ignoriert). allowSms ist die Zustimmung des Mitglieds zu Texterinnerungen. Ein veralteter Body als Zeilenliste wird weiterhin akzeptiert

Verbindungen​

Basispfad: /messaging/connections

Verwaltet WebSocket-/Echtzeitverbindungen für Chat, Gruppenunterhaltungen, private Nachrichten und Live-Streaming. Das vollständige Protokoll findest du unter Echtzeit-Architektur.

MethodePfadAuthBerechtigungBeschreibung
GET/:churchId/:conversationIdÖffentlich—Lädt alle Verbindungen einer Unterhaltung
POST/Öffentlich—Registriert Verbindungen (Stapel). Löst eine Anwesenheitsmeldung für die Unterhaltung aus. Body-Einträge: { churchId, conversationId, socketId, displayName?, personId? }
POST/setNameÖffentlich—Aktualisiert den Anzeigenamen einer Verbindung anhand der Socket-ID. Body: { socketId, name }
DELETE/:churchId/:conversationId/:socketIdÖffentlich—Entfernt eine Verbindung aus einer Unterhaltung. Löst eine Anwesenheitsmeldung aus
POST/tmpSendAlertÖffentlich—Sendet eine Benachrichtigung an die Verbindungen einer Person. Body: { churchId, personId }

Geräte​

Basispfad: /messaging/devices

Verwaltet die Geräteregistrierung für Push-Benachrichtigungen und die Kopplung von Inhalten (z. B. die Lessons-App auf TV-Bildschirmen).

MethodePfadAuthBerechtigungBeschreibung
POST/enrollJWT—Registriert oder aktualisiert ein Gerät (Push-Registrierung auf dem Mobilgerät). Gleicht anhand des FCM-Tokens oder der Geräte-ID ab
POST/enrollAnonÖffentlich—Registriert ein anonymes Gerät und erzeugt einen 4-stelligen Kopplungscode
POST/Öffentlich—Speichert Geräte (Stapel)
GET/pair/:pairingCodeJWT—Koppelt ein Gerät mit seinem Kopplungscode. Optional ?contentType=&contentId=, um Inhalte zuzuweisen
GET/status/:deviceIdÖffentlich—Prüft den Kopplungsstatus eines Geräts
GET/:churchIdJWT—Lädt alle Geräte einer Gemeinde
GET/:churchId/person/:personIdJWT—Lädt alle Geräte einer Person
GET/:churchId/:idJWT—Lädt ein Gerät nach ID
DELETE/:churchId/:idJWT—Löscht ein Gerät

Beispiel: Ein Gerät registrieren​

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"
}

Geräteinhalte​

Basispfad: /messaging/devicecontents

Verwaltet Inhaltszuweisungen für gekoppelte Geräte (z. B. welche Lektion auf einem TV angezeigt wird).

MethodePfadAuthBerechtigungBeschreibung
GET/deviceId/:deviceIdJWT—Lädt die Inhaltszuweisungen eines Geräts
POST/JWT—Speichert Inhaltszuweisungen von Geräten (Stapel)
DELETE/:idJWT—Löscht eine Inhaltszuweisung eines Geräts

Texting​

Basispfad: /messaging/texting

Verwaltet SMS-Texting-Anbieter, den Versand von Gruppennachrichten per SMS und die Zustellverfolgung.

MethodePfadAuthBerechtigungBeschreibung
GET/providersJWT—Lädt die Texting-Anbieter der Gemeinde (Zugangsdaten sind maskiert)
GET/statusJWT—{ enabled } -- ob die Gemeinde einen aktivierten Texting-Anbieter hat. Jeder angemeldete Benutzer der Gemeinde; dient dazu, Text-Optionen nur anzuzeigen, wenn SMS versendet werden können
GET/inboundUrlJWTtexting.send oder settings.edit{ url } -- die eingehende Webhook-URL (STOP) der Gemeinde, die beim Anbieter eingetragen wird
POST/inbound/:churchId/:tokenÖffentlich—Webhook für eingehende Nachrichten des Anbieters. token ist ein HMAC der Gemeinde-ID. Eine Antwort, die genau einem Stopp-Wort entspricht (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, REVOKE), markiert jede passende Person als optedOut und schaltet deren allowSms aus. Gibt { optedOut: <count> } zurück; andere Antworten geben { optedOut: 0 } zurück
GET/preview/:groupIdJWT—Zeigt Empfänger einer Gruppen-SMS in der Vorschau (Anzahl berechtigter, abgemeldeter und Personen ohne Telefonnummer)
GET/sentJWT—Lädt alle versendeten SMS-Datensätze der Gemeinde
GET/sent/:id/detailsJWT—Lädt eine versendete SMS mit Zustellprotokollen je Empfänger
POST/providersJWT—Speichert Texting-Anbieter (Stapel). Verschlüsselt API-Zugangsdaten
POST/sendJWT—Sendet eine SMS an alle berechtigten Mitglieder einer Gruppe. Body: { groupId, message }. Platzhalterfelder ({{firstName}}, {{lastName}}, {{displayName}}, {{churchName}}) werden pro Empfänger aufgelöst
POST/sendPersonJWT—Sendet eine SMS an eine einzelne Person. Body: { personId, phoneNumber, message }. Platzhalterfelder werden aufgelöst, und der aufgelöste Text wird protokolliert
DELETE/providers/:idJWT—Löscht einen Texting-Anbieter

Beispiel: Gruppen-SMS senden​

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
}

E-Mail-Vorlagen​

Basispfad: /messaging/emailTemplates

Verwaltet wiederverwendbare E-Mail-Vorlagen und das Versenden vorlagenbasierter E-Mails an Gruppen.

MethodePfadAuthBerechtigungBeschreibung
GET/JWT—Lädt alle E-Mail-Vorlagen der Gemeinde
GET/:idJWT—Lädt eine E-Mail-Vorlage nach ID
GET/sendStatusJWTgroupMembers.edit oder tasks.adminDer E-Mail-Status der Gruppen der Gemeinde: { approved, paused, remaining, requested }. Der Dialog E-Mail senden im B1Admin und die Workflow-Aktion E-Mail senden nutzen ihn, um zu warnen, wenn keine E-Mails versendet werden
POST/requestApprovalJWTgroupMembers.editBittet den Support, die Gemeinde für Gruppen-E-Mails freizuschalten (höchstens einmal pro Gemeinde und Woche)
GET/preview/:groupIdJWT—Zeigt die E-Mail-Zustellung für eine Gruppe in der Vorschau (Anzahl berechtigter Empfänger, Mitglieder ohne E-Mail)
POST/JWT—Erstellt oder aktualisiert E-Mail-Vorlagen (Stapel)
POST/sendJWT—Sendet eine vorlagenbasierte E-Mail an alle Mitglieder einer Gruppe. Body: { groupId, subject, htmlContent }
DELETE/:idJWT—Löscht eine E-Mail-Vorlage

Beispiel: E-Mail an eine Gruppe senden​

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
}

Unterstützte Platzhalterfelder: {{firstName}}, {{lastName}}, {{displayName}}, {{email}}, {{churchName}}

Gesperrte IP-Adressen​

Basispfad: /messaging/blockedips

(veraltet) IP-Sperre für den Live-Stream-Chat. Der B1App-Client ruft POST / nicht mehr auf -- die IP-Sperre wurde bei der Migration zur einheitlichen Zustellung entfernt. Die Route /clear wird weiterhin server-zu-server von StreamingServiceController aufgerufen, wenn Streaming-Gottesdienste gespeichert werden.

MethodePfadAuthBerechtigungBeschreibung
POST/JWT—(veraltet) Speichert gesperrte IPs (Stapel). Kein aktiver Client
POST/clearJWT—Entfernt alle gesperrten IPs für bestimmte Gottesdienste. Body: [{ serviceId, churchId }]

Zustellprotokolle​

Basispfad: /messaging/deliverylogs

Verfolgt den Zustellstatus gesendeter Nachrichten (SMS, Push-Benachrichtigungen, E-Mail).

MethodePfadAuthBerechtigungBeschreibung
GET/content/:contentType/:contentIdJWT—Lädt Zustellprotokolle nach Inhaltstyp und ID
GET/person/:personIdJWT—Lädt Zustellprotokolle einer Person. Optional ?startDate=&endDate= als Filter
GET/recentJWT—Lädt die neuesten Zustellprotokolle der Gemeinde. Optional ?limit= (Standard 100)
GET/:idJWT—Lädt ein Zustellprotokoll nach ID