Lumipat sa pangunahing nilalaman

Mga Endpoint ng Messaging

Pinamamahalaan ng Messaging module ang mga real-time na usapan, chat message, push notification, paghahatid ng SMS/email, koneksyon ng WebSocket, pribadong mensahe, pagpaparehistro ng device, at mga texting provider. Ito ang communication layer na ginagamit sa lahat ng ChurchApps application, para sa live stream chat at sa mga asynchronous na notification.

Base path: /messaging

Mga Usapan​

Base path: /messaging/conversations

MethodPathAuthPermissionPaglalarawan
GET/timeline/ids?ids=JWT—I-load ang mga usapan ayon sa mga ID na pinaghihiwalay ng kuwit, kasama ang unang/huling mensahe
GET/messages/:contentType/:contentIdJWT—I-load ang mga usapan para sa content na may paginated na mensahe (?page=&limit=)
GET/postsJWT—Kunin ang mga usapang uri ng post para sa mga grupo ng kasalukuyang user
GET/posts/group/:groupIdJWT—Kunin ang mga usapang uri ng post para sa isang partikular na grupo
GET/notes/feed?section=&limit=&before=JWT—Pinakabagong notes sa bawat record para sa pahina ng Notes ng B1 Admin. Ang section ay people, groups, events, o workflows (400 kung iba); ang limit ay default na 25 (max 100); ang before ay cursor mula sa nakaraang pahina. Dumadaan pa rin ang bawat note sa sarili nitong patakaran ng uri (People Edit / pahintulot sa confidential notes, mga lider ng grupo, mga viewer ng event, mga viewer ng workflow card), kaya tanging mga note na mabubuksan nila ang nakikita ng tumatawag. Pinuputol sa 300 karakter ang teksto ng note
GET/current/:churchId/:contentType/:contentIdPublic—Kunin o gumawa ng kasalukuyang usapan para sa content (awtomatikong dine-decrypt ang contentId)
GET/:churchId/:contentType/:contentIdPublic—I-load ang mga usapan ayon sa uri at ID ng content
GET/:churchId/:idPublic—I-load ang isang usapan ayon sa ID
POST/JWT—Gumawa o mag-update ng mga usapan (batch)
POST/startJWT—Magsimula ng bagong usapan na may paunang comment na mensahe
DELETE/:churchId/:idJWT—Burahin ang isang usapan

Kontrol sa pag-access ng notes ng tao​

Ang mga usapang may contentType: "person" (ang tab na Notes sa record ng tao) o contentType: "personConfidential" (ang seksyong Confidential Notes) ay nakabantay sa bawat read at write path, kasama ang mga pampublikong route sa itaas, na nagbabalik ng 401 para sa mga uring ito ng content. Ang person ay nangangailangan ng pahintulot ng MembershipApi na People / Edit; ang personConfidential ay nangangailangan ng People / View Confidential Notes. Para sa mga scoped API key, sakop ng people:write ang parehong aksyon (dapat taglay pa rin ng user ng key ang pinagbabatayang pahintulot ng role).

Kontrol sa pag-access ng notes ng grupo at event​

May dalawa pang uri ng note na binabantayan sa parehong paraan, sa bawat read at write path (kasama ang mga pampublikong route sa itaas), at hindi kailanman bukas sa anonymous na pag-post:

  • groupNote (contentId = group ID) -- ang feed na Leader notes ng isang grupo. Tanging ang mga lider ng grupong iyon (leaderGroupIds sa JWT) ang makakabasa o makakapag-post. Walang pahintulot ng staff ang nagbibigay ng access, kasama ang content.edit at ang mga pahintulot ng membership ng grupo.
  • eventNote (contentId = event ID) -- ang mga note sa isang calendar event. Palaging makakabasa at makakapag-post ang staff na may content.edit o Calendars / Admin. Kung hindi, sumusunod ang access sa notesViewRole (basa) at notesPostRole (post) ng event: ang staff (default, ginagamit kapag null ang field) ay walang pinapayagang iba, ang leaders ay pinapayagan ang mga lider ng grupo ng event, at ang members ay pinapayagan ang mga miyembro at lider ng grupo ng event. Ang event na walang groupId ay para sa staff lamang.

