Zum Hauptinhalt springen

Messaging-Endpunkte

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

Basispfad: /messaging

Konversationen​

Basispfad: /messaging/conversations

MethodePfadAuthBerechtigungBeschreibung
GET/timeline/ids?ids=JWT—Konversationen anhand kommagetrennter IDs laden, mit erster und letzter Nachricht
GET/messages/:contentType/:contentIdJWT—Konversationen für Inhalte mit paginierten Nachrichten laden (?page=&limit=)
GET/postsJWT—Konversationen vom Typ Beitrag für die Gruppen des aktuellen Benutzers abrufen
GET/posts/group/:groupIdJWT—Konversationen vom Typ Beitrag für eine bestimmte Gruppe abrufen
GET/notes/feed?section=&limit=&before=JWT—Neueste Notizen aus allen Datensätzen für die Notizenseite von B1 Admin. section ist people, groups, events oder workflows (sonst 400); limit ist standardmäßig 25 (max. 100); before ist der Cursor der vorherigen Seite. Jede Notiz unterliegt weiterhin der Regel ihres Typs (Berechtigung „People Edit“ bzw. vertrauliche Notizen, Leitende der Gruppe, Veranstaltungsbetrachter, Betrachter von Workflow-Karten), sodass Aufrufer nur Notizen sehen, die sie auch öffnen könnten. Der Notiztext wird nach 300 Zeichen gekürzt
GET/current/:churchId/:contentType/:contentIdÖffentlich—Aktuelle Konversation für Inhalte abrufen oder erstellen (entschlüsselt contentId automatisch)
GET/:churchId/:contentType/:contentIdÖffentlich—Konversationen nach Inhaltstyp und ID laden
GET/:churchId/:idÖffentlich—Eine einzelne Konversation anhand der ID laden
POST/JWT—Konversationen erstellen oder aktualisieren (Stapelverarbeitung)
POST/startJWT—Eine neue Konversation mit einer ersten Kommentarnachricht starten
DELETE/:churchId/:idJWT—Eine Konversation löschen

Zugriffskontrolle für Personennotizen​

Konversationen mit contentType: "person" (der Tab „Notizen“ eines Personendatensatzes) oder contentType: "personConfidential" (der Bereich „Vertrauliche Notizen“) sind bei jedem Lese- und Schreibzugriff geschützt, auch über die oben aufgeführten öffentlichen Routen, die für diese Inhaltstypen 401 zurückgeben. person erfordert die MembershipApi-Berechtigung People / Edit, personConfidential erfordert People / View Confidential Notes. Bei API-Schlüsseln mit eingeschränktem Umfang umfasst people:write beide Aktionen (der Benutzer des Schlüssels muss die zugrunde liegende Rollenberechtigung weiterhin besitzen).

Zugriffskontrolle für Gruppen- und Veranstaltungsnotizen​

Zwei weitere Notiztypen sind auf die gleiche Weise geschützt, bei jedem Lese- und Schreibzugriff (auch über die oben genannten öffentlichen Routen), und sind niemals für anonymes Posten offen:

  • groupNote (contentId = Gruppen-ID) -- der Feed Leiternotizen einer Gruppe. Nur die Leitenden dieser Gruppe (leaderGroupIds im JWT) können lesen oder posten. Keine Mitarbeiterberechtigung gewährt Zugriff, auch nicht content.edit oder die Berechtigungen zur Gruppenmitgliedschaft.
  • eventNote (contentId = Veranstaltungs-ID) -- die Notizen zu einem Kalendereintrag. Mitarbeitende mit content.edit oder Calendars / Admin können immer lesen und posten. Ansonsten richtet sich der Zugriff nach der notesViewRole (Lesen) und notesPostRole (Posten) der Veranstaltung: staff (Standard, wenn das Feld null ist) erlaubt sonst niemandem Zugriff, leaders erlaubt den Leitenden der Veranstaltungsgruppe, und members erlaubt den Mitgliedern und Leitenden der Veranstaltungsgruppe. Eine Veranstaltung ohne groupId ist nur für Mitarbeitende zugänglich.

Zugriffskontrolle für Notizen auf Workflow-Karten​

