Ugrás a fő tartalomra

Üzenetküldési végpontok

Az Üzenetküldési modul a valós idejű beszélgetéseket, csevegőüzeneteket, push-értesítéseket, SMS- és e-mail-küldést, WebSocket-kapcsolatokat, privát üzeneteket, eszközregisztrációt és SMS-szolgáltatókat kezeli. Ez biztosítja a kommunikációs réteget, amelyet minden ChurchApps-alkalmazás használ, mind az élő közvetítés csevegéséhez, mind az aszinkron értesítésekhez.

Alapútvonal: /messaging

Beszélgetések​

Alapútvonal: /messaging/conversations

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/timeline/ids?ids=JWT—Beszélgetések betöltése vesszővel elválasztott azonosítók alapján, az első és utolsó üzenetekkel
GET/messages/:contentType/:contentIdJWT—Egy tartalomhoz tartozó beszélgetések betöltése lapozott üzenetekkel (?page=&limit=)
GET/postsJWT—A jelenlegi felhasználó csoportjaihoz tartozó bejegyzés-típusú beszélgetések lekérése
GET/posts/group/:groupIdJWT—Egy adott csoporthoz tartozó bejegyzés-típusú beszélgetések lekérése
GET/notes/feed?section=&limit=&before=JWT—A legújabb jegyzetek minden rekordhoz a B1 Admin Jegyzetek oldalon. A section értéke people, groups, events vagy workflows lehet (egyébként 400-as hiba); a limit alapértéke 25 (maximum 100); a before az előző oldal kurzora. Minden jegyzetnek meg kell felelnie a saját típusa szabályának (Személyek szerkesztése / bizalmas jegyzetek jogosultság, csoportvezetők, eseményt megtekintők, munkafolyamat-kártyát megtekintők), így a hívók csak azokat a jegyzeteket látják, amelyeket meg tudnának nyitni. A jegyzetek szövegét 300 karakterre vágjuk
GET/current/:churchId/:contentType/:contentIdNyilvános—A tartalomhoz tartozó aktuális beszélgetés lekérése vagy létrehozása (a contentId-t automatikusan visszafejti)
GET/:churchId/:contentType/:contentIdNyilvános—Beszélgetések betöltése tartalomtípus és azonosító alapján
GET/:churchId/:idNyilvános—Egy beszélgetés betöltése azonosító alapján
POST/JWT—Beszélgetések létrehozása vagy frissítése (kötegelve)
POST/startJWT—Új beszélgetés indítása egy kezdeti hozzászólás üzenettel
DELETE/:churchId/:idJWT—Beszélgetés törlése

Személyes jegyzetekhez való hozzáférés-szabályozás​

A contentType: "person" (a személyi rekord Jegyzetek lapja) vagy contentType: "personConfidential" (a Bizalmas jegyzetek szakasz) típusú beszélgetéseket minden olvasási és írási útvonalon ellenőrzik, beleértve a fenti, egyébként nyilvános útvonalakat is, amelyek ezekre a tartalomtípusokra 401-es választ adnak. A person típushoz a MembershipApi Személyek / Szerkesztés jogosultság szükséges; a personConfidential típushoz a Személyek / Bizalmas jegyzetek megtekintése jogosultság. Korlátozott API-kulcsok esetén a people:write mindkét műveletet tartalmazza (a kulcs felhasználójának továbbra is rendelkeznie kell a mögöttes szerepkör-jogosultsággal).

Csoport- és eseményjegyzetek hozzáférés-szabályozása​

Két további jegyzettípust ugyanúgy ellenőriznek minden olvasási és írási útvonalon (a fenti nyilvános útvonalakat is beleértve), és soha nem nyitják meg névtelen hozzászólás számára:

  • groupNote (contentId = csoportazonosító) -- a csoport Vezetői jegyzetei hírfolyama. Csak az adott csoport vezetői (a JWT leaderGroupIds mezője) olvashatják vagy tehetnek közzé bejegyzést. Egyetlen munkatársi jogosultság sem biztosít hozzáférést, beleértve a content.edit és a csoporttagsági jogosultságokat.
  • eventNote (contentId = eseményazonosító) -- egy naptári eseményhez tartozó jegyzetek. A content.edit jogosultsággal rendelkező vagy a Naptárak / Adminisztrátor jogkörrel bíró munkatársak mindig olvashatják és közzétehetik a jegyzeteket. Egyébként a hozzáférés az esemény notesViewRole (olvasás) és notesPostRole (közzététel) mezőjét követi: a staff (az alapértelmezett, ha a mező null) senki mást nem enged, a leaders az esemény csoportjának vezetőit, a members pedig az esemény csoportjának tagjait és vezetőit engedélyezi. A groupId nélküli esemény csak munkatársak számára érhető el.