Kontrol sa pag-access ng notes ng workflow card​

Ang mga usapang may contentType: "workflowCard" (ang mga note sa isang workflow card, kung saan ang contentId ay ang task ID ng card) ay mababasa at masusulatan lamang ng sinumang makakabukas ng card na iyon: isang user na may pahintulot na DoingApi Tasks / View, o ang taong o grupong naka-assign sa card, gumawa nito, o tungkol dito. Ang iba ay makakatanggap ng 401 sa bawat read path, kasama ang mga pampublikong route sa itaas. Naka-attach ang usapan ng card sa pamamagitan ng card mismo gamit ang POST /doing/tasks/:id/conversation (body { "conversationId": "..." }; ang unang naka-attach na usapan ang nananaig), na maaaring tawagin ng mga editor ng card at ng assignee nito.

Halimbawa: Pagsisimula ng Usapan​

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

Mga Mensahe​

Base path: /messaging/messages

MethodPathAuthPermissionPaglalarawan
GET/conversation/:conversationIdJWT—I-load ang lahat ng mensahe ng isang usapan
GET/catchup/:churchId/:conversationIdPublic—I-load ang lahat ng mensahe ng isang usapan (pampublikong catchup para sa live chat)
GET/:churchId/:idPublic—I-load ang isang mensahe ayon sa ID
POST/JWT—I-save ang mga mensahe (batch). Nagpapadala ng real-time na update at nagti-trigger ng mga notification. Ang pag-update ng umiiral na mensahe ay nangangailangan na ikaw ang may-akda nito o may hawak ng content.edit; hindi kailanman maililipat sa iba ang nakatalang may-akda
POST/sendPublic—Magpadala ng mga mensahe (batch, pampubliko). Nagpapadala ng real-time na update sa pamamagitan ng WebSocket at nagti-trigger ng mga notification
POST/setCalloutJWT—(legacy) Mag-broadcast ng callout message nang real time. Walang aktibong client; hindi na nire-render ng live stream chat ang mga callout
DELETE/:churchId/:idJWT—Burahin ang isang mensahe at i-broadcast ang pagbura nang real time. Tingnan ang Moderation ng mensahe

Moderation ng mensahe​

Pinapayagan ang pagbura ng mensahe para sa:

  • ang may-akda ng mensahe;
  • staff na may content.edit (saanman sa simbahan);
  • mga lider ng grupo, para sa mga usapang may contentType na group o groupAnnouncement na ang contentId ay grupong pinamumunuan nila (leaderGroupIds sa JWT).

Hindi kailanman minomoderate ng lider ang mga usapan ng note ng tao (person / personConfidential) -- gumagamit ang mga ito ng mga pahintulot sa notes (people.edit, people.viewConfidentialNotes) sa halip.

Pagbura lamang ang ibinibigay sa mga lider, hindi pag-edit: ang pagsusulat muli ng mensahe ng ibang miyembro ay nananatiling limitado sa may-akda at sa staff na may content.edit.

Halimbawa: Pagpapadala ng Mensahe​

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

Mga Pribadong Mensahe​

Base path: /messaging/privatemessages

MethodPathAuthPermissionPaglalarawan
GET/JWT—I-load ang lahat ng pribadong mensahe ng kasalukuyang user (kasama ang huling mensahe bawat usapan, at minamarkahang nabasa ang lahat)
GET/existing/:personIdJWT—Hanapin ang umiiral na pribadong usapan sa isang partikular na tao
GET/:idJWT—I-load ang pribadong mensahe ayon sa ID (binubura ang notification kung para sa kasalukuyang user)
POST/JWT—Magpadala ng mga pribadong mensahe (batch). Nagti-trigger ng push notification sa tatanggap

