Pular para o conteúdo principal

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étodoCaminhoAuthPermissãoDescrição
GET/timeline/ids?ids=JWT—Carrega conversas por IDs separados por vírgula, com a primeira e a última mensagem
GET/messages/:contentType/:contentIdJWT—Carrega conversas de um conteúdo com mensagens paginadas (?page=&limit=)
GET/postsJWT—Obtém conversas do tipo post dos grupos do usuário atual
GET/posts/group/:groupIdJWT—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/:contentIdPúblico—Obtém ou cria a conversa atual de um conteúdo (descriptografa o contentId automaticamente)
GET/:churchId/:contentType/:contentIdPúblico—Carrega conversas por tipo de conteúdo e ID
GET/:churchId/:idPúblico—Carrega uma única conversa pelo ID
POST/JWT—Cria ou atualiza conversas (em lote)
POST/startJWT—Inicia uma nova conversa com uma mensagem de comentário inicial
DELETE/:churchId/:idJWT—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 (leaderGroupIds no JWT) podem ler ou publicar. Nenhuma permissão de equipe concede acesso, incluindo content.edit e as permissões de participação em grupos.
  • eventNote (contentId = ID do evento) -- as anotações de um evento do calendário. Equipe com content.edit ou Calendários / Administrador sempre pode ler e publicar. Caso contrário, o acesso segue o notesViewRole (leitura) e o notesPostRole (publicação) do evento: staff (o padrão, usado quando o campo é null) não permite ninguém além da equipe, leaders permite os líderes do grupo do evento, e members permite os membros e líderes do grupo do evento. Um evento sem groupId é 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étodoCaminhoAuthPermissãoDescrição