Konversationen 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: Benutzer mit der DoingApi-Berechtigung Tasks / View sowie die Person oder Gruppe, der die Karte zugewiesen ist, von der sie erstellt wurde oder die sie betrifft. Alle anderen erhalten bei jedem Lesezugriff 401, auch über die oben genannten öffentlichen Routen. Die Konversation einer Karte wird über die Karte selbst mit POST /doing/tasks/:id/conversation (Body { "conversationId": "..." }; die zuerst angehängte Konversation gewinnt) angehängt, was die Bearbeitenden der Karte und ihre zugewiesene Person aufrufen können.

Beispiel: Eine Konversation 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—Alle Nachrichten einer Konversation laden
GET/catchup/:churchId/:conversationIdÖffentlich—Alle Nachrichten einer Konversation laden (öffentlicher Catch-up für Live-Chat)
GET/:churchId/:idÖffentlich—Eine einzelne Nachricht anhand der ID laden
POST/JWT—Nachrichten speichern (Stapelverarbeitung). Sendet Echtzeit-Aktualisierungen und löst Benachrichtigungen aus. Zum Ändern einer bestehenden Nachricht muss man deren Autor sein oder content.edit besitzen; der gespeicherte Autor kann niemals neu zugewiesen werden
POST/sendÖffentlich—Nachrichten senden (Stapelverarbeitung, öffentlich). Sendet Echtzeit-Aktualisierungen über WebSocket und löst Benachrichtigungen aus
POST/setCalloutJWT—(veraltet) Eine Hervorhebungsnachricht in Echtzeit senden. Kein aktiver Client; der Live-Stream-Chat zeigt Hervorhebungen nicht mehr an
DELETE/:churchId/:idJWT—Eine Nachricht löschen und die Löschung in Echtzeit übertragen. Siehe Moderation von Nachrichten

Moderation von Nachrichten​

Eine Nachricht darf gelöscht werden von:

  • dem Autor der Nachricht;
  • Mitarbeitenden mit content.edit (in der gesamten Gemeinde);
  • Gruppenleitenden für Konversationen mit contentType group oder groupAnnouncement, deren contentId eine Gruppe ist, die sie leiten (leaderGroupIds im JWT).

Konversationen zu Personennotizen (person / personConfidential) werden nie von Leitenden moderiert. Dafür gelten stattdessen die Notizberechtigungen (people.edit, people.viewConfidentialNotes).

Leitende dürfen nur löschen, nicht bearbeiten: Das Umschreiben der Nachricht eines anderen Mitglieds bleibt auf den Autor und Mitarbeitende 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—Alle privaten Nachrichten des aktuellen Benutzers laden (enthält die letzte Nachricht pro Konversation und markiert alle als gelesen)
GET/existing/:personIdJWT—Eine bestehende private Konversation mit einer bestimmten Person finden
GET/:idJWT—Eine private Nachricht anhand der ID laden (löscht die Benachrichtigung, wenn sie an den aktuellen Benutzer gerichtet ist)
POST/JWT—Private Nachrichten senden (Stapelverarbeitung). Löst eine Push-Benachrichtigung beim Empfänger aus

Benachrichtigungen​

Basispfad: /messaging/notifications

MethodePfadAuthBerechtigungBeschreibung
GET/unreadCountJWT—Anzahl ungelesener Benachrichtigungen des aktuellen Benutzers abrufen
GET/myJWT—Alle Benachrichtigungen des aktuellen Benutzers laden (markiert alle als gelesen)
GET/tmpEmailÖffentlich—Die tägliche E-Mail-Übersicht der Benachrichtigungen auslösen (Debug-/Cron-Endpunkt)
GET/:churchId/person/:personIdJWT—Benachrichtigungen einer bestimmten Person laden
GET/:churchId/:idJWT—Eine Benachrichtigung anhand der ID laden
POST/JWT—Benachrichtigungen erstellen oder aktualisieren (Stapelverarbeitung)
POST/createJWT—Benachrichtigungen für mehrere Personen erstellen. Body: { peopleIds, contentType, contentId, message, link }
POST/markRead/:churchId/:personIdJWT—Alle Benachrichtigungen einer Person als gelesen markieren
POST/sendTestJWT—Eine Test-Push-Benachrichtigung senden. Body: { personId, title }
POST/pingÖffentlich—Eine Benachrichtigung durch einen externen Auslöser erstellen. Body: { personId, churchId, contentType, contentId, message, triggeredByPersonId }
DELETE/:churchId/:idJWT—Eine Benachrichtigung löschen

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

