Endpoints de mensagens
O módulo de Mensagens gerencia conversas em tempo real, mensagens de chat, notificações push, entrega de SMS/e-mail, conexões WebSocket, mensagens privadas, registro de dispositivos e provedores de envio de texto. Ele oferece a camada de comunicação usada por todos os aplicativos do ChurchApps, tanto para o chat de transmissões ao vivo quanto para notificações assíncronas.
Caminho base: /messaging
Conversas
Caminho base: /messaging/conversations
| Método | Caminho | Auth | Permissão | Descrição |
|---|---|---|---|---|
| GET | /timeline/ids?ids= | JWT | — | Carrega conversas por IDs separados por vírgula, com a primeira e a última mensagem |
| GET | /messages/:contentType/:contentId | JWT | — | Carrega conversas de um conteúdo com mensagens paginadas (?page=&limit=) |
| GET | /posts | JWT | — | Obtém conversas do tipo post dos grupos do usuário atual |
| GET | /posts/group/:groupId | JWT | — | Obtém conversas do tipo post de um grupo específico |
| GET | /notes/feed?section=&limit=&before= | JWT | — | Anotações mais recentes de todos os registros, para a página de Anotações do B1 Admin. section é people, groups, events ou workflows (400 caso contrário); limit tem padrão 25 (máximo 100); before é o cursor da página anterior. Cada anotação ainda passa pela regra do próprio tipo (permissão de Editar Pessoas / anotações confidenciais, líderes do grupo, visualizadores do evento, visualizadores do cartão de fluxo de trabalho), então quem chama só vê anotações que poderia abrir. O texto da anotação é cortado em 300 caracteres |
| GET | /current/:churchId/:contentType/:contentId | Público | — | Obtém ou cria a conversa atual de um conteúdo (descriptografa o contentId automaticamente) |
| GET | /:churchId/:contentType/:contentId | Público | — | Carrega conversas por tipo de conteúdo e ID |
| GET | /:churchId/:id | Público | — | Carrega uma única conversa pelo ID |
| POST | / | JWT | — | Cria ou atualiza conversas (em lote) |
| POST | /start | JWT | — | Inicia uma nova conversa com uma mensagem de comentário inicial |
| DELETE | /:churchId/:id | JWT | — | Exclui uma conversa |
Controle de acesso às anotações de pessoas
Conversas com contentType: "person" (a aba Anotações de um registro de pessoa) ou contentType: "personConfidential" (a seção de Anotações confidenciais) são controladas em todos os caminhos de leitura e escrita, inclusive nas rotas públicas acima, que retornam 401 para esses tipos de conteúdo. person exige a permissão Pessoas / Editar da MembershipApi; personConfidential exige Pessoas / Ver anotações confidenciais. Para chaves de API com escopo, people:write cobre ambas as ações (o usuário da chave ainda precisa ter a permissão subjacente da função).
Controle de acesso às anotações de grupo e evento
Dois outros tipos de conteúdo de anotação são controlados da mesma forma, em todos os caminhos de leitura e escrita (inclusive nas rotas públicas acima), e nunca ficam abertos a publicação anônima:
groupNote(contentId= ID do grupo) -- o feed de Anotações do líder de um grupo. Somente os líderes desse grupo (leaderGroupIdsno JWT) podem ler ou publicar. Nenhuma permissão de equipe concede acesso, incluindocontent.edite as permissões de participação em grupos.eventNote(contentId= ID do evento) -- as anotações de um evento do calendário. Equipe comcontent.editou Calendários / Administrador sempre pode ler e publicar. Caso contrário, o acesso segue onotesViewRole(leitura) e onotesPostRole(publicação) do evento:staff(o padrão, usado quando o campo énull) não permite ninguém além da equipe,leaderspermite os líderes do grupo do evento, ememberspermite os membros e líderes do grupo do evento. Um evento semgroupIdé restrito à equipe.
Controle de acesso às anotações de cartões de fluxo de trabalho
Conversas com contentType: "workflowCard" (as anotações de um cartão de fluxo de trabalho, em que contentId é o ID da tarefa do cartão) só podem ser lidas e escritas por quem pode abrir esse cartão: um usuário com a permissão Tarefas / Ver da DoingApi, ou a pessoa ou grupo a quem o cartão está atribuído, criado para ou sobre. Todos os outros recebem 401 em todos os caminhos de leitura, inclusive nas rotas públicas acima. A conversa de um cartão é vinculada por meio do próprio cartão com POST /doing/tasks/:id/conversation (corpo { "conversationId": "..." }; a primeira conversa vinculada prevalece), que podem ser chamados pelos editores do cartão e pelo responsável por ele.
Exemplo: iniciar uma conversa
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"
}
Mensagens
Caminho base: /messaging/messages
| Método | Caminho | Auth | Permissão | Descrição |
|---|---|---|---|---|
| GET | /conversation/:conversationId | JWT | — | Carrega todas as mensagens de uma conversa |
| GET | /catchup/:churchId/:conversationId | Público | — | Carrega todas as mensagens de uma conversa (recuperação pública para o chat ao vivo) |
| GET | /:churchId/:id | Público | — | Carrega uma única mensagem pelo ID |
| POST | / | JWT | — | Salva mensagens (em lote). Envia atualizações em tempo real e dispara notificações. Atualizar uma mensagem existente exige ser o autor ou ter content.edit; o autor armazenado nunca pode ser reatribuído |
| POST | /send | Público | — | Envia mensagens (em lote, público). Envia atualizações em tempo real via WebSocket e dispara notificações |
| POST | /setCallout | JWT | — | (legado) Transmite em tempo real uma mensagem de destaque. Sem cliente ativo; o chat de transmissões ao vivo não exibe mais destaques |
| DELETE | /:churchId/:id | JWT | — | Exclui uma mensagem e transmite a exclusão em tempo real. Veja Moderação de mensagens |
Moderação de mensagens
Excluir uma mensagem é permitido para:
- o autor da mensagem;
- a equipe com
content.edit(em qualquer lugar da igreja); - líderes de grupo, para conversas com
contentTypegroupougroupAnnouncementcujocontentIdseja um grupo que eles lideram (leaderGroupIdsno JWT).
Conversas de anotações de pessoas (person / personConfidential) nunca são moderadas por líderes — usam as permissões de anotações (people.edit, people.viewConfidentialNotes).
Líderes podem apenas excluir, não editar: reescrever a mensagem de outro membro continua restrito ao autor e à equipe com content.edit.
Exemplo: enviar uma mensagem
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"
}
]
Mensagens privadas
Caminho base: /messaging/privatemessages
| Método | Caminho | Auth | Permissão | Descrição |
|---|---|---|---|---|
| GET | / | JWT | — | Carrega todas as mensagens privadas do usuário atual (inclui a última mensagem de cada conversa e marca tudo como lido) |
| GET | /existing/:personId | JWT | — | Encontra uma conversa privada existente com uma pessoa específica |
| GET | /:id | JWT | — | Carrega uma mensagem privada pelo ID (limpa a notificação se for endereçada ao usuário atual) |
| POST | / | JWT | — | Envia mensagens privadas (em lote). Dispara notificação push para o destinatário |
Notificações
Caminho base: /messaging/notifications
| Método | Caminho | Auth | Permissão | Descrição |
|---|---|---|---|---|
| GET | /unreadCount | JWT | — | Obtém a contagem de notificações não lidas do usuário atual |
| GET | /my | JWT | — | Carrega todas as notificações do usuário atual (marca todas como lidas) |
| GET | /tmpEmail | Público | — | Dispara o resumo diário de notificações por e-mail (endpoint de depuração/cron) |
| GET | /:churchId/person/:personId | JWT | — | Carrega as notificações de uma pessoa específica |
| GET | /:churchId/:id | JWT | — | Carrega uma notificação pelo ID |
| POST | / | JWT | — | Cria ou atualiza notificações (em lote) |
| POST | /create | JWT | — | Cria notificações para várias pessoas. Corpo: { peopleIds, contentType, contentId, message, link } |
| POST | /markRead/:churchId/:personId | JWT | — | Marca todas as notificações de uma pessoa como lidas |
| POST | /sendTest | JWT | — | Envia uma notificação push de teste. Corpo: { personId, title } |
| POST | /ping | Público | — | Cria uma notificação a partir de um gatilho externo. Corpo: { personId, churchId, contentType, contentId, message, triggeredByPersonId } |
| DELETE | /:churchId/:id | JWT | — | Exclui uma notificação |
| GET | /groupPreview/:groupId | JWT | groupMembers.edit | Conta quantos membros de um grupo um push alcançaria |
| GET | /churchPreview | JWT | content.edit | Conta quantas pessoas um push para todos com o aplicativo alcançaria |
| POST | /group/send | JWT | groupMembers.edit | Envia um push para os membros de um grupo agora |
Exemplo: criar notificações
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"
}
Notificações agendadas
Caminho base: /messaging/scheduledNotifications
Pushes agendados com antecedência. audience é church (todos com o aplicativo; exige content.edit) ou group (exige groupMembers.edit e um groupId). O título é limitado a 80 caracteres e a mensagem a 240. Uma linha vencida é enviada pelo temporizador de 1 minuto.
| Método | Caminho | Auth | Permissão | Descrição |
|---|---|---|---|---|
| GET | / | JWT | groupMembers.edit ou content.edit | Lista as notificações agendadas e as recentes da igreja |
| POST | / | JWT | por público | Cria uma notificação agendada, ou atualiza uma quando id é informado. Corpo: { id?, audience, groupId?, title, message, link?, imageUrl?, sendAt }. Atualizar uma que não esteja mais pendente retorna 409 |
| POST | /:id/sendNow | JWT | por público | Envia agora uma notificação pendente. Retorna 409 se já foi enviada, cancelada ou está sendo enviada |
| DELETE | /:id | JWT | por público | Cancela uma notificação pendente, ou remove da lista uma já enviada, com falha ou cancelada. Retorna 409 enquanto estiver sendo enviada |
| DELETE | / | JWT | groupMembers.edit ou content.edit | Remove todas as notificações enviadas, com falha e canceladas dos públicos para os quais o usuário pode enviar. Retorna { deleted } |
Preferências de notificação
Caminho base: /messaging/notificationpreferences
| Método | Caminho | Auth | Permissão | Descrição |
|---|---|---|---|---|
| GET | /categories | JWT | — | Lista as categorias de notificação com seus canais padrão e permitidos |
| GET | /my | JWT | — | Carrega as preferências de notificação do usuário atual (cria os padrões automaticamente se não existirem) |
| POST | / | JWT | — | Salva as preferências do usuário atual. Corpo: qualquer um de allowPush, allowSms, emailFrequency, masterMute, quietHoursStart, quietHoursEnd, timeZone, maxPushPerDay, mais overrides: [{ categoryKey, channel, optedIn }] opcional (o canal pode ser push, email, in_app ou sms; categorias bloqueadas são ignoradas). allowSms é a adesão do membro aos lembretes por texto. Um corpo legado no formato de array de linhas ainda é aceito |
Conexões
Caminho base: /messaging/connections
Gerencia as conexões WebSocket/em tempo real do chat, das conversas de grupo, das mensagens privadas e das transmissões ao vivo. Veja Arquitetura em tempo real para o protocolo completo.
| Método | Caminho | Auth | Permissão | Descrição |
|---|---|---|---|---|
| GET | /:churchId/:conversationId | Público | — | Carrega todas as conexões de uma conversa |
| POST | / | Público | — | Registra conexões (em lote). Dispara uma transmissão de presença na conversa. Itens do corpo: { churchId, conversationId, socketId, displayName?, personId? } |
| POST | /setName | Público | — | Atualiza o nome de exibição de uma conexão pelo ID do socket. Corpo: { socketId, name } |
| DELETE | /:churchId/:conversationId/:socketId | Público | — | Remove uma conexão de uma conversa. Dispara uma transmissão de presença |
| POST | /tmpSendAlert | Público | — | Envia um alerta de notificação para as conexões de uma pessoa. Corpo: { churchId, personId } |
Dispositivos
Caminho base: /messaging/devices
Gerencia o registro de dispositivos para notificações push e para o pareamento de conteúdo (por exemplo, o aplicativo Lessons em telas de TV).
| Método | Caminho | Auth | Permissão | Descrição |
|---|---|---|---|---|
| POST | /enroll | JWT | — | Registra ou atualiza um dispositivo (registro de push do celular). Faz a correspondência pelo token FCM ou pelo ID do dispositivo |
| POST | /enrollAnon | Público | — | Registra um dispositivo anônimo e gera um código de pareamento de 4 caracteres |
| POST | / | Público | — | Salva dispositivos (em lote) |
| GET | /pair/:pairingCode | JWT | — | Pareia um dispositivo usando seu código de pareamento. ?contentType=&contentId= opcionais para atribuir conteúdo |
| GET | /status/:deviceId | Público | — | Verifica o status de pareamento de um dispositivo |
| GET | /:churchId | JWT | — | Carrega todos os dispositivos de uma igreja |
| GET | /:churchId/person/:personId | JWT | — | Carrega todos os dispositivos de uma pessoa |
| GET | /:churchId/:id | JWT | — | Carrega um dispositivo pelo ID |
| DELETE | /:churchId/:id | JWT | — | Exclui um dispositivo |
Exemplo: registrar um 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"
}
Conteúdo de dispositivos
Caminho base: /messaging/devicecontents
Gerencia as atribuições de conteúdo de dispositivos pareados (por exemplo, qual lição é exibida em uma TV).
| Método | Caminho | Auth | Permissão | Descrição |
|---|---|---|---|---|
| GET | /deviceId/:deviceId | JWT | — | Carrega as atribuições de conteúdo de um dispositivo |
| POST | / | JWT | — | Salva as atribuições de conteúdo de dispositivos (em lote) |
| DELETE | /:id | JWT | — | Exclui uma atribuição de conteúdo de dispositivo |
Envio de texto (SMS)
Caminho base: /messaging/texting
Gerencia os provedores de SMS, o envio de mensagens de texto para grupos e o acompanhamento de entregas.
| Método | Caminho | Auth | Permissão | Descrição |
|---|---|---|---|---|
| GET | /providers | JWT | — | Carrega os provedores de texto da igreja (as credenciais são mascaradas) |
| GET | /status | JWT | — | { enabled } — indica se a igreja tem um provedor de texto habilitado. Qualquer usuário conectado da igreja; usado para mostrar as opções Texto somente quando textos podem ser enviados |
| GET | /inboundUrl | JWT | texting.send ou settings.edit | { url } — a URL de webhook de entrada (STOP) da igreja, para colar no provedor |
| POST | /inbound/:churchId/:token | Público | — | Webhook de mensagens de entrada do provedor. token é um HMAC do ID da igreja. Uma resposta que seja exatamente uma palavra de parada (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, REVOKE) marca todas as pessoas correspondentes como optedOut e desliga o allowSms delas. Retorna { optedOut: <count> }; outras respostas retornam { optedOut: 0 } |
| GET | /preview/:groupId | JWT | — | Prévia dos destinatários de um texto para um grupo (contagens de elegíveis, descadastrados e sem telefone) |
| GET | /sent | JWT | — | Carrega todos os registros de mensagens de texto enviadas pela igreja |
| GET | /sent/:id/details | JWT | — | Carrega um texto enviado com os registros de entrega por destinatário |
| POST | /providers | JWT | — | Salva os provedores de texto (em lote). Criptografa as credenciais de API |
| POST | /send | JWT | — | Envia um SMS para todos os membros elegíveis de um grupo. Corpo: { groupId, message }. Os campos de mesclagem ({{firstName}}, {{lastName}}, {{displayName}}, {{churchName}}) são resolvidos para cada destinatário |
| POST | /sendPerson | JWT | — | Envia um SMS para uma única pessoa. Corpo: { personId, phoneNumber, message }. Os campos de mesclagem são resolvidos, e o texto resolvido é o que fica registrado |
| DELETE | /providers/:id | JWT | — | Exclui um provedor de texto |
Exemplo: enviar texto para um grupo
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
}
Modelos de e-mail
Caminho base: /messaging/emailTemplates
Gerencia modelos de e-mail reutilizáveis e o envio de e-mails com modelo para grupos.
| Método | Caminho | Auth | Permissão | Descrição |
|---|---|---|---|---|
| GET | / | JWT | — | Carrega todos os modelos de e-mail da igreja |
| GET | /:id | JWT | — | Carrega um único modelo de e-mail pelo ID |
| GET | /sendStatus | JWT | groupMembers.edit ou tasks.admin | Status de e-mail de grupo da igreja: { approved, paused, remaining, requested }. O diálogo Enviar e-mail do B1Admin e a ação Enviar e-mail do fluxo de trabalho usam-no para avisar quando o e-mail não será enviado |
| POST | /requestApproval | JWT | groupMembers.edit | Pede ao suporte a aprovação da igreja para e-mails de grupo (no máximo uma vez por igreja por semana) |
| GET | /preview/:groupId | JWT | — | Prévia da entrega de e-mail para um grupo (contagem de destinatários elegíveis, membros sem e-mail) |
| POST | / | JWT | — | Cria ou atualiza modelos de e-mail (em lote) |
| POST | /send | JWT | — | Envia um e-mail com modelo para todos os membros de um grupo. Corpo: { groupId, subject, htmlContent } |
| DELETE | /:id | JWT | — | Exclui um modelo de e-mail |
Exemplo: enviar e-mail para um 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
}
Campos de mesclagem suportados: {{firstName}}, {{lastName}}, {{displayName}}, {{email}}, {{churchName}}
IPs bloqueados
Caminho base: /messaging/blockedips
(legado) Bloqueio de IPs para o chat de transmissões ao vivo. O cliente do B1App não chama mais POST / — o bloqueio de IPs foi removido na migração para a entrega unificada. A rota /clear ainda é chamada de servidor para servidor pelo StreamingServiceController quando os cultos de transmissão são salvos.
| Método | Caminho | Auth | Permissão | Descrição |
|---|---|---|---|---|
| POST | / | JWT | — | (legado) Salva IPs bloqueados (em lote). Sem cliente ativo |
| POST | /clear | JWT | — | Limpa todos os IPs bloqueados de cultos específicos. Corpo: [{ serviceId, churchId }] |
Registros de entrega
Caminho base: /messaging/deliverylogs
Acompanha o status de entrega das mensagens enviadas (SMS, notificações push, e-mail).
| Método | Caminho | Auth | Permissão | Descrição |
|---|---|---|---|---|
| GET | /content/:contentType/:contentId | JWT | — | Carrega os registros de entrega por tipo e ID de conteúdo |
| GET | /person/:personId | JWT | — | Carrega os registros de entrega de uma pessoa. ?startDate=&endDate= opcionais para filtrar |
| GET | /recent | JWT | — | Carrega os registros de entrega recentes da igreja. ?limit= opcional (padrão 100) |
| GET | /:id | JWT | — | Carrega um registro de entrega pelo ID |
Páginas relacionadas
- Arquitetura em tempo real -- Protocolo WebSocket, assinaturas de salas e a estrutura de entrega unificada
- Notificações push na web -- Registro e entrega de push no navegador
- Endpoints de membros -- Pessoas, grupos, funções e identidade principal
- Endpoints de presença -- Rastreamento de cultos e visitas
- Autenticação e permissões -- Fluxo de login, JWT, OAuth, modelo de permissões
- Estrutura de módulos -- Padrões de organização do código