Mga Notification​

Base path: /messaging/notifications

MethodPathAuthPermissionPaglalarawan
GET/unreadCountJWT—Kunin ang bilang ng hindi pa nababasang notification ng kasalukuyang user
GET/myJWT—I-load ang lahat ng notification ng kasalukuyang user (minamarkahang nabasa ang lahat)
GET/tmpEmailPublic—I-trigger ang araw-araw na email digest ng notification (debug/cron endpoint)
GET/:churchId/person/:personIdJWT—I-load ang mga notification ng isang partikular na tao
GET/:churchId/:idJWT—I-load ang notification ayon sa ID
POST/JWT—Gumawa o mag-update ng mga notification (batch)
POST/createJWT—Gumawa ng mga notification para sa maraming tao. Body: { peopleIds, contentType, contentId, message, link }
POST/markRead/:churchId/:personIdJWT—Markahang nabasa ang lahat ng notification ng isang tao
POST/sendTestJWT—Magpadala ng test push notification. Body: { personId, title }
POST/pingPublic—Gumawa ng notification mula sa external na trigger. Body: { personId, churchId, contentType, contentId, message, triggeredByPersonId }
DELETE/:churchId/:idJWT—Burahin ang isang notification
GET/groupPreview/:groupIdJWTgroupMembers.editBilangin kung ilan sa mga miyembro ng grupo ang maaabot ng isang push
GET/churchPreviewJWTcontent.editBilangin kung ilang tao ang maaabot ng push sa lahat ng may app
POST/group/sendJWTgroupMembers.editMagpadala ng push sa mga miyembro ng grupo ngayon din

Halimbawa: Paggawa ng Mga Notification​

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

Mga Naka-iskedyul na Notification​

Base path: /messaging/scheduledNotifications

Mga push na naka-iskedyul nang maaga. Ang audience ay church (lahat ng may app; nangangailangan ng content.edit) o group (nangangailangan ng groupMembers.edit at groupId). Hanggang 80 karakter ang title at 240 ang message. Ipinapadala ng 1-minutong timer ang row na dumating na ang oras.

MethodPathAuthPermissionPaglalarawan
GET/JWTgroupMembers.edit o content.editIlista ang mga naka-iskedyul at kamakailang notification ng simbahan
POST/JWTayon sa audienceGumawa ng naka-iskedyul na notification, o mag-update kapag may id. Body: { id?, audience, groupId?, title, message, link?, imageUrl?, sendAt }. Ang pag-update ng hindi na pending ay nagbabalik ng 409
POST/:id/sendNowJWTayon sa audienceIpadala agad ang pending na notification. Nagbabalik ng 409 kung naipadala na, nakansela, o kasalukuyang ipinapadala
DELETE/:idJWTayon sa audienceKanselahin ang pending na notification, o alisin sa listahan ang naipadala, pumalya, o nakanselang notification. Nagbabalik ng 409 habang ipinapadala ito
DELETE/JWTgroupMembers.edit o content.editAlisin ang lahat ng naipadala, pumalya, at nakanselang notification para sa mga audience na maaaring padalhan ng user. Nagbabalik ng { deleted }

Mga Kagustuhan sa Notification​

Base path: /messaging/notificationpreferences

MethodPathAuthPermissionPaglalarawan
GET/categoriesJWT—Ilista ang mga kategorya ng notification kasama ang default at pinapayagang channel nito
GET/myJWT—I-load ang mga kagustuhan sa notification ng kasalukuyang user (awtomatikong gumagawa ng default kung wala pa)
POST/JWT—I-save ang mga kagustuhan ng kasalukuyang user. Body: anuman sa allowPush, allowSms, emailFrequency, masterMute, quietHoursStart, quietHoursEnd, timeZone, maxPushPerDay, kasama ang opsyonal na overrides: [{ categoryKey, channel, optedIn }] (ang channel ay maaaring push, email, in_app, o sms; hindi pinapansin ang mga naka-lock na kategorya). Ang allowSms ay opt-in ng miyembro para sa mga paalala sa text. Tinatanggap pa rin ang legacy na body na array ng mga row

Mga Koneksyon​

Base path: /messaging/connections

Pinamamahalaan ang mga koneksyon ng WebSocket/real-time para sa chat, mga usapan ng grupo, pribadong mensahe, at live streaming. Tingnan ang Real-time Architecture para sa buong protocol.

MethodPathAuthPermissionPaglalarawan
GET/:churchId/:conversationIdPublic—I-load ang lahat ng koneksyon ng isang usapan
POST/Public—Magrehistro ng mga koneksyon (batch). Nagti-trigger ng attendance broadcast sa usapan. Mga item ng body: { churchId, conversationId, socketId, displayName?, personId? }
POST/setNamePublic—I-update ang display name ng koneksyon ayon sa socket ID. Body: { socketId, name }
DELETE/:churchId/:conversationId/:socketIdPublic—Alisin ang koneksyon sa isang usapan. Nagti-trigger ng attendance broadcast
POST/tmpSendAlertPublic—Magpadala ng notification alert sa mga koneksyon ng isang tao. Body: { churchId, personId }

Mga Device​

Base path: /messaging/devices

Pinamamahalaan ang pagpaparehistro ng device para sa push notification at content pairing (hal., ang Lessons app sa mga TV display).

MethodPathAuthPermissionPaglalarawan
POST/enrollJWT—Mag-enroll o mag-update ng device (mobile push registration). Tumutugma ayon sa FCM token o device ID
POST/enrollAnonPublic—Mag-enroll ng anonymous na device at gumawa ng 4-karakter na pairing code
POST/Public—I-save ang mga device (batch)
GET/pair/:pairingCodeJWT—I-pair ang device gamit ang pairing code nito. Opsyonal na ?contentType=&contentId= para mag-assign ng content
GET/status/:deviceIdPublic—Suriin ang pairing status ng device
GET/:churchIdJWT—I-load ang lahat ng device ng simbahan
GET/:churchId/person/:personIdJWT—I-load ang lahat ng device ng isang tao
GET/:churchId/:idJWT—I-load ang device ayon sa ID
DELETE/:churchId/:idJWT—Burahin ang device

Halimbawa: Pag-enroll ng Device​

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

Nilalaman ng Device​

Base path: /messaging/devicecontents

Pinamamahalaan ang mga assignment ng content para sa mga naka-pair na device (hal., aling aralin ang ipinapakita sa TV).

MethodPathAuthPermissionPaglalarawan
GET/deviceId/:deviceIdJWT—I-load ang mga assignment ng content para sa isang device
POST/JWT—I-save ang mga assignment ng content ng device (batch)
DELETE/:idJWT—Burahin ang isang assignment ng content ng device

Texting​

Base path: /messaging/texting

Pinamamahalaan ang mga SMS texting provider, group text messaging, at pagsubaybay sa paghahatid.

MethodPathAuthPermissionPaglalarawan
GET/providersJWT—I-load ang mga texting provider ng simbahan (minamaskara ang mga credential)
GET/statusJWT—{ enabled } -- kung may naka-enable na texting provider ang simbahan. Sinumang naka-sign in na user ng simbahan; ginagamit para ipakita ang mga opsyong Text lamang kapag maaari nang magpadala ng text
GET/inboundUrlJWTtexting.send o settings.edit{ url } -- ang inbound (STOP) webhook URL ng simbahan na ipe-paste sa provider
POST/inbound/:churchId/:tokenPublic—Inbound-message webhook ng provider. Ang token ay HMAC ng church id. Ang reply na eksaktong stop word (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, REVOKE) ay minamarkahang optedOut ang bawat tugmang tao at pinapatay ang kanilang allowSms. Nagbabalik ng { optedOut: <count> }; ibang reply ay nagbabalik ng { optedOut: 0 }
GET/preview/:groupIdJWT—I-preview ang mga tatanggap ng group text (bilang ng eligible, opted-out, at walang phone)
GET/sentJWT—I-load ang lahat ng naipadalang text message record ng simbahan
GET/sent/:id/detailsJWT—I-load ang naipadalang text kasama ang delivery log bawat tatanggap
POST/providersJWT—I-save ang mga texting provider (batch). Nag-e-encrypt ng API credential
POST/sendJWT—Magpadala ng SMS sa lahat ng eligible na miyembro ng grupo. Body: { groupId, message }. Ang mga merge field ({{firstName}}, {{lastName}}, {{displayName}}, {{churchName}}) ay nireresolba bawat tatanggap
POST/sendPersonJWT—Magpadala ng SMS sa iisang tao. Body: { personId, phoneNumber, message }. Nireresolba ang mga merge field, at ang nireresolbang teksto ang naitatala
DELETE/providers/:idJWT—Burahin ang isang texting provider

Halimbawa: Pagpapadala ng Group Text​

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
}

Mga Email Template​

Base path: /messaging/emailTemplates

Pinamamahalaan ang mga magagamit-muling email template at pagpapadala ng templated na email sa mga grupo.

MethodPathAuthPermissionPaglalarawan
GET/JWT—I-load ang lahat ng email template ng simbahan
GET/:idJWT—I-load ang isang email template ayon sa ID
GET/sendStatusJWTgroupMembers.edit o tasks.adminAng status ng group email ng simbahan: { approved, paused, remaining, requested }. Ginagamit ng dialog na Send Email ng B1Admin at ng aksyong workflow na Send email para magbabala kapag hindi makakalabas ang email
POST/requestApprovalJWTgroupMembers.editHumiling sa support na aprubahan ang simbahan para sa group email (hanggang isang beses lamang bawat simbahan kada linggo)
GET/preview/:groupIdJWT—I-preview ang paghahatid ng email sa isang grupo (bilang ng eligible na tatanggap, mga miyembrong walang email)
POST/JWT—Gumawa o mag-update ng mga email template (batch)
POST/sendJWT—Magpadala ng templated na email sa lahat ng miyembro ng grupo. Body: { groupId, subject, htmlContent }
DELETE/:idJWT—Burahin ang isang email template

Halimbawa: Pagpapadala ng Email sa Grupo​

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
}

Mga suportadong merge field: {{firstName}}, {{lastName}}, {{displayName}}, {{email}}, {{churchName}}

Mga Naka-block na IP​

Base path: /messaging/blockedips

(legacy) Pag-block ng IP para sa live streaming chat. Hindi na tinatawag ng B1App client ang POST / -- inalis ang IP blocking sa unified-delivery migration. Tinatawag pa rin ang route na /clear nang server-to-server ng StreamingServiceController kapag na-save ang mga streaming service.

MethodPathAuthPermissionPaglalarawan
POST/JWT—(legacy) I-save ang mga naka-block na IP (batch). Walang aktibong client
POST/clearJWT—Burahin ang lahat ng naka-block na IP para sa mga partikular na service. Body: [{ serviceId, churchId }]

Mga Delivery Log​

Base path: /messaging/deliverylogs

Sinusubaybayan ang status ng paghahatid ng mga naipadalang mensahe (SMS, push notification, email).

MethodPathAuthPermissionPaglalarawan
GET/content/:contentType/:contentIdJWT—I-load ang mga delivery log ayon sa uri at ID ng content
GET/person/:personIdJWT—I-load ang mga delivery log ng isang tao. Opsyonal na ?startDate=&endDate= na filter
GET/recentJWT—I-load ang kamakailang delivery log ng simbahan. Opsyonal na ?limit= (default 100)
GET/:idJWT—I-load ang delivery log ayon sa ID