Benachrichtigungseinstellungen​

Basispfad: /messaging/notificationpreferences

MethodePfadAuthBerechtigungBeschreibung
GET/categoriesJWT—Benachrichtigungskategorien mit ihren Standard- und erlaubten Kanälen auflisten
GET/myJWT—Benachrichtigungseinstellungen des aktuellen Benutzers laden (legt Standardwerte automatisch an, falls keine vorhanden sind)
POST/JWT—Die Einstellungen des aktuellen Benutzers speichern. Body: beliebige der Felder allowPush, allowSms, emailFrequency, masterMute, quietHoursStart, quietHoursEnd, timeZone, maxPushPerDay, dazu 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 Textnachricht-Erinnerungen. Ein veraltetes Body-Format als Array von Zeilen wird weiterhin akzeptiert

Verbindungen​

Basispfad: /messaging/connections

Verwaltet WebSocket-/Echtzeitverbindungen für Chats, Gruppenkonversationen, private Nachrichten und Live-Streaming. Siehe Echtzeit-Architektur für das vollständige Protokoll.

MethodePfadAuthBerechtigungBeschreibung
GET/:churchId/:conversationIdÖffentlich—Alle Verbindungen einer Konversation laden
POST/Öffentlich—Verbindungen registrieren (Stapelverarbeitung). Löst eine Anwesenheitsübertragung für die Konversation aus. Elemente im Body: { churchId, conversationId, socketId, displayName?, personId? }
POST/setNameÖffentlich—Den Anzeigenamen einer Verbindung anhand der Socket-ID aktualisieren. Body: { socketId, name }
DELETE/:churchId/:conversationId/:socketIdÖffentlich—Eine Verbindung aus einer Konversation entfernen. Löst eine Anwesenheitsübertragung aus
POST/tmpSendAlertÖffentlich—Eine Benachrichtigung an die Verbindungen einer Person senden. Body: { churchId, personId }

Geräte​

Basispfad: /messaging/devices

Verwaltet die Geräteregistrierung für Push-Benachrichtigungen und die Inhaltskopplung (z. B. Lessons-App auf TV-Displays).

MethodePfadAuthBerechtigungBeschreibung
POST/enrollJWT—Ein Gerät registrieren oder aktualisieren (Registrierung für mobile Push-Benachrichtigungen). Abgleich über FCM-Token oder Geräte-ID
POST/enrollAnonÖffentlich—Ein anonymes Gerät registrieren und einen 4-stelligen Kopplungscode erzeugen
POST/Öffentlich—Geräte speichern (Stapelverarbeitung)
GET/pair/:pairingCodeJWT—Ein Gerät mit seinem Kopplungscode koppeln. Optional ?contentType=&contentId=, um Inhalte zuzuweisen
GET/status/:deviceIdÖffentlich—Den Kopplungsstatus eines Geräts prüfen
GET/:churchIdJWT—Alle Geräte einer Gemeinde laden
GET/:churchId/person/:personIdJWT—Alle Geräte einer Person laden
GET/:churchId/:idJWT—Ein Gerät anhand der ID laden
DELETE/:churchId/:idJWT—Ein Gerät löschen

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 Fernseher angezeigt wird).

MethodePfadAuthBerechtigungBeschreibung
GET/deviceId/:deviceIdJWT—Inhaltszuweisungen eines Geräts laden
POST/JWT—Inhaltszuweisungen für Geräte speichern (Stapelverarbeitung)
DELETE/:idJWT—Eine Inhaltszuweisung für ein Gerät löschen

Texting​

Basispfad: /messaging/texting

Verwaltet SMS-Anbieter, Gruppen-Textnachrichten und die Zustellverfolgung.