Munkafolyamat-kártya jegyzeteinek hozzáférés-szabályozása​

A contentType: "workflowCard" típusú beszélgetések (a munkafolyamat-kártya jegyzetei, ahol a contentId a kártya feladatazonosítója) csak azok számára olvashatók és írhatók, akik meg tudják nyitni az adott kártyát: a DoingApi Feladatok / Megtekintés jogosultsággal rendelkező felhasználó, vagy az a személy vagy csoport, akihez a kártya hozzá van rendelve, akit a kártya létrehozott, vagy akire a kártya vonatkozik. Mindenki más 401-es választ kap minden olvasási útvonalon, beleértve a fenti nyilvános útvonalakat is. A kártya beszélgetését magán a kártyán keresztül lehet csatolni a POST /doing/tasks/:id/conversation hívással (törzs: { "conversationId": "..." }; az első csatolt beszélgetés marad érvényben), amelyet a kártya szerkesztői és a hozzárendelt személy hívhat meg.

Példa: Beszélgetés indítása​

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

Üzenetek​

Alapútvonal: /messaging/messages

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/conversation/:conversationIdJWT—Egy beszélgetés összes üzenetének betöltése
GET/catchup/:churchId/:conversationIdNyilvános—Egy beszélgetés összes üzenetének betöltése (nyilvános utolérés élő csevegéshez)
GET/:churchId/:idNyilvános—Egy üzenet betöltése azonosító alapján
POST/JWT—Üzenetek mentése (kötegelve). Valós idejű frissítéseket küld és értesítéseket indít. Egy meglévő üzenet frissítéséhez a szerzőnek kell lennie, vagy a content.edit jogosultsággal kell rendelkezni; a tárolt szerző nem cserélhető le
POST/sendNyilvános—Üzenetek küldése (kötegelve, nyilvános). Valós idejű frissítéseket küld WebSocketen keresztül és értesítéseket indít
POST/setCalloutJWT—(elavult) Kiemelt üzenet közvetítése valós időben. Nincs aktív kliens; az élő közvetítés csevegése már nem jeleníti meg a kiemeléseket
DELETE/:churchId/:idJWT—Üzenet törlése és a törlés közvetítése valós időben. Lásd: Üzenetmoderálás

Üzenetmoderálás​

Üzenetet törölhet:

  • az üzenet szerzője;
  • a content.edit jogosultsággal rendelkező munkatárs (a gyülekezeten belül bárhol);
  • csoportvezetők, a contentType értéke group vagy groupAnnouncement típusú beszélgetések esetén, ahol a contentId olyan csoport, amelyet vezetnek (a JWT leaderGroupIds mezője).

A személyi jegyzetekhez tartozó beszélgetéseket (person / personConfidential) soha nem moderálják a vezetők; ezekre a jegyzetekre vonatkozó jogosultságok (people.edit, people.viewConfidentialNotes) vonatkoznak.

A vezetők csak törölhetnek, szerkeszteni nem: más tag üzenetének átírása továbbra is csak a szerzőre és a content.edit jogosultsággal rendelkező munkatársakra korlátozódik.

Példa: Üzenet küldése​

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

Privát üzenetek​

Alapútvonal: /messaging/privatemessages

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/JWT—A jelenlegi felhasználó összes privát üzenetének betöltése (beszélgetésenként az utolsó üzenettel, mindent olvasottnak jelöl)
GET/existing/:personIdJWT—Egy adott személlyel folytatott meglévő privát beszélgetés keresése
GET/:idJWT—Egy privát üzenet betöltése azonosító alapján (törli az értesítést, ha az aktuális felhasználónak szól)
POST/JWT—Privát üzenetek küldése (kötegelve). Push-értesítést indít a címzettnek

Értesítések​

Alapútvonal: /messaging/notifications

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/unreadCountJWT—A jelenlegi felhasználó olvasatlan értesítéseinek száma
GET/myJWT—A jelenlegi felhasználó összes értesítésének betöltése (mindent olvasottnak jelöl)
GET/tmpEmailNyilvános—Napi e-mail-értesítési összesítő indítása (hibakereső / ütemezett feladat végpont)
GET/:churchId/person/:personIdJWT—Egy adott személy értesítéseinek betöltése
GET/:churchId/:idJWT—Egy értesítés betöltése azonosító alapján
POST/JWT—Értesítések létrehozása vagy frissítése (kötegelve)
POST/createJWT—Értesítések létrehozása több személy számára. Törzs: { peopleIds, contentType, contentId, message, link }
POST/markRead/:churchId/:personIdJWT—Egy személy összes értesítésének olvasottnak jelölése
POST/sendTestJWT—Teszt push-értesítés küldése. Törzs: { personId, title }
POST/pingNyilvános—Értesítés létrehozása külső eseményindítóból. Törzs: { personId, churchId, contentType, contentId, message, triggeredByPersonId }
DELETE/:churchId/:idJWT—Értesítés törlése