GET/conversation/:conversationIdJWT—Carrega todas as mensagens de uma conversa
GET/catchup/:churchId/:conversationIdPúblico—Carrega todas as mensagens de uma conversa (recuperação pública para o chat ao vivo)
GET/:churchId/:idPú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/sendPúblico—Envia mensagens (em lote, público). Envia atualizações em tempo real via WebSocket e dispara notificações
POST/setCalloutJWT—(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/:idJWT—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 contentType group ou groupAnnouncement cujo contentId seja um grupo que eles lideram (leaderGroupIds no 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étodoCaminhoAuthPermissãoDescriçã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/:personIdJWT—Encontra uma conversa privada existente com uma pessoa específica
GET/:idJWT—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étodoCaminhoAuthPermissãoDescrição
GET/unreadCountJWT—Obtém a contagem de notificações não lidas do usuário atual
GET/myJWT—Carrega todas as notificações do usuário atual (marca todas como lidas)
GET/tmpEmailPúblico—Dispara o resumo diário de notificações por e-mail (endpoint de depuração/cron)
GET/:churchId/person/:personIdJWT—Carrega as notificações de uma pessoa específica
GET/:churchId/:idJWT—Carrega uma notificação pelo ID
POST/JWT—Cria ou atualiza notificações (em lote)
POST/createJWT—Cria notificações para várias pessoas. Corpo: { peopleIds, contentType, contentId, message, link }
POST/markRead/:churchId/:personIdJWT—Marca todas as notificações de uma pessoa como lidas
POST/sendTestJWT—Envia uma notificação push de teste. Corpo: { personId, title }
POST/pingPúblico—Cria uma notificação a partir de um gatilho externo. Corpo: { personId, churchId, contentType, contentId, message, triggeredByPersonId }
DELETE/:churchId/:idJWT—Exclui uma notificação
GET/groupPreview/:groupIdJWTgroupMembers.editConta quantos membros de um grupo um push alcançaria
GET/churchPreviewJWTcontent.editConta quantas pessoas um push para todos com o aplicativo alcançaria
POST/group/sendJWTgroupMembers.editEnvia 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étodoCaminhoAuthPermissãoDescrição
GET/JWTgroupMembers.edit ou content.editLista as notificações agendadas e as recentes da igreja
POST/JWTpor públicoCria 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/sendNowJWTpor públicoEnvia agora uma notificação pendente. Retorna 409 se já foi enviada, cancelada ou está sendo enviada
DELETE/:idJWTpor públicoCancela uma notificação pendente, ou remove da lista uma já enviada, com falha ou cancelada. Retorna 409 enquanto estiver sendo enviada
DELETE/JWTgroupMembers.edit ou content.editRemove 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étodoCaminhoAuthPermissãoDescrição
GET/categoriesJWT—Lista as categorias de notificação com seus canais padrão e permitidos
GET/myJWT—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étodoCaminhoAuthPermissãoDescrição
GET/:churchId/:conversationIdPú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/setNamePúblico—Atualiza o nome de exibição de uma conexão pelo ID do socket. Corpo: { socketId, name }
DELETE/:churchId/:conversationId/:socketIdPúblico—Remove uma conexão de uma conversa. Dispara uma transmissão de presença
POST/tmpSendAlertPú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étodoCaminhoAuthPermissãoDescrição
POST/enrollJWT—Registra ou atualiza um dispositivo (registro de push do celular). Faz a correspondência pelo token FCM ou pelo ID do dispositivo
POST/enrollAnonPú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/:pairingCodeJWT—Pareia um dispositivo usando seu código de pareamento. ?contentType=&contentId= opcionais para atribuir conteúdo
GET/status/:deviceIdPúblico—Verifica o status de pareamento de um dispositivo
GET/:churchIdJWT—Carrega todos os dispositivos de uma igreja
GET/:churchId/person/:personIdJWT—Carrega todos os dispositivos de uma pessoa
GET/:churchId/:idJWT—Carrega um dispositivo pelo ID
DELETE/:churchId/:idJWT—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étodoCaminhoAuthPermissãoDescrição
GET/deviceId/:deviceIdJWT—Carrega as atribuições de conteúdo de um dispositivo
POST/JWT—Salva as atribuições de conteúdo de dispositivos (em lote)
DELETE/:idJWT—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étodoCaminhoAuthPermissãoDescrição
GET/providersJWT—Carrega os provedores de texto da igreja (as credenciais são mascaradas)
GET/statusJWT—{ 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/inboundUrlJWTtexting.send ou settings.edit{ url } — a URL de webhook de entrada (STOP) da igreja, para colar no provedor
POST/inbound/:churchId/:tokenPú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/:groupIdJWT—Prévia dos destinatários de um texto para um grupo (contagens de elegíveis, descadastrados e sem telefone)
GET/sentJWT—Carrega todos os registros de mensagens de texto enviadas pela igreja
GET/sent/:id/detailsJWT—Carrega um texto enviado com os registros de entrega por destinatário
POST/providersJWT—Salva os provedores de texto (em lote). Criptografa as credenciais de API
POST/sendJWT—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/sendPersonJWT—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/:idJWT—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étodoCaminhoAuthPermissãoDescrição
GET/JWT—Carrega todos os modelos de e-mail da igreja
GET/:idJWT—Carrega um único modelo de e-mail pelo ID
GET/sendStatusJWTgroupMembers.edit ou tasks.adminStatus 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/requestApprovalJWTgroupMembers.editPede ao suporte a aprovação da igreja para e-mails de grupo (no máximo uma vez por igreja por semana)
GET/preview/:groupIdJWT—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/sendJWT—Envia um e-mail com modelo para todos os membros de um grupo. Corpo: { groupId, subject, htmlContent }
DELETE/:idJWT—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étodoCaminhoAuthPermissãoDescrição
POST/JWT—(legado) Salva IPs bloqueados (em lote). Sem cliente ativo
POST/clearJWT—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étodoCaminhoAuthPermissãoDescrição
GET/content/:contentType/:contentIdJWT—Carrega os registros de entrega por tipo e ID de conteúdo
GET/person/:personIdJWT—Carrega os registros de entrega de uma pessoa. ?startDate=&endDate= opcionais para filtrar
GET/recentJWT—Carrega os registros de entrega recentes da igreja. ?limit= opcional (padrão 100)
GET/:idJWT—Carrega um registro de entrega pelo ID