Vai al contenuto principale

Endpoint di messaggistica

Il modulo Messaging gestisce conversazioni in tempo reale, messaggi di chat, notifiche push, invio di SMS/email, connessioni WebSocket, messaggi privati, registrazione dei dispositivi e provider di messaggistica. Fornisce il livello di comunicazione usato da tutte le applicazioni ChurchApps, sia per la chat delle dirette streaming sia per le notifiche asincrone.

Percorso base: /messaging

Conversazioni​

Percorso base: /messaging/conversations

MetodoPercorsoAutenticazionePermessoDescrizione
GET/timeline/ids?ids=JWT—Carica le conversazioni per ID separati da virgola, con primo e ultimo messaggio
GET/messages/:contentType/:contentIdJWT—Carica le conversazioni di un contenuto con messaggi paginati (?page=&limit=)
GET/postsJWT—Ottiene le conversazioni di tipo post dei gruppi dell'utente corrente
GET/posts/group/:groupIdJWT—Ottiene le conversazioni di tipo post di un gruppo specifico
GET/notes/feed?section=&limit=&before=JWT—Le note più recenti di tutti i record per la pagina Note di B1 Admin. section è people, groups, events o workflows (altrimenti 400); limit vale 25 di default (massimo 100); before è il cursore della pagina precedente. Ogni nota passa comunque la regola del proprio tipo (permesso People Edit / note riservate, leader del gruppo, visualizzatori dell'evento, visualizzatori della scheda del flusso di lavoro), quindi i chiamanti vedono solo le note che potrebbero aprire. Il testo della nota è troncato a 300 caratteri
GET/current/:churchId/:contentType/:contentIdPubblico—Ottiene o crea la conversazione corrente per il contenuto (decifra automaticamente contentId)
GET/:churchId/:contentType/:contentIdPubblico—Carica le conversazioni per tipo di contenuto e ID
GET/:churchId/:idPubblico—Carica una singola conversazione tramite ID
POST/JWT—Crea o aggiorna conversazioni (batch)
POST/startJWT—Avvia una nuova conversazione con un messaggio di commento iniziale
DELETE/:churchId/:idJWT—Elimina una conversazione

Controllo degli accessi alle note delle persone​

Le conversazioni con contentType: "person" (la scheda Note di una scheda persona) o contentType: "personConfidential" (la sezione Note riservate) sono protette in ogni percorso di lettura e scrittura, incluse le rotte pubbliche sopra elencate, che restituiscono 401 per questi tipi di contenuto. person richiede il permesso People / Edit di MembershipApi; personConfidential richiede People / View Confidential Notes. Per le chiavi API con ambito, people:write copre entrambe le azioni (l'utente della chiave deve comunque avere il permesso del ruolo sottostante).

Controllo degli accessi alle note di gruppo e di evento​

Altri due tipi di contenuto nota sono protetti allo stesso modo, in ogni percorso di lettura e scrittura (incluse le rotte pubbliche sopra), e non sono mai aperti a pubblicazioni anonime:

  • groupNote (contentId = ID del gruppo) -- il flusso Note dei leader di un gruppo. Solo i leader di quel gruppo (leaderGroupIds nel JWT) possono leggere o pubblicare. Nessun permesso dello staff concede l'accesso, inclusi content.edit e i permessi di appartenenza ai gruppi.
  • eventNote (contentId = ID dell'evento) -- le note di un evento di calendario. Lo staff con content.edit o Calendars / Admin può sempre leggere e pubblicare. Altrimenti l'accesso segue il notesViewRole (lettura) e il notesPostRole (pubblicazione) dell'evento: staff (predefinito, usato quando il campo è null) non consente a nessun altro, leaders consente i leader del gruppo dell'evento, e members consente i membri e i leader del gruppo dell'evento. Un evento senza groupId è riservato allo staff.

Controllo degli accessi alle note delle schede del flusso di lavoro​

Le conversazioni con contentType: "workflowCard" (le note su una scheda del flusso di lavoro, dove contentId è l'ID dell'attività della scheda) possono essere lette e scritte solo da chi può aprire quella scheda: un utente con il permesso DoingApi Tasks / View, oppure la persona o il gruppo a cui la scheda è assegnata, creata da o relativa. Tutti gli altri ricevono 401 in ogni percorso di lettura, incluse le rotte pubbliche sopra. La conversazione di una scheda viene collegata tramite la scheda stessa con POST /doing/tasks/:id/conversation (corpo { "conversationId": "..." }; vince la prima conversazione collegata), che possono chiamare gli editor della scheda e il suo assegnatario.

Esempio: avviare una conversazione​

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

Messaggi​

Percorso base: /messaging/messages

MetodoPercorsoAutenticazionePermessoDescrizione
GET/conversation/:conversationIdJWT—Carica tutti i messaggi di una conversazione
GET/catchup/:churchId/:conversationIdPubblico—Carica tutti i messaggi di una conversazione (recupero pubblico per la chat in diretta)
GET/:churchId/:idPubblico—Carica un singolo messaggio tramite ID
POST/JWT—Salva messaggi (batch). Invia aggiornamenti in tempo reale e attiva le notifiche. Modificare un messaggio esistente richiede di esserne l'autore oppure avere content.edit; l'autore salvato non può mai essere riassegnato
POST/sendPubblico—Invia messaggi (batch, pubblico). Invia aggiornamenti in tempo reale tramite WebSocket e attiva le notifiche
POST/setCalloutJWT—(legacy) Trasmette in tempo reale un messaggio di evidenza. Nessun client attivo; la chat delle dirette non mostra più gli evidenziati
DELETE/:churchId/:idJWT—Elimina un messaggio e trasmette in tempo reale l'eliminazione. Vedi Moderazione dei messaggi

Moderazione dei messaggi​

L'eliminazione di un messaggio è consentita a:

  • l'autore del messaggio;
  • lo staff con content.edit (in tutta la chiesa);
  • i leader di gruppo, per le conversazioni con contentType group o groupAnnouncement il cui contentId è un gruppo che guidano (leaderGroupIds nel JWT).

Le conversazioni di note su persone (person / personConfidential) non sono mai moderate dai leader: usano invece i permessi delle note (people.edit, people.viewConfidentialNotes).

I leader possono solo eliminare, non modificare: riscrivere il messaggio di un altro membro resta limitato all'autore e allo staff con content.edit.

Esempio: inviare un messaggio​

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

Messaggi privati​

Percorso base: /messaging/privatemessages

MetodoPercorsoAutenticazionePermessoDescrizione
GET/JWT—Carica tutti i messaggi privati dell'utente corrente (include l'ultimo messaggio per conversazione e segna tutto come letto)
GET/existing/:personIdJWT—Trova una conversazione privata esistente con una specifica persona
GET/:idJWT—Carica un messaggio privato tramite ID (cancella la notifica se destinato all'utente corrente)
POST/JWT—Invia messaggi privati (batch). Attiva una notifica push al destinatario

Notifiche​

Percorso base: /messaging/notifications

MetodoPercorsoAutenticazionePermessoDescrizione
GET/unreadCountJWT—Ottiene il numero di notifiche non lette dell'utente corrente
GET/myJWT—Carica tutte le notifiche dell'utente corrente (le segna tutte come lette)
GET/tmpEmailPubblico—Attiva il riepilogo giornaliero delle notifiche via email (endpoint di debug/cron)
GET/:churchId/person/:personIdJWT—Carica le notifiche di una specifica persona
GET/:churchId/:idJWT—Carica una notifica tramite ID
POST/JWT—Crea o aggiorna notifiche (batch)
POST/createJWT—Crea notifiche per più persone. Corpo: { peopleIds, contentType, contentId, message, link }
POST/markRead/:churchId/:personIdJWT—Segna come lette tutte le notifiche di una persona
POST/sendTestJWT—Invia una notifica push di prova. Corpo: { personId, title }
POST/pingPubblico—Crea una notifica da un trigger esterno. Corpo: { personId, churchId, contentType, contentId, message, triggeredByPersonId }
DELETE/:churchId/:idJWT—Elimina una notifica
GET/groupPreview/:groupIdJWTgroupMembers.editConta quanti membri di un gruppo raggiungerebbe una push
GET/churchPreviewJWTcontent.editConta quante persone raggiungerebbe una push a tutti quelli con l'app
POST/group/sendJWTgroupMembers.editInvia subito una push ai membri di un gruppo

Esempio: creare notifiche​

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

Notifiche programmate​

Percorso base: /messaging/scheduledNotifications

Push programmate in anticipo. audience è church (tutti quelli con l'app; richiede content.edit) oppure group (richiede groupMembers.edit e un groupId). Il titolo è limitato a 80 caratteri e il messaggio a 240. Una riga scaduta viene inviata dal timer che gira ogni minuto.

MetodoPercorsoAutenticazionePermessoDescrizione
GET/JWTgroupMembers.edit o content.editElenca le notifiche programmate e quelle recenti della chiesa
POST/JWTper destinatariCrea una notifica programmata, oppure ne aggiorna una quando è impostato id. Corpo: { id?, audience, groupId?, title, message, link?, imageUrl?, sendAt }. Aggiornarne una che non è più in attesa restituisce 409
POST/:id/sendNowJWTper destinatariInvia subito una notifica in attesa. Restituisce 409 se è già stata inviata, annullata o è in invio
DELETE/:idJWTper destinatariAnnulla una notifica in attesa, oppure rimuove dall'elenco una notifica inviata, fallita o annullata. Restituisce 409 mentre è in invio
DELETE/JWTgroupMembers.edit o content.editRimuove tutte le notifiche inviate, fallite e annullate per i destinatari a cui l'utente può inviare. Restituisce { deleted }

Preferenze di notifica​

Percorso base: /messaging/notificationpreferences

MetodoPercorsoAutenticazionePermessoDescrizione
GET/categoriesJWT—Elenca le categorie di notifica con i canali predefiniti e quelli consentiti
GET/myJWT—Carica le preferenze di notifica dell'utente corrente (crea i valori predefiniti se non esistono)
POST/JWT—Salva le preferenze dell'utente corrente. Corpo: uno o più tra allowPush, allowSms, emailFrequency, masterMute, quietHoursStart, quietHoursEnd, timeZone, maxPushPerDay, più overrides: [{ categoryKey, channel, optedIn }] facoltativo (il canale può essere push, email, in_app o sms; le categorie bloccate vengono ignorate). allowSms è il consenso del membro ai promemoria via SMS. È ancora accettato il vecchio formato con array di righe

Connessioni​

Percorso base: /messaging/connections

Gestisce le connessioni WebSocket/in tempo reale per la chat, le conversazioni di gruppo, i messaggi privati e le dirette streaming. Vedi Architettura in tempo reale per il protocollo completo.

MetodoPercorsoAutenticazionePermessoDescrizione
GET/:churchId/:conversationIdPubblico—Carica tutte le connessioni di una conversazione
POST/Pubblico—Registra connessioni (batch). Attiva una trasmissione della presenza sulla conversazione. Elementi del corpo: { churchId, conversationId, socketId, displayName?, personId? }
POST/setNamePubblico—Aggiorna il nome visualizzato di una connessione tramite socket ID. Corpo: { socketId, name }
DELETE/:churchId/:conversationId/:socketIdPubblico—Rimuove una connessione da una conversazione. Attiva una trasmissione della presenza
POST/tmpSendAlertPubblico—Invia un avviso di notifica alle connessioni di una persona. Corpo: { churchId, personId }

Dispositivi​

Percorso base: /messaging/devices

Gestisce la registrazione dei dispositivi per le notifiche push e l'abbinamento dei contenuti (ad esempio l'app Lessons sugli schermi TV).

MetodoPercorsoAutenticazionePermessoDescrizione
POST/enrollJWT—Registra o aggiorna un dispositivo (registrazione push mobile). Corrisponde tramite token FCM o ID dispositivo
POST/enrollAnonPubblico—Registra un dispositivo anonimo e genera un codice di abbinamento di 4 caratteri
POST/Pubblico—Salva dispositivi (batch)
GET/pair/:pairingCodeJWT—Abbina un dispositivo usando il suo codice di abbinamento. ?contentType=&contentId= facoltativi per assegnare un contenuto
GET/status/:deviceIdPubblico—Verifica lo stato di abbinamento di un dispositivo
GET/:churchIdJWT—Carica tutti i dispositivi di una chiesa
GET/:churchId/person/:personIdJWT—Carica tutti i dispositivi di una persona
GET/:churchId/:idJWT—Carica un dispositivo tramite ID
DELETE/:churchId/:idJWT—Elimina un dispositivo

Esempio: registrare un dispositivo​

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

Contenuti dei dispositivi​

Percorso base: /messaging/devicecontents

Gestisce le assegnazioni di contenuti per i dispositivi abbinati (ad esempio quale lezione viene mostrata su una TV).

MetodoPercorsoAutenticazionePermessoDescrizione
GET/deviceId/:deviceIdJWT—Carica le assegnazioni di contenuto di un dispositivo
POST/JWT—Salva le assegnazioni di contenuto dei dispositivi (batch)
DELETE/:idJWT—Elimina un'assegnazione di contenuto di un dispositivo

SMS​

Percorso base: /messaging/texting

Gestisce i provider di SMS, l'invio di messaggi di testo ai gruppi e il monitoraggio delle consegne.

MetodoPercorsoAutenticazionePermessoDescrizione
GET/providersJWT—Carica i provider di SMS della chiesa (le credenziali sono mascherate)
GET/statusJWT—{ enabled } -- indica se la chiesa ha un provider di SMS attivo. Qualsiasi utente autenticato della chiesa; serve a mostrare le opzioni Testo solo quando è possibile inviare SMS
GET/inboundUrlJWTtexting.send o settings.edit{ url } -- l'URL webhook di risposta (STOP) della chiesa da incollare nel provider
POST/inbound/:churchId/:tokenPubblico—Webhook dei messaggi in entrata del provider. token è un HMAC dell'ID della chiesa. Una risposta che è esattamente una parola di interruzione (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, REVOKE) imposta optedOut per ogni persona corrispondente e disattiva il suo allowSms. Restituisce { optedOut: <count> }; le altre risposte restituiscono { optedOut: 0 }
GET/preview/:groupIdJWT—Anteprima dei destinatari di un SMS per un gruppo (conteggi di idonei, disiscritti, senza telefono)
GET/sentJWT—Carica tutti i record degli SMS inviati dalla chiesa
GET/sent/:id/detailsJWT—Carica un SMS inviato con i log di consegna per destinatario
POST/providersJWT—Salva i provider di SMS (batch). Cifra le credenziali API
POST/sendJWT—Invia un SMS a tutti i membri idonei di un gruppo. Corpo: { groupId, message }. I campi di unione ({{firstName}}, {{lastName}}, {{displayName}}, {{churchName}}) vengono risolti per ciascun destinatario
POST/sendPersonJWT—Invia un SMS a una singola persona. Corpo: { personId, phoneNumber, message }. I campi di unione vengono risolti e viene registrato il testo risolto
DELETE/providers/:idJWT—Elimina un provider di SMS

Esempio: inviare un SMS a un gruppo​

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
}

Modelli email​

Percorso base: /messaging/emailTemplates

Gestisce i modelli email riutilizzabili e l'invio di email basate su modelli ai gruppi.

MetodoPercorsoAutenticazionePermessoDescrizione
GET/JWT—Carica tutti i modelli email della chiesa
GET/:idJWT—Carica un singolo modello email tramite ID
GET/sendStatusJWTgroupMembers.edit o tasks.adminLo stato delle email di gruppo della chiesa: { approved, paused, remaining, requested }. La finestra Invia email di B1Admin e l'azione Invia email del flusso di lavoro lo usano per avvisare quando le email non partiranno
POST/requestApprovalJWTgroupMembers.editChiede al supporto di approvare la chiesa per le email di gruppo (al massimo una volta a settimana per chiesa)
GET/preview/:groupIdJWT—Anteprima della consegna email per un gruppo (conteggio dei destinatari idonei, membri senza email)
POST/JWT—Crea o aggiorna modelli email (batch)
POST/sendJWT—Invia un'email basata su modello a tutti i membri di un gruppo. Corpo: { groupId, subject, htmlContent }
DELETE/:idJWT—Elimina un modello email

Esempio: inviare un'email a un gruppo​

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
}

Campi di unione supportati: {{firstName}}, {{lastName}}, {{displayName}}, {{email}}, {{churchName}}

IP bloccati​

Percorso base: /messaging/blockedips

(legacy) Blocco degli IP per la chat delle dirette streaming. Il client di B1App non chiama più POST / -- il blocco degli IP è stato rimosso con la migrazione alla consegna unificata. La rotta /clear viene ancora invocata da server a server da StreamingServiceController quando i servizi di streaming vengono salvati.

MetodoPercorsoAutenticazionePermessoDescrizione
POST/JWT—(legacy) Salva gli IP bloccati (batch). Nessun client attivo
POST/clearJWT—Rimuove tutti gli IP bloccati per specifici servizi. Corpo: [{ serviceId, churchId }]

Log di consegna​

Percorso base: /messaging/deliverylogs

Traccia lo stato di consegna dei messaggi inviati (SMS, notifiche push, email).

MetodoPercorsoAutenticazionePermessoDescrizione
GET/content/:contentType/:contentIdJWT—Carica i log di consegna per tipo di contenuto e ID
GET/person/:personIdJWT—Carica i log di consegna di una persona. ?startDate=&endDate= facoltativi per filtrare
GET/recentJWT—Carica i log di consegna recenti della chiesa. ?limit= facoltativo (predefinito 100)
GET/:idJWT—Carica un log di consegna tramite ID