Példa: Értesítések létrehozása​

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

Értesítési beállítások​

Alapútvonal: /messaging/notificationpreferences

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/categoriesJWT—Értesítési kategóriák listázása az alapértelmezett és engedélyezett csatornáikkal
GET/myJWT—A jelenlegi felhasználó értesítési beállításainak betöltése (ha nincsenek, automatikusan létrehozza az alapértékeket)
POST/JWT—A jelenlegi felhasználó beállításainak mentése. Törzs: a következők bármelyike: allowPush, allowSms, emailFrequency, masterMute, quietHoursStart, quietHoursEnd, timeZone, maxPushPerDay, valamint opcionálisan overrides: [{ categoryKey, channel, optedIn }] (a channel értéke lehet push, email, in_app vagy sms; a zárolt kategóriákat figyelmen kívül hagyja). Az allowSms a tag szöveges emlékeztetőkre adott hozzájárulását jelöli. A régi, sorokból álló tömb formátumú törzs továbbra is elfogadott

Kapcsolatok​

Alapútvonal: /messaging/connections

A WebSocket- és valós idejű kapcsolatokat kezeli csevegéshez, csoportbeszélgetésekhez, privát üzenetekhez és élő közvetítéshez. A teljes protokollért lásd: Valós idejű architektúra.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/:churchId/:conversationIdNyilvános—Egy beszélgetéshez tartozó összes kapcsolat betöltése
POST/Nyilvános—Kapcsolatok regisztrálása (kötegelve). Jelenlétet közvetít a beszélgetésen. A törzs elemei: { churchId, conversationId, socketId, displayName?, personId? }
POST/setNameNyilvános—Egy kapcsolat megjelenítendő nevének frissítése socket-azonosító alapján. Törzs: { socketId, name }
DELETE/:churchId/:conversationId/:socketIdNyilvános—Kapcsolat eltávolítása egy beszélgetésből. Jelenlétet közvetít
POST/tmpSendAlertNyilvános—Értesítő riasztás küldése egy személy kapcsolatainak. Törzs: { churchId, personId }

Eszközök​

Alapútvonal: /messaging/devices

Push-értesítésekhez és tartalompárosításhoz (pl. a Lessons alkalmazás TV-kijelzőkön) szükséges eszközregisztrációt kezeli.

MetódusÚtvonalHitelesítésJogosultságLeírás
POST/enrollJWT—Eszköz regisztrálása vagy frissítése (mobil push-regisztráció). FCM-token vagy eszközazonosító alapján illeszt
POST/enrollAnonNyilvels—Névtelen eszköz regisztrálása, és 4 karakteres párosítókód generálása
POST/Nyilvános—Eszközök mentése (kötegelve)
GET/pair/:pairingCodeJWT—Eszköz párosítása a párosítókódjával. Opcionális ?contentType=&contentId= a tartalom hozzárendeléséhez
GET/status/:deviceIdNyilvános—Egy eszköz párosítási állapotának ellenőrzése
GET/:churchIdJWT—Egy gyülekezet összes eszközének betöltése
GET/:churchId/person/:personIdJWT—Egy személy összes eszközének betöltése
GET/:churchId/:idJWT—Egy eszköz betöltése azonosító alapján
DELETE/:churchId/:idJWT—Eszköz törlése

Példa: Eszköz regisztrálása​

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

Eszköztartalmak​

Alapútvonal: /messaging/devicecontents

Párosított eszközökhöz tartozó tartalom-hozzárendeléseket kezeli (pl. melyik lecke jelenik meg egy TV-n).

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/deviceId/:deviceIdJWT—Egy eszköz tartalom-hozzárendeléseinek betöltése
POST/JWT—Eszköz tartalom-hozzárendelések mentése (kötegelve)
DELETE/:idJWT—Eszköz tartalom-hozzárendelés törlése

SMS-küldés​

Alapútvonal: /messaging/texting