MethodePfadAuthBerechtigungBeschreibung
GET/providersJWT—Texting-Anbieter der Gemeinde laden (Zugangsdaten sind maskiert)
GET/statusJWT—{ enabled } – ob die Gemeinde einen aktivierten Texting-Anbieter hat. Jede angemeldete Person der Gemeinde kann dies abrufen; es dient dazu, die Optionen Text nur dann anzuzeigen, wenn Textnachrichten gesendet werden können
GET/inboundUrlJWTtexting.send oder settings.edit{ url } – die eingehende (STOP-)Webhook-URL der Gemeinde, die beim Anbieter eingetragen wird
POST/inbound/:churchId/:tokenÖffentlich—Webhook des Anbieters für eingehende Nachrichten. token ist ein HMAC der Gemeinde-ID. Eine Antwort, die genau einem Stoppwort entspricht (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, REVOKE), markiert jede passende Person als optedOut und deaktiviert deren allowSms. Gibt { optedOut: <count> } zurück; andere Antworten geben { optedOut: 0 } zurück
GET/preview/:groupIdJWT—Empfänger einer Gruppen-Textnachricht vorab anzeigen (berechtigte, abgemeldete und Anzahl ohne Telefonnummer)
GET/sentJWT—Alle gesendeten Textnachrichten-Datensätze der Gemeinde laden
GET/sent/:id/detailsJWT—Eine gesendete Textnachricht mit Zustellprotokollen pro Empfänger laden
POST/providersJWT—Texting-Anbieter speichern (Stapelverarbeitung). Verschlüsselt API-Zugangsdaten
POST/sendJWT—Eine SMS an alle berechtigten Mitglieder einer Gruppe senden. Body: { groupId, message }. Platzhalter ({{firstName}}, {{lastName}}, {{displayName}}, {{churchName}}) werden für jeden Empfänger aufgelöst
POST/sendPersonJWT—Eine SMS an eine einzelne Person senden. Body: { personId, phoneNumber, message }. Platzhalter werden aufgelöst, und der aufgelöste Text wird protokolliert
DELETE/providers/:idJWT—Einen Texting-Anbieter löschen

Beispiel: Gruppen-Textnachricht 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 den Versand von Vorlagen-E-Mails an Gruppen.

MethodePfadAuthBerechtigungBeschreibung
GET/JWT—Alle E-Mail-Vorlagen der Gemeinde laden
GET/:idJWT—Eine einzelne E-Mail-Vorlage anhand der ID laden
GET/sendStatusJWTgroupMembers.edit oder tasks.adminDer E-Mail-Status der Gruppen der Gemeinde: { approved, paused, remaining, requested }. Der Dialog „E-Mail senden“ von B1Admin und die Workflow-Aktion E-Mail senden nutzen ihn, um zu warnen, wenn E-Mails nicht versendet werden können
POST/requestApprovalJWTgroupMembers.editBeim Support die Freigabe der Gemeinde für Gruppen-E-Mails beantragen (höchstens einmal pro Gemeinde und Woche)
GET/preview/:groupIdJWT—Vorschau des E-Mail-Versands für eine Gruppe (Anzahl berechtigter Empfänger, Mitglieder ohne E-Mail-Adresse)
POST/JWT—E-Mail-Vorlagen erstellen oder aktualisieren (Stapelverarbeitung)
POST/sendJWT—Eine Vorlagen-E-Mail an alle Mitglieder einer Gruppe senden. Body: { groupId, subject, htmlContent }
DELETE/:idJWT—Eine E-Mail-Vorlage löschen

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 Platzhalter: {{firstName}}, {{lastName}}, {{displayName}}, {{email}}, {{churchName}}

Gesperrte IP-Adressen​

Basispfad: /messaging/blockedips

(veraltet) IP-Sperre für Live-Stream-Chats. Der B1App-Client ruft POST / nicht mehr auf, da die IP-Sperre bei der Umstellung auf die einheitliche Zustellung entfernt wurde. Die Route /clear wird weiterhin serverseitig von StreamingServiceController aufgerufen, wenn Streaming-Dienste gespeichert werden.

MethodePfadAuthBerechtigungBeschreibung
POST/JWT—(veraltet) Gesperrte IP-Adressen speichern (Stapelverarbeitung). Kein aktiver Client
POST/clearJWT—Alle gesperrten IP-Adressen für bestimmte Dienste löschen. Body: [{ serviceId, churchId }]

Zustellprotokolle​

Basispfad: /messaging/deliverylogs

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

MethodePfadAuthBerechtigungBeschreibung
GET/content/:contentType/:contentIdJWT—Zustellprotokolle nach Inhaltstyp und ID laden
GET/person/:personIdJWT—Zustellprotokolle einer Person laden. Optional ?startDate=&endDate= als Filter
GET/recentJWT—Aktuelle Zustellprotokolle der Gemeinde laden. Optional ?limit= (Standard 100)
GET/:idJWT—Ein Zustellprotokoll anhand der ID laden

Verwandte Seiten​