SMS-szolgáltatókat, csoportos szöveges üzenetküldést és kézbesítés-követést kezel.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/providersJWT—A gyülekezet SMS-szolgáltatóinak betöltése (a hitelesítő adatok maszkolva vannak)
GET/statusJWT—{ enabled } -- az, hogy a gyülekezetnek van-e engedélyezett SMS-szolgáltatója. Bármely bejelentkezett gyülekezeti felhasználó lekérheti; a Szöveg lehetőségek csak akkor jelennek meg, ha szöveges üzenet küldhető
GET/inboundUrlJWTtexting.send vagy settings.edit{ url } -- a gyülekezet bejövő (STOP) webhook URL-je, amelyet be kell illeszteni a szolgáltatóba
POST/inbound/:churchId/:tokenNyilvános—Szolgáltató bejövő üzenet webhookja. A token a gyülekezet azonosítójának HMAC-je. Ha a válasz pontosan egy leállító szó (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, REVOKE), minden egyező személy optedOut állapotot kap, és a allowSms értéke kikapcsol. Visszaadja: { optedOut: <count> }; más válaszok esetén { optedOut: 0 }
GET/preview/:groupIdJWT—Egy csoportos szöveges üzenet címzettjeinek előnézete (jogosult, leiratkozott és telefonszám nélküli darabszámok)
GET/sentJWT—A gyülekezet összes elküldött szöveges üzenetének rekordjai
GET/sent/:id/detailsJWT—Egy elküldött szöveges üzenet betöltése, címzettenkénti kézbesítési naplókkal
POST/providersJWT—SMS-szolgáltatók mentése (kötegelve). Titkosítja az API-hitelesítő adatokat
POST/sendJWT—SMS küldése egy csoport összes jogosult tagjának. Törzs: { groupId, message }. A összefésülő mezők ({{firstName}}, {{lastName}}, {{displayName}}, {{churchName}}) címzettenként kerülnek feloldásra
POST/sendPersonJWT—SMS küldése egyetlen személynek. Törzs: { personId, phoneNumber, message }. Az összefésülő mezők feloldódnak, és a feloldott szöveg kerül naplózásra
DELETE/providers/:idJWT—SMS-szolgáltató törlése

Példa: Csoportos szöveges üzenet küldése​

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 sablonok​

Alapútvonal: /messaging/emailTemplates

Újrafelhasználható e-mail sablonokat kezel, és sablonos e-maileket küld csoportoknak.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/JWT—A gyülekezet összes e-mail sablonjának betöltése
GET/:idJWT—Egy e-mail sablon betöltése azonosító alapján
GET/sendStatusJWTgroupMembers.edit vagy tasks.adminA gyülekezet csoportos e-mail állapota: { approved, paused, remaining, requested }. A B1Admin E-mail küldése párbeszédablaka és a munkafolyamat E-mail küldése művelete ezt használja, hogy figyelmeztessen, ha az e-mail nem fog kimenni
POST/requestApprovalJWTgroupMembers.editKérés a támogatásnak, hogy hagyják jóvá a gyülekezetet csoportos e-mailekhez (gyülekezetenként legfeljebb hetente egyszer)
GET/preview/:groupIdJWT—Egy csoport e-mail-kézbesítésének előnézete (jogosult címzettek száma, e-mail-cím nélküli tagok)
POST/JWT—E-mail sablonok létrehozása vagy frissítése (kötegelve)
POST/sendJWT—Sablonos e-mail küldése egy csoport összes tagjának. Törzs: { groupId, subject, htmlContent }
DELETE/:idJWT—E-mail sablon törlése

Példa: E-mail küldése csoportnak​

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
}

Támogatott összefésülő mezők: {{firstName}}, {{lastName}}, {{displayName}}, {{email}}, {{churchName}}

Letiltott IP-címek​

Alapútvonal: /messaging/blockedips

(elavult) IP-címek letiltása élő közvetítésű csevegéshez. A B1App kliens már nem hívja meg a POST / végpontot -- az IP-letiltást az egységesített kézbesítési migráció során eltávolították. A /clear útvonalat a StreamingServiceController továbbra is szerverek közötti hívásként használja, amikor közvetítési szolgáltatásokat mentenek.

MetódusÚtvonalHitelesítésJogosultságLeírás
POST/JWT—(elavult) Letiltott IP-címek mentése (kötegelve). Nincs aktív kliens
POST/clearJWT—Letiltott IP-címek törlése meghatározott szolgáltatásokhoz. Törzs: [{ serviceId, churchId }]

Kézbesítési naplók​

Alapútvonal: /messaging/deliverylogs

Az elküldött üzenetek (SMS, push-értesítések, e-mail) kézbesítési állapotát követi nyomon.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/content/:contentType/:contentIdJWT—Kézbesítési naplók betöltése tartalomtípus és azonosító alapján
GET/person/:personIdJWT—Egy személy kézbesítési naplóinak betöltése. Opcionális ?startDate=&endDate= szűrők
GET/recentJWT—A gyülekezet legutóbbi kézbesítési naplóinak betöltése. Opcionális ?limit= (alapértelmezett 100)
GET/:idJWT—Kézbesítési napló betöltése azonosító alapján

Kapcsolódó oldalak​