Módulo 2 - Comunicação Omnichannel & Chat (communication)
Módulo 2: Comunicação Omnichannel & Chat (communication)
Section titled “Módulo 2: Comunicação Omnichannel & Chat (communication)”Estado actual — Manager e Equipe. Cada cliente tem dois destinos visíveis, Manager e Team (Gerência e Equipe em português). Equipe abre a visita em andamento; senão a concluída hoje (até acabar o dia de Londres ela continua a principal e não vai para Visitas passadas — finishedToday); senão a atual/próxima, ou a última concluída. A barra abaixo de Team mostra a maleta, dia, horário, duração e funcionários, sem o nome do serviço; ao abrir os detalhes, o tipo de serviço aparece em um widget próprio no corpo dos detalhes (painel à direita no desktop, expansão no celular), sem ocupar o título. Data, serviço e equipe identificam a visita; seleções explícitas e links antigos não trocam de tarefa sozinhos. Histórico de visitas ordena as visitas atuais/futuras da mais próxima para a mais distante; passadas e canceladas ficam em grupos separados, recolhidos por padrão, da mais recente para a mais antiga. A busca abre os grupos com resultados. Guarda as outras conversas, inclusive visitas simultâneas, com busca e não lidas; o texto do Manager não recebe cartões de grupos. O cliente vê só as duas entradas; a funcionária abre a visita relevante numa única linha por cliente. Os canais por tarefa e seus vínculos históricos permanecem separados, sem copiar mensagens entre visitas. Mensagens retidas e não lidas contam junto a Equipe; liberar continua na própria mensagem. O canal direto não mostra o painel “WhatsApp routing” nem oferece substituição manual do destino da próxima mensagem recebida. O conteúdo do Team (JOB) fica no app, inclusive mensagens agendadas, liberações e avisos de atraso. Ao escolher Enviar link do app pelo WhatsApp no menu da mensagem, a gerência libera a mensagem no app se ela estiver retida e envia ao cliente um convite com o link curto para abri-la. Com a janela de 24 h fechada, o mesmo convite abre no WhatsApp Business para envio manual. O aviso é publicado na visita mesmo sem dispositivo de push cadastrado. A fila do WhatsApp descarta envios pendentes legados do Team e preserva as mensagens no app. A confirmação de reserva segue as preferências de envio e, quando vai pelo WhatsApp, fica na conversa da Gerência com o link da visita. Encaminhar da conversa do gestor para o grupo da tarefa continua no menu da mensagem. A ordem é essa mesmo quando a concluída hoje começou depois: uma visita do mesmo dia que nunca começou não passa à frente dela só por ter início mais cedo (teamConversations; caso da Laura Jilow, 2026-11-07, em que o Team abria o grupo vazio das 08:00 e escondia a conversa da visita das 13:00). Na lista do escritório, a linha do cliente mostra a última mensagem de qualquer conversa dele — a mesma pela qual a lista é ordenada —, mesmo quando o toque abre o Manager (AdminClientGroup, previewChannel só com filtro); antes ela dizia “No messages yet…” com a conversa do Team cheia.
Estado actual — acesso da equipe (2026-11-05). Ler a conversa da tarefa exige só estar na escala atual dela (orçamentos e tarefas sem canal de equipe não concedem acesso): lista, histórico, busca, anexos, marcar como lida, tradução e o socket ao vivo valem a qualquer momento. Escrever — enviar, reagir, fixar, agendar, apagar e anexar — só dentro da janela teamChatWindow: de 24 horas antes do início agendado até 24 horas depois da conclusão efetiva; enquanto não concluída, vale o fim agendado (ou início + duração quando não há fim). O servidor recusa a escrita fora dela (canAccessChannelById(..., 'write'), canAccessClientMedia(..., 'write')); /api/channels manda à funcionária writeOpensAt/writeExpiresAt, e fora desse intervalo ServiceChat troca a caixa de texto por um aviso de chat fechado, no lugar dela (crewMayWrite, chat.team.readOnly). Avisos push seguem só dentro da janela. Na ficha da visita a aba dessa conversa chama-se Cliente para a funcionária (Equipe para o cliente e o escritório); fora da escala ela vê o motivo e o caminho para a Gerência. O relay revalida a escala em D1 antes de transmitir a sockets da equipe; uma falha de autorização/banco fecha o socket. Novos anexos de chat usam a subpasta team/{tarefa}/chat; os antigos são identificados por URL indexada (0248). Evidências da visita continuam com sua autorização própria. Essa janela não é a janela de 24 horas da Meta.
Estado actual — Google Contacts na solicitação e na primeira mensagem. O envio de uma solicitação pelo site (chat-initiate, orçamento ou contato) sincroniza imediatamente apenas o lead ou cliente correspondente, após persistir seus orçamentos e endereços, sem esperar uma mensagem WhatsApp. Rascunhos não disparam; falhas do Google não recusam a solicitação. A primeira mensagem WhatsApp recebida com nome disponível dispara a sincronização do cliente ou lead com a conta corporativa, inclusive quando o lead já veio de um orçamento. O fluxo compartilhado (completeIncomingMessage → syncFirstInboundGoogleContact) atende Meta e Chatwoot e executa a gravação em paralelo ao atendimento, após persistir a mensagem; reentregas são descartadas pela ingestão existente. A primeira mensagem nomeada é identificada pela ordem de inserção em todos os canais da pessoa, evitando repetir o envio a cada fala ou por importar histórico antigo. Se o nome inicialmente era apenas telefone, a primeira mensagem posterior com nome passa a disparar. onlyContact reutiliza o formato, os grupos e a correspondência por ID/telefone/e-mail do sincronizador, mas grava apenas aquela pessoa com uma chamada individual, sem alterar o resumo da última sincronização completa. Erros não impedem a mensagem nem o bot, e a sincronização completa periódica permanece como recuperação. O disparo imediato não elimina a demora de propagação do próprio Google até outros aparelhos.
Estado actual — WhatsApp só no app (migração 0282, 2026-11-12). O WhatsApp passa só entre o app e a Meta: a Meta entrega cada evento ao meta-webhook, que grava a mensagem no app, e todo envio (chat, fila, mensagens automáticas, códigos de login, reações, leituras) sai direto pela Cloud API. Nada é copiado, enviado ou recebido pelo Chatwoot: saíram a cópia dos eventos da Meta (chatwoot_forward_queue), o espelho dos envios (messages.chatwoot_mirror), o hub da caixa API (inbox 9, chatwoot_message_links), o transporte Chatwoot, a varredura, e a ficha do cliente no contato do Chatwoot. O Chatwoot (conta 2) fica só para Instagram e Facebook — sem caixa de WhatsApp nem de e-mail (ver Roteamento social): o cartão Chatwoot em Settings → WhatsApp guarda só a URL (https://chatwoot.primecrowncleaning.co.uk) e a conta, gravadas com a página — sem inbox ID e sem teste nem troca de transporte —, e o token e o secret do webhook são segredos do cofre (CHATWOOT_ACCESS_TOKEN, CHATWOOT_WEBHOOK_SECRET; o valor antigo do whatsAppConfig só vale enquanto o segredo não existe); a coexistência (WhatsApp Business no celular) continua, e o eco do que se digita lá chega pela Meta. Mensagens antigas com transport = CHATWOOT ficam no histórico.
Estado actual — autoria do WhatsApp. Mensagens sem autor identificado digitadas no WhatsApp Business aparecem como WhatsApp, pelo eco direto da Meta, inclusive no histórico com os rótulos antigos. Uma assinatura reconhecida conserva o nome do gestor.
Estado actual — mensagem indisponível na Meta. Uma entrada sem conteúdo com erro 131060 mostra que a Meta não disponibilizou o texto e orienta abrir o WhatsApp Business; não é tratada como prova de formato incompatível. Se houver texto no evento, ele é preservado.
Estado actual — coordenação. Histórico, recuperação paginada, envio, drenagem da fila e leitura de canais têm coordenação fora dos hooks, com transportes e estado injetados. Confirmações por socket, ID estável de retry, mensagens concorrentes, escopo da conta/papel/entidade e notificações recebidas durante consultas são preservados. IndexedDB e pontes nativas continuam nos adaptadores; seleção e reconciliação de snapshots usam regras puras.
Estado actual — avisos sobre a tela. Os toasts persistentes de instalação, notificações e atualização aparecem sobre o conteúdo, sem empurrar a lista de mensagens nem redimensionar a conversa. A área ao redor dos cartões continua permitindo interação com a tela; os avisos aguardam enquanto uma janela está aberta.
Caixa focada (2026-11-07, etapa 1). Sem pílula, a lista do escritório mostra só o que precisa de quem olha (inInboxView, src/components/chat/inboxFocus.ts): conversas com mensagem, não resolvidas, assumidas pela própria pessoa (qualquer idade) ou sem responsável com mensagem nos últimos 15 dias. Resolvidas e Assumidas por outros abrem pelo menu de três pontos do topo (nunca uma pílula) e “Back to inbox” volta; a busca procura em tudo o que está carregado; a conversa aberta não some. A espera sem resposta há mais de 15 dias fica na pílula A responder. O selo de Messages não conta conversas assumidas por outro gestor (unreadBadgeCount). O “…” de cada linha só aparece com o foco do teclado — as ações ficam no arraste, no clique direito e no toque longo. No servidor, o escritório deixa de receber conversas vazias (eram 3.701 de 77 com mensagem, 1,6 MB); a revisão do diretório move-se quando uma conversa ganha a primeira mensagem (migração 0261), e ?contact=<id> traz todas as conversas de um contato, vazias inclusive — o controlador da caixa carrega-as ao abrir o contato (seletor Team), o e-mail abre o DIRECT por getOrCreateDirectChannel, e uma conversa trazida assim fica no estado entre recargas (loadedOnDemand). Uma conversa cuja única mensagem é o link de acesso retido (automation = 'accessLink', um cliente esperando no login) continua listada; as outras notas automáticas retidas não listam a conversa — o histórico do escritório não as mostra, e em produção eram 333 conversas assim. Medido em produção com a regra anterior: 410 conversas, das quais 77 com mensagem visível. Um link direto (push, ⌘K) para uma conversa fora da lista busca-a antes de desistir (?channel=<id>, ou o grupo da visita por getOrCreateJobChannel); a conversa aberta não sai do estado numa recarga; os detalhes (janela, app) de uma conversa trazida sob demanda não são zerados pela fase de detalhes, e o POST /api/channels devolve o appReach. A leitura de um contato só lê as prévias e o alcance do app dele. Design: docs/superpowers/specs/2026-11-07-inbox-focus-design.md; a etapa 2 (recorte da regra no servidor) vem depois de medir esta.
Estado actual — caixa de atendimento. A lista exibe todas as conversas ativas por padrão (sem pílula “All”) e disponibiliza três filtros de status específicos: Minhas (atribuídas ao gestor atual), Sem responsável (não lida ou aguardando resposta, sem responsável ativo) e A responder (última mensagem do contato sem resposta da equipe e não marcada como resolvida). Ao selecionar Assumir atendimento no menu de três pontos da conversa, o menu fecha e abre a janela de atendimento. Nela, o responsável pode Marcar como resolvido mesmo depois de responder. A mesma janela permite reabrir uma conversa resolvida como a responder: resolved_at é gravado no canal, e caso o contato envie uma nova mensagem após a resolução, a conversa volta automaticamente a constar como a responder. Nomes, telefone e tarefa continuam na busca. O clique abre a conversa mais recente que corresponde ao filtro, inclusive uma tarefa; limpar filtros restaura a lista. O avatar usa a inicial do contato; quando há responsável atribuído, o badge do gestor assume o local do badge de cliente/funcionário (canto inferior direito) com borda branca discreta (ring-1 ring-white) para não saltar fora do círculo do avatar. Atribuição só aparece após confirmação do servidor; recusas são mostradas na própria ação.
Estado actual — fotos de perfil. ADMIN/MANAGER substituem diretamente a foto de qualquer cliente, lead ou funcionário, incluindo outros gestores, no perfil da pessoa. Cliente e funcionário alteram a própria foto diretamente, sem moderação; somente dados bancários de funcionários dependem de aprovação da gestão. Uma substituição manual cancela propostas PHOTO pendentes e impede sua aprovação tardia. Fotos publicadas aparecem em Pessoas, no próprio perfil e no chat; pedidos antigos de foto pendentes foram cancelados na migração 0242. A migração 0229 acrescenta photo_url a clientes e leads. Upload é autenticado, limitado a imagem JPG/PNG/WebP de até 2 MB e vinculado à identidade que abriu o seletor (câmera frontal ou biblioteca; recorte quadrado ao centro); trocar pessoa/conta descarta retornos tardios. Um boot lido antes da gravação não repõe a foto já aceite: fica a versão mais nova. URLs de fotos atuais são lidas por usuários autenticados, com cache privado desativado; um arquivo que deixou de ser foto publicada não ganha acesso público.
Estado actual — arraste na lista. Passar o rato por uma conversa ou um e-mail não abre as ações laterais. O arraste continua no toque; com o rato, só enquanto o botão está premido.
Estado actual — leitura do e-mail. As ações do cabeçalho usam apenas ícones, com identificação no tooltip e rótulo acessível; o menu de atribuição conserva as opções por extenso. Dentro da conversa, as mensagens aparecem da mais recente para a mais antiga, com novas respostas no topo. O histórico citado das respostas fica recolhido também em emails HTML; o botão “…” permite mostrar e ocultar o conteúdo original, sem alterar o email armazenado. O HTML abre num quadro isolado (sem scripts do remetente) que cresce com a mensagem: um CSS do remetente com altura ou overflow travados não o deixa cortado na primeira medida. Nas mensagens enviadas, o fundo externo do HTML é transparente para acompanhar o box azul, preservando estilos internos e o email enviado ao destinatário. A prévia ignora folhas de estilo; uma prévia já gravada que seja só CSS é refeita a partir do corpo na listagem. Um corpo grande demais para o D1 guarda o texto e o HTML sem imagens embutidas, para a mensagem existir; o original continua no R2 quando o envio o gravou. Todo e-mail tem o seu original no R2 (emails/raw/<ano-mês>/<id>.eml, email_messages.raw_r2_key): o recebido como chegou do relay, e desde 2026-11-11 também o enviado — resposta, encaminhamento, e-mail novo e fatura —, montado por buildSentEml (functions/lib/emailMime.ts) a partir exatamente do que foi entregue ao provedor (HTML e texto do renderEmail, logo e imagens cid:, anexos, Cc/Cco, In-Reply-To/References e o Message-ID que a Cloudflare devolveu; o Resend não devolve um). O D1 guarda os campos que a tela lê (corpos até 60 mil caracteres); o original é a cópia sem perda. A gravação no R2 tenta três vezes (storeRawEmail) antes de a mensagem ficar só com as colunas; um envio nunca falha por causa da cópia. Uma conversa cujo corpo não chegou mostra a prévia que ficou na conversa.
Estado actual — sincronização de e-mails. Lista, detalhe e contador usam cache compartilhado com invalidação do domínio emails, retorno ao foco/reconexão e reconciliação em primeiro plano quando o canal ao vivo está indisponível. A lista percorre páginas com cursor de data+ID. Rascunhos pertencem à conta/papel e conversa; leituras, arquivos e envios tardios não mudam a seleção nem levam conteúdo a outro destinatário. Marcar leitura só zera a contagem se a conversa não recebeu outra mensagem durante a consulta; conversas marcadas explicitamente como não lidas permanecem não lidas mesmo abertas na visualização ativa (?markRead=false). O campo de pesquisa abre resultados em janela flutuante suspensa sem empurrar a lista ou painel inferior.
Estado actual — confirmação de e-mails. Leituras e gravações da caixa nativa recusam respostas de erro da API, inclusive 4xx resolvidos pelo transporte; uma recusa de envio não limpa o compositor como se tivesse sido aceita. Abrir uma conversa consulta somente os anexos das mensagens dessa conversa, sem ler os anexos das outras caixas.
Estado actual — exclusão definitiva pelo admin (2026-10-25). Administradores (ADMIN) podem excluir definitivamente conversas inteiras ou mensagens individuais de e-mail na caixa de entrada nativa, assim como mensagens em canais de chat (sem restrição de janela de 60 minutos nem de remetente). A exclusão realiza hard delete no banco D1 (email_threads, email_messages, email_attachments ou messages) e expurgo atômico de todos os anexos e arquivos correspondentes no Cloudflare R2 (BUCKET), além de desfixar mensagens pinadas. Confirmações utilizam modal não bloqueante (useConfirmation).
Estado actual — sem “marcar como spam” (2026-11-10). A ação manual saiu (menu da conversa, barra de seleção, /api/emails/bulk e o PATCH de status recusam o Spam): marcar não ensinava nada ao filtro, então excluir basta. A pasta Spam continua, só para o que o filtro automático da chegada manda para lá (email-relay: frases de vendedor + IA com 90% de certeza; e as palavras da gravação — cliente ou lead cadastrado nunca), e lá “Não é spam” resgata.
Estado actual — e-mail apresentado como num cliente nativo (2026-11-10). Um e-mail encaminhado aparecia só com os anexos: ao receber, o servidor cortava o “texto citado” antes de gravar, e num encaminhamento (bloco gmail_quote do Gmail, “From:/Sent:” do Outlook) o conteúdo inteiro é justamente esse bloco. Agora o corpo é gravado inteiro (só a linha de prévia deixa a citação de fora), e esconder o histórico citado é escolha da tela: numa resposta ele fica atrás de “•••”, num encaminhamento nunca (emailBodyView, src/shared/emailDisplay.ts; o encaminhamento é reconhecido pelo assunto Fwd/Fw/Enc ou pelo cabeçalho “Forwarded message”/“Mensagem encaminhada”). Mensagens recebidas antes disso (email_messages.body_complete = 0, migração 0269) são relidas da cópia original no R2 e gravadas inteiras uma vez, quando a conversa é aberta (restoreEmailBodies). Cada mensagem é um EmailMessageView: remetente com endereço, Para/Cc, data e ações; a mais nova aberta e as anteriores numa linha (remetente, prévia, data) até serem abertas; corpo em largura total com fonte do sistema; anexos como cartões (ícone pelo tipo, nome, tamanho; imagens com miniatura) e imagens do corpo (cid:) carregadas dos próprios anexos, sem repetir na lista. A lista marca com um clipe as conversas com anexo (hasAttachments, só anexos de verdade, não imagens do corpo). A caixa de resposta fica numa linha (“Responder a …”) até Responder abri-la.
Estado actual — tela inteira para o e-mail (2026-11-10). Saiu a barra de cima: pastas, lista e leitura começam no topo da tela. A busca e o Novo e-mail (ícone de lápis) ficam na cabeça da lista; o primeiro botão dali oculta ou mostra a coluna de pastas em telas largas (lembrado neste aparelho) e, em telas estreitas, abre a lista de pastas; com as pastas fora de vista ele mostra onde se está (“Entrada”, “Prime · Seguro”). As linhas não têm mais caixa de seleção: ⌘/Ctrl/Shift-clique escolhe conversas (como no Mail), e no celular “Selecionar” do menu da conversa começa a seleção; daí em diante um toque escolhe; a linha escolhida fica azul.
Estado actual — simplificação e responder a todos (2026-11-10). Cada mensagem mostra para quem foi (Para e Cc). Responder a todos (na mensagem que teve outras pessoas) preenche o campo Cc da resposta com todos os outros destinatários — nunca as nossas caixas (replyAllRecipients, src/shared/emailRecipients.ts); o Cc pode ser digitado à mão e o servidor agora envia de fato o Cc (antes só gravava) na resposta e no Novo e-mail (SendEmailOptions.cc, Cloudflare e Resend). A busca procura em todas as pastas da conta aberta (ou de todas), menos Spam e Lixeira, e o título vira “Resultados da busca”. Ficou mais simples: o cabeçalho da conversa mostra só Responder, Encaminhar, Concluir, Mover e Lixeira, e o resto (estrela, spam, assumir, perfil, WhatsApp, orçamento, vincular cliente) fica em Mais, que é o mesmo menu da conversa; o menu suspenso de “assumir” do cabeçalho saiu (EmailAssignmentControl), ficou o modal. Nas linhas, não lida é um ponto azul com assunto em negrito, a etiqueta da conta só aparece em Todas as contas e o selo “Client:” saiu. “Todos os e-mails” deixou de ser pasta (a busca cobre); “Abrir conversa” e “Copiar endereço” saíram do menu.
Estado actual — contas como pastas (2026-11-10). Como no Mail da Apple, as caixas (contas) ficam dentro da lista de pastas e não mais em abas no topo: primeiro Todas as contas (Entrada, Com estrela, Enviados, Concluídos, Spam e Lixeira de todas juntas), depois uma seção por conta (Prime Crown, Prime, Crown) com as pastas fixas e as pastas próprias daquela conta (email_folders.mailbox, migração 0268; o nome é único por conta). Cada seção recolhe pela seta (lembrado neste aparelho) e cria pasta pelo ícone ao lado do nome. Uma conversa só entra em pasta da própria conta (o servidor recusa 409 FOLDER_OTHER_MAILBOX; “Mover para…” só oferece as pastas da conta, e numa seleção de contas diferentes só Entrada e Concluídos). O título mostra onde se está (“Prime · Seguro”), Novo e-mail já vem com a conta aberta, e a leitura usa toda a largura: cada mensagem ocupa a coluna inteira, uma abaixo da outra, sem balões alternados.
Estado actual — pastas e gerenciamento de e-mails (2026-11-10). A central de e-mail funciona como um cliente de e-mail: à esquerda a lista de pastas (EmailFolderList; em telas abaixo de 1024 px abre pelo botão com o nome da pasta), no meio as conversas e à direita a leitura. Pastas fixas: Entrada (abertas e respondidas fora de pastas próprias), Com estrela, Enviados (toda conversa em que escrevemos), Concluídos (resolvidas), Todos os e-mails, Spam e Lixeira; abaixo, as pastas do escritório (email_folders, migração 0267), criadas, renomeadas e excluídas ali mesmo. Uma conversa fica em um lugar só (emailPlaceOf, src/shared/emailFolders.ts): Spam/Lixeira, senão a pasta própria, senão Entrada ou Concluídos pelo status; estrela e Enviados são vistas, não lugares. E-mail novo numa conversa de pasta própria ou concluída a traz de volta para a Entrada (ingest limpa folder_id), para nada novo ficar escondido. Excluir uma pasta não apaga e-mail: as conversas voltam para Entrada ou Concluídos. Gerenciamento: caixa de seleção em cada linha (no celular aparece depois do primeiro “Selecionar” do menu da conversa) e a barra de seleção (lida/não lida, estrela, Concluir/Entrada, Mover para…, Spam, Lixeira); o menu e o cabeçalho da conversa têm Estrela, Concluir/Mover para a Entrada e Mover para…. Tudo passa por POST /api/emails/bulk (até 50 por chamada; a tela divide), com a mesma regra de movimento (emailMoveWrite) na tela e no servidor; a lista lê ?folder= (emailFolderCondition) e as contagens por pasta vêm de /api/emails/stats (places, por caixa; o número ao lado da pasta é de não lidas).
Estado actual — encaminhar e-mail (2026-11-09). Cada mensagem da conversa (recebida ou nossa) tem Encaminhar ao lado da hora. Abre o formulário de novo e-mail em modo encaminhamento: a caixa de saída é a da mensagem original (fixa), o assunto vira Fwd: … (nunca Fwd: Fwd:), o texto é uma nota opcional e, abaixo dela, aparece a mensagem original inteira como o destinatário a lerá (ForwardedMessagePreview: cabeçalho “Forwarded message” e o corpo HTML completo); os arquivos da original entram como etiquetas de anexo, cada uma com X para tirar (imagens inline sempre seguem); também se podem anexar arquivos novos. O servidor (POST /api/emails/messages/:id/forward, ADMIN/MANAGER) monta o e-mail por renderEmail (modo mínimo, agora com block): nota + assinatura, depois o cabeçalho “Forwarded message” (de, data em Londres, assunto, para) e o corpo original (forwardedMessageBlock, functions/lib/emailForward.ts, sem <script>). Os arquivos são lidos do R2; se um marcado sumiu, recusa 409 ATTACHMENT_UNAVAILABLE sem enviar nada. O encaminhamento vira uma conversa nova com o destinatário (como Novo e-mail: OPEN, assumida por 30 min por quem enviou), para que a resposta dele caia ali, e guarda cópia própria de cada arquivo — apagar a mensagem original apaga os arquivos dela.
Estado actual — e-mail no aplicativo do celular (2026-11-11, em construção). A central de e-mail é servida a aplicativos de e-mail (Mail do iPhone, Gmail, Outlook) por um servidor no Oracle (mail-bridge/, mail.primecrowncleaning.co.uk, IMAP 993 e SMTP 465 com TLS) que não guarda e-mail: tudo passa por /api/mail-bridge com MAIL_BRIDGE_SECRET. Quem entra é um admin ou gerente ativo com uma senha de app criada no Perfil → Login e segurança (MailAppPasswordsSection; 20 letras, mostrada uma vez, guardada como SHA-256 em mail_app_passwords, revogável; nunca a senha de login). As pastas seguem o padrão IMAP pelo uso especial (o celular reconhece a marcação, não o nome): INBOX; Drafts (\Drafts) por pessoa — o que o celular salva enquanto escreve, guardado como o .eml que ele mandou (mail_drafts, R2 emails/drafts/<pessoa>/), só do autor, apagado quando o celular apaga (depois de enviar); Done (\Archive, o Arquivar do celular, com o nome da tela); Sent (\Sent); Spam (\Junk); Trash (\Trash). As três caixas (primecrowncleaning, primeldn, crownldn) ficam numa conta só, como o All accounts da tela: a resposta sai pela caixa da conversa; num e-mail novo o remetente é o endereço escolhido no celular (o iPhone aceita os três endereços na conta). Pelo emailPlaceOf: INBOX, Done e cada pasta do escritório (listada sob a sua conta, Prime/Quotes) com as mensagens recebidas da conversa; Sent com o que escrevemos; Spam e Trash com a conversa inteira. O lido é o unread_count da conversa (as N recebidas mais novas ficam não lidas), a estrela é a da conversa. Cada mensagem tem um UID estável por pasta (imap_uids, novas sempre maiores; imap_folder_state). Ler, estrelar e mover passam por applyEmailThreadAction, a mesma regra do /api/emails/bulk; apagar no celular move para a Lixeira — também quando o aplicativo apaga copiando para a Lixeira (COPY, como o Spark faz): a conversa muda de lugar no app —, e só um admin apaga de vez, na Lixeira. Toda mensagem é um .eml real com tamanho conhecido: o original do R2, ou — num enviado antigo — montado uma vez por buildSentEml a partir das colunas e guardado (email_messages.raw_size). mail_revision (gatilhos nas conversas, mensagens e pastas) avisa o servidor que algo mudou.
Estado actual — conversa só nossa fica em Enviados (2026-11-11). Como em qualquer cliente de e-mail, uma conversa em que só nós escrevemos — Novo e-mail, encaminhamento, fatura, e-mail novo pelo celular — fica só em Enviados (email_threads.only_ours, migração 0281; emailPlaceOf devolve sent, e a consulta da lista e as contagens tiram-na do Inbox e de Done). Entra no Inbox quando o outro lado responde (a entrada desliga a marcação) ou quando alguém a move à mão (Inbox, Done ou uma pasta: emailMoveWrite devolve onlyOurs: false). Spam, Lixeira e uma pasta do escritório continuam a valer antes dela. A migração marcou as conversas existentes que não tinham nenhuma mensagem recebida.
Estado actual — spam, lixeira e retenção de e-mails (2026-10-26). A caixa de e-mails inclui as pastas Spam e Lixeira (migração 0235_email_threads_spam_trash.sql), isoladas da listagem principal (ALL, OPEN, REPLIED, RESOLVED) e das contagens de mensagens não lidas (totalUnread). Na ingestão (/api/emails/inbound), mensagens com cabeçalho X-Prime-Spam do relay ou palavras-chave de prospecção comercial (SEO, marketing, backlinks, etc.) de remetentes desconhecidos são gravadas com status SPAM e unreadCount = 0, sem emitir notificações push para a equipe; clientes e leads cadastrados nunca são marcados como spam. O remetente, assunto e a caixa original (X-Prime-Original-To) são sempre preservados. Na interface, qualquer usuário autorizado (ADMIN ou MANAGER) pode excluir/mover conversas para a Lixeira (status = 'TRASH') e restaurá-las para a caixa de entrada (“Não é spam” / “Restaurar”). A exclusão definitiva manual é restrita exclusivamente a administradores (ADMIN) dentro da Lixeira, sendo bloqueada na API para conversas fora dela. Conversas na Lixeira ou Spam exibem aviso de remoção automática após 30 dias. O housekeeping semanal (functions/api/cron/housekeeping.ts) expurga automaticamente do D1 e do storage R2 todas as conversas com status TRASH ou SPAM cujo updated_at tenha mais de 30 dias. Administradores podem esvaziar a lixeira imediatamente via DELETE /api/emails/threads?action=empty_trash.
Estado actual — caixa de e-mails nativa. As três caixas de e-mail das marcas de limpeza (Prime Crown info@primecrowncleaning.co.uk, Prime info@primeldn.co.uk e Crown info@crownldn.co.uk) são agrupadas na visão EMAILS do painel de gestão (migração 0232_email_inbox.sql). As mensagens são agrupadas em conversas (email_threads) por cabeçalhos RFC (Message-ID, In-Reply-To, References) ou assunto normalizado com remetente, vinculando automaticamente a clientes (clients.email) ou leads. O compositor envia respostas pela caixa da marca correspondente mantendo a árvore de referências para encadeamento nos clientes de e-mail externos. A caixa compartilha os mesmos selos visuais de Messages: selo esmeralda de não lidas com hora em destaque verde, badge de responsável com a inicial do gestor no canto inferior do avatar (ConversationAvatar) e botão de atendimento no cabeçalho da conversa (EmailAssignmentControl). O atendimento suporta assunção manual com períodos (30 min, 1h, 2h ou indefinido) via modal/janela (EmailAssignmentModal), desatribuição e resolução, além de take over automático de 30 minutos quando um gestor envia uma resposta (ou mantém indefinido se já era seu sem prazo; migração 0233_email_thread_assigned_until.sql). Ao receber um novo e-mail (/api/emails/inbound), o sistema despacha notificações push (notifyEmailInbound) para os gestores e administradores; caso a conversa possua um gestor atribuído com atendimento ativo, o push é enviado exclusivamente a ele para evitar ruído. Ao clicar na notificação push, o app abre diretamente na conversa de e-mail correspondente.
Janela de 24 h na atualização leve (2026-11-06). A mensagem do cliente pelo WhatsApp reabre a janela onde quer que chegue: no WebSocket da conversa aberta e também na atualização leve da lista (since), que só traz prévias e não lidas (applySessionWindowFromPreview em channelState.ts, regra opensSessionWindow). Antes, quando a mensagem chegava pela lista, a barra de escrita continuava trancada até o passe completo de 5 minutos ou um F5 (caso da Dina). Prévia, ordem e cursor de leitura continuam os do servidor; uma mensagem antiga não reabre nem encurta a janela.
Estado actual — histórico e desempenho. O histórico abre nas últimas 20 mensagens e permite carregar as anteriores sem perder a posição de leitura; o cursor inclui data, sequência e ID, sem saltar mensagens do mesmo segundo. Atualizar preserva páginas antigas já carregadas. A busca consulta o servidor, oferece mais resultados e mostra até 30 mensagens de contexto de cada lado do resultado escolhido; fechar restaura a conversa corrente. A recuperação por WebSocket/polling percorre todas as páginas contra a mesma marca de sincronização e recupera recibos e traduções alterados; o WebSocket conecta em paralelo ao histórico e preserva mensagens recebidas durante a leitura HTTP. O catch-up aguarda esse snapshot para evitar uma consulta duplicada. Ao perder o WebSocket, o polling em primeiro plano começa imediatamente e repete a cada 5 segundos, cessando quando a conexão reabre. Ping/pong sem acordar o Durable Object detecta conexão travada; handshakes têm limite de 8 segundos e a reconexão usa jitter. Leituras simultâneas do mesmo histórico são reunidas, e o cache descarta conversas antigas inativas acima de 20, preservando as observadas e envios pendentes. A caixa continua entregando todos os canais exigidos pelos badges e seletores, mas suas prévias usam buscas indexadas da última mensagem em vez de classificar todo o histórico (migração 0228); a rota social lê somente a última mensagem recebida de cada canal e a janela WhatsApp ignora histórico anterior às últimas 24 horas. A caixa carrega em três fases autorizadas: identidades sem ler mensagens; depois só a última mensagem e as não lidas das conversas que as têm (uma conversa já lida não fica em “Loading messages”, e o cadastro não volta a ser descarregado); por último a janela de WhatsApp e os outros detalhes, também só onde diferem do silêncio, sem segurar a prévia. Uma actualização seguinte repete a prévia, não o cadastro; o cadastro volta imediatamente quando sua revisão durável muda (migração 0247), inclusive em alterações no mesmo segundo e exclusões, sem percorrer os carimbos de todos os cadastros. Essa revisão só se move quando muda um campo que a caixa mostra (nome, alias, foto, telefones e grupo do cliente; nome, alias, foto e celular do funcionário; nome, foto, telefones e fusão do lead; dia, horário, serviço, estado, conclusão, duração e equipa da visita; e os campos do canal, incluindo reopened_at) — nunca numa gravação que deixa o valor igual nem na criação de uma linha sem conversa (migração 0260). Antes, qualquer gravação nessas tabelas (preenchimento de série, preço, geocódigo, carimbo de auditoria) fazia cada sessão aberta do escritório reler o cadastro inteiro duas vezes; essa leitura era a consulta mais pesada do D1 e o deixava sobrecarregado (D1 DB is overloaded), atrasando mensagens do WhatsApp e a janela de 24 h na tela (caso do Alex, 2026-11-07). Uma caixa larga lê as prévias numa única consulta, sem descarregar nomes e telefones de novo; a última linha é a cabeça gravada na conversa (escritório e cliente), e o contador de não lidas busca o intervalo indexado de sequência de cada conversa para quem lê. A fase de detalhes não repete essas leituras. Uma revisão chat, sem conteúdo ou IDs, avisa os clientes conectados; rajadas são reunidas numa releitura que pede somente as conversas alteradas desde a revisão devolvida pelo servidor (since), incluindo exclusões, transferências, edição, liberação de retidas e leituras em outro aparelho. Uma conversa esvaziada vem explicitamente para limpar a prévia; mensagens recebidas pelo socket não avançam essa revisão. A marca é lida antes dos dados para não saltar alterações concorrentes. A passagem de cinco minutos e a retomada do foco leem só as prévias alteradas desde a revisão da caixa (since) e um passe de detalhes que não relê o cadastro (lean=1: janela, retidas, alcance do app por contato e rotas); puxar para atualizar é que relê a prévia inteira. Se uma releitura leve já estiver em andamento, a reconciliação conserva sua fase de detalhes. APIs de canais e mensagens expõem duração em Server-Timing.
Estado actual — tradução após gravar. A mensagem original e sua pendência de tradução são gravadas atomicamente pelo trigger messages_queue_translation (message_translation_jobs, 0228). O envio confirma a gravação sem esperar pela IA; a tradução chega pelo evento translations. O cron retoma trabalhos interrompidos, com uma reserva temporária por mensagem. Mensagens da equipe continuam HELD até existir inglês confiável e as regras de liberação permitirem; a tradução em segundo plano nunca libera uma conversa já fechada. Recibos, autorização e idempotência de envio permanecem obrigatórios.
Estado actual — Chat do cliente (2026-10-21). A hora de uma mensagem é sent_at (quando saiu), senão created_at (messageSentAt, src/shared/chatSentAt.ts) — nunca delivered_at: numa mensagem do app esse é o momento em que o aparelho do cliente a recebeu ou ele abriu a conversa, e a bolha mostrava 17:08 numa mensagem das 10:00 (a lista já mostrava 10:00). As caixas de conversa (ServiceChatMessage, ImageAlbum, ChatDaySeparator) usam visual nativo mobile moderno com raio dinâmico de sequência (rounded-[18px] com 3px na ponta do primeiro item e 6px nos seguintes, sem caudas triangulares artificiais de CSS), espaçamento interno ergonómico (px-3.5 py-2), tipografia com entrelinha relaxada, sombra suave (shadow-xs), largura máxima de 86% no telemóvel e pílulas de data centradas. URLs em texto (splitTextByUrls, LinkifiedMessageText) são transformadas em links clicáveis seguros (handleExternalAnchorClick) com break-all e [overflow-wrap:anywhere]; os contêineres de mensagens usam min-w-0 e max-w-full em todas as camadas de flexbox para impedir que URLs longas estrapolem o limite da bolha. O lado da empresa chama-se Manager em todas as telas (MANAGER_LABEL, chat.peer.manager: cartão da lista, topo da conversa, seletor; Gerência em pt-BR), e o cartão diz “Bookings, billing and anything else — a manager answers here” (antes prometia um gerente dedicado e que só ele lia). A tela abre com o título Messages, com as entradas fixas Manager e Team; a equipe da visita e o histórico seguem o Estado actual acima. O app do cliente guarda só duas semanas de visitas concluídas, então /api/channels manda em cada conversa de tarefa o dia e o estágio da visita (requestStart, requestStatus). Cada conversa de tarefa do cliente mostra “Sun 25 Oct · Standard Cleaning” e, no avatar e no chip de hora, quem vem (“09:00 · Ana”, jobThreadPresentation; antes, a inicial do dia da semana, igual para sábado e domingo). Nenhuma etiqueta automática marca mensagens por palavras (chave, código, animal…); o que importa a equipa fixa à mão (Pin). Para a faxineira, o seletor no topo de uma conversa de visita diz Client (Cliente) em vez de Team: ali ela fala com o cliente (ChatConversationSwitcher, viewerIsCrew). Um link de pagamento nosso (/pay/<código>) numa mensagem abre a página de pagamento como uma camada sobre o app, como em Bills (inAppPayCode, LinkifiedMessageText → InvoicePayLayer, na pilha de janelas: X, Esc e Voltar fecham só a camada). Antes abria uma janela nova no PWA e depois navegava para /pay: ao fechar, o app arrancava de novo, como um refresh completo (2026-11-09). Links de outros sites continuam fora. O aviso de notificações (ChatPermissionBanner), fechado no X, não volta por 3 dias neste aparelho (preferência de tela); perder um push que funcionava traz o aviso de volta.
Estado actual — consumo e digitação. O chat não transmite nem exibe presença de digitação (migração 0218); o WhatsApp também não simula digitação/gravação nem espera artificialmente antes de enviar (0219 limpa a configuração). Permanecem leitura, recibos, limites e segurança de envio. O ChatOps fechado lê somente contadores, carregando as três listas ao abrir; apenas fila em andamento usa atualização rápida. Saúde WhatsApp compartilha consulta entre barra e Settings. Canais têm contexto separado das mensagens. Xero usa intervalo rápido apenas pendente; VAT confirmado encerra o intervalo; visita, histórico e auditoria usam eventos existentes, foco e reconciliação de cinco minutos. No idle só aquecem destinos frequentes em conexão adequada; os demais mantêm preload por intenção. O iframe Chatwoot permanece montado para preservar sessão e rascunhos. Resumos IA mantêm suas regras e não leem configuração sem conversas elegíveis.
Preferências e cobrança do cliente. O aviso de fatura com saldo em aberto no app começa desligado. Em Configurações → Mensagens → Mensagens automáticas, o escritório pode ativá-lo e personalizar seu texto com {number} e {amount}. As mensagens enviadas manualmente chegam pelo fluxo habitual; check-in/out são opções separadas, desligadas por padrão. Cash/conta do funcionário não gera aviso de emissão. A confirmação explícita “não recebi” (NONE) cria nota interna do Bot para a gestão cobrar pelo WhatsApp; “não confirmado” não solicita cobrança. O dashboard e a área financeira do funcionário compartilham a lista de tarefas concluídas aguardando recebimento: Lembrar cliente grava aviso no app do cliente e nota interna no chat principal para o manager, sem enviar WhatsApp automaticamente; um cadeado bloqueia novos lembretes da mesma tarefa por 24 horas corridas, inclusive em outro aparelho. Confirmar recebimento registra valor e método pela mesma operação financeira usada pelo Cash check do manager. Uma baixa aceita retira a tarefa de aguardando recebimento nas duas vistas; recebimento parcial mantém o saldo restante, e dinheiro efetivamente com a equipe continua no controle de valores retidos. Recibos e lembretes repetidos não duplicam os registros; lembretes nunca registram dinheiro. O último lembrete mostra data e autoria na lista da funcionária e no resumo financeiro da tarefa; o chat e a auditoria existentes conservam o histórico. “Já paguei” abre o fluxo de mensagens com a gestão a partir da fatura, com o relato identificado pela referência e anexos no próprio chat; não confirma recebimento. Divergências usam as confirmações e notas existentes: cliente diz que pagou ou outra pessoa recebeu ficam não confirmadas e avisam a gestão; valor parcial/excedente continua no registro de valor recebido. O cartão financeiro do dashboard agrega o saldo aguardando coleta por funcionário e idade, com acesso ao Cash check, sem misturar com dinheiro já retido pela equipe.
O resumo de Messages no Dashboard lê as mensagens do último dia (desde a meia-noite de Londres ou as últimas 24 h, o que vier antes) em páginas de 500, para Equipe falando com clientes e Hoje; quem está esperando vem da contagem do banco (abaixo). A agregação mantém estado por conversa e funcionário, sem guardar o histórico inteiro em memória. A paginação usa data normalizada, sequência de leitura e ID, com limite de inserção capturado no início: novas mensagens entram na próxima atualização. O índice da migração 0171 atende essa leitura sem ordenar todo o histórico. Testes locais cobrem 300 clientes, 30 funcionários, mais de 4.000 mensagens recentes, cursores antigos nulos e chegadas durante a paginação; isso não substitui homologação de carga concorrente em produção.
Estado actual — acesso ao Chatwoot. O app não abre o Chatwoot: o item Chatwoot do sidebar, o painel à direita, o login automático (/api/chatwoot/sso, /api/chatwoot/desk, os segredos CHATWOOT_PLATFORM_TOKEN/CHATWOOT_ADMIN_TOKEN) e o proxy chat.primecrowncleaning.co.uk (Worker chat-redirect) foram removidos em 2026-11-11. Quem usa o Chatwoot entra direto em chatwoot.primecrowncleaning.co.uk (o mesmo servidor do Oracle), com o seu login. O painel do Prime Crown dentro do Chatwoot (chatwoot-panel.html) continua. As notificações do Chatwoot dentro do app foram completamente removidas: o app não dispara Web Push, não cria toasts em tela, não insere registros na central de notificações (notification_history), não possui categoria CHATWOOT em preferências/filtros e não exibe badge no menu lateral. O webhook do Chatwoot só trata Instagram/Facebook; os eventos das outras caixas (e-mail, a antiga caixa WhatsApp) são apenas reconhecidos (200 OK) — chatwootDeskAlert só decide isso — e o cron não sincroniza alertas de SLA do Chatwoot. O WhatsApp fica só no chat do app. Categorias essenciais de notificação são obrigatórias e não podem ser silenciadas nem desativadas em push: INCIDENT e SYSTEM para o escritório e o cliente, CHAT para ADMIN, MANAGER e cliente, FINANCIAL para o cliente. A funcionária não escolhe: o Profile lista só os avisos que ela recebe (mensagens, visita nova, sem check-in, holerite e a decisão de foto, banco ou endereço) e todos ficam ligados, sem som, duração nem interruptor. O escritório e o cliente mantêm os controles de Push e Inbox por categoria, com subitens recolhíveis, no Perfil; a aba de Configurações retém o aviso público do sistema e direciona ao Perfil. Na página de notificações (NotificationsPage), os filtros foram simplificados com controle de status direto (Todas vs Não lidas) e pílulas de categoria em linha única exibidas apenas para categorias com itens ativos no escopo. A instalação é partilhada (Caraíva id 3, Crown London id 4) e não muda de marca.
Estado actual — linha. O compositor já não oferece um catálogo de templates: a mensagem ao cliente sai pelo evento em Automatic messages, ou como texto livre dentro da janela de 24 h. A linha é a Meta Cloud API, direto do app (o transporte Chatwoot saiu na migração 0282). O gateway Evolution (sessão não oficial do WhatsApp Web) foi removido em 2026-11-09 (migração 0266): webhook, conexão por QR, política anti-ban, presença, checagem de número, @lid, chamadas, recuperação de mensagens e sonda E2E saíram do código; a fila que ainda esperava por ele virou falha visível em Failed Sends. Linhas históricas com provider = 'EVOLUTION' continuam no banco e nunca são liberadas nem contadas como da Meta. Ao abrir Inbox/Chat, o ChatPermissionBanner também verifica o desbloqueio de som (sound_confirmed + preferência soundEnabled): se faltar, o mesmo PromptToast do push pede Ativar som e o toque corre confirmSoundUnlock (tom + marcador), sem reabrir o gate fullscreen.
Estado actual — envio e recibos. Mensagens ao cliente: ver Mensagens automáticas abaixo. O compositor não oferece templates: com a janela fechada, o atalho é o WhatsApp Business no celular. A avaliação pós-limpeza e a fatura por WhatsApp escolhem o número como qualquer resposta: whatsapp_phone primeiro, depois mobile_phone e phone (antes a avaliação só saía com phone preenchido e a fatura ignorava o número do WhatsApp). Na Cloud API a Meta responde sent quando aceita e failed depois, quando não consegue entregar (130497 país restrito, 131026 sem WhatsApp, 131047 janela fechada); o recibo failed depois de sent agora retira o tick e estaciona a mensagem em falhas com o motivo da Meta — antes era tratado como replay velho do Evolution e a bolha ficava num tick só. Só entrega ou leitura vencem uma falha.
Estado actual — citação e reação. Uma resposta citada no app sai como citação nativa no WhatsApp pela Meta (context.message_id) — para texto, foto e áudio, e também quando a mensagem sai depois pela fila (replyToId → loadQuoteTarget). Reações feitas no app sobre uma mensagem wamid. saem direto pela Graph API (metaSendReaction, da linha da própria mensagem); a reação do cliente chega pela Meta e vai para a mensagem reagida (handleIncomingReaction), nunca como mensagem. O aviso dessa reação nomeia a pessoa (alias ou nome da ficha, ou o dono da conversa), não WhatsApp seguido do número. O que a equipa digita no app WhatsApp Business do celular (coexistência) chega como eco da Meta (metaEcho.ts). Se a mensagem contiver uma assinatura de gestor no início (ex.: Manager - Claudia: ... ou Manager Claudia: ...) ou no fim (ex.: ... \nManager - Claudia ou ... \nClaudia - Manager), o Prime Crown identifica o gestor ativo correspondente (por alias ou nome, resolvePhoneAppAuthor), grava a autoria diretamente em seu nome (senderId, senderName), assume o atendimento (takeOverOnStaffReply por 30 minutos) e emite a notificação com a sua autoria; se não houver assinatura válida ou correspondente a um gestor ativo e desbloqueado, grava genericamente como “WhatsApp” sem transferir o atendimento. A mensagem vai para o grupo da tarefa quando responde (cita) uma mensagem de um grupo em aberto do mesmo cliente; sem citação, no DIRECT.
Estado actual — grupo e inbox. No chat do detalhe de uma tarefa, o escritório tem a conversa do cliente, uma aba por funcionário escalado e o Team da tarefa; cada aba de funcionário reutiliza o DIRECT desse funcionário com a gestão, incluindo o histórico da Inbox, sem criar uma conversa por tarefa. A funcionária vê somente Manager (seu próprio DIRECT com a gestão) e Team; nunca o DIRECT do cliente ou de outra funcionária. Grupo em aberto é uma regra só (isOpenJobChannel): não trancado e tarefa agendada/em andamento, ou concluída há menos que o prazo de acesso (closeWindowHoursAfter, 24 h) contado de completed_at (migração 0154, gravado na transição para DONE; updated_at mudava a cada edição posterior e reiniciava o relógio); qualquer outro status fecha. Vale para a pergunta “para quem é”, para a resposta citada do cliente, para respostas do celular e para o trancamento automático (que só tranca DONE — uma cancelada pode voltar a agendada e nada destranca o grupo). A pergunta “para quem é”: ver Mensagens automáticas. A mesma regra (nearestTasks, src/shared/nearestTasks.ts) curta a lista da Inbox: ao abrir um cliente aparecem o Manager e só as duas tarefas mais próximas de agora — mais a que está aberta no ecrã e as que têm mensagens por ler — com “+N more tasks in Team”; todas continuam no menu Team da conversa (ChatConversationSwitcher). o toque volta como o título e parseRouteSelection o reconhece, inclusive com rótulos renomeados. Histórico do app e reenvios pela fila levam as opções numeradas, que continuam aceitas. A única pergunta de resposta fixa que resta é a avaliação pós-limpeza do template original (Excellent/Good/Could be better → nota 5/4/3, lida em botChoices.ts; só a nota 5 recebe o link do Google); a versão v2 abre a avaliação no app.
Uma resposta numérica só escolhe a tarefa do menu exato guardado com a pergunta; se esse retrato faltar ou estiver inválido, a mensagem permanece no DIRECT, sem reinterpretar “2” pela tarefa aberta hoje. A escolha só confirma a pergunta cujo ID foi lido, não uma pergunta nova que chegou entretanto; um envio tardio do bot não reabre a escolha já feita pelo gestor. Um menu enfileirado, falhado ou cujo envio foi retirado não aceita escolhas antes de ter sent_at; a fila deixa de tentar entregá-lo após uma hora, quando a sessão já não teria resposta válida. Quando o gestor escolhe Automático ou um destino explícito, a mesma transação cancela os menus de roteamento ainda na fila desse cliente (CANCELLED, sem alarme de falha de entrega); um envio que só ficou enfileirado depois também é cancelado quando tenta guardar o menu. O link do app e outras mensagens não são cancelados por essa troca. O contexto repassado ao TEAM usa esse mesmo ID de pergunta e termina antes da mensagem que iniciou uma pergunta posterior, mesmo que o envio posterior ainda não tenha gravado a sua sessão; não mistura o assunto privado seguinte no grupo. Mesmo uma escolha TEAM já guardada só encaminha para um grupo ainda aberto cujo canal e tarefa pertencem ao mesmo cliente.
Estado actual — leitura e voz. O status da Meta mostra is_on_biz_app (coexistência). A bolha do chat traduz para o idioma do Perfil (useT / user.language), não o preferredLanguage antigo da ficha do funcionário. Um contato autenticado vê e abre os canais DIRECT/JOB de todos os locais do seu grupo; o Worker aplica o mesmo escopo na lista, criação e em cada sub-rota do canal. Uma nota de voz sai como áudio nativo do WhatsApp (voice: true na Meta, ficheiro audio/ogg), não como arquivo. Anexos de vídeo (.mp4, .mov, .m4v, .avi, .mkv, .3gp) no chat são reproduzidos diretamente na bolha da conversa por um player nativo de vídeo (<video controls playsInline>), e citações/prévias de conversa exibem o rótulo ‘🎥 Video’ / ‘🎥 Vídeo’ (chat.label.video); apenas formatos estritamente sonoros (.ogg, .oga, .mp3, .m4a, .webm, .wav, .aac) são tratados como notas de voz / áudio. Mensagens da equipa saem exactamente como foram digitadas; o Polish do compositor é só sob pedido. A tradução cliente→pt-BR segue o modelo configurado e a regra de reserva.
Estado actual — entrega e sessão. Cron do chat-do autentica com CRON_SECRET. Se duas entregas simultâneas da mesma mídia passam pela leitura de deduplicação, só a vencedora do índice de mensagem conserva o objeto R2; a cópia aleatória da perdedora é apagada. No retorno do segundo plano, falha de rede ao carregar o histórico não impede a reconexão e sua busca de mensagens perdidas; uma sessão encerrada nunca retoma esse transporte. Ações da bandeja Android e da PWA levam o dono original até a mutação; se o cookie WebView/service worker já pertencer a outra conta, o servidor recusa a ação (409) antes de enviar, marcar leitura ou alterar o sino. Em logout ou revogação, a audiência Android começa a ser removida antes da requisição de saída e a PWA descarta publicações assíncronas antigas; limpeza tardia fecha somente banners do usuário que saiu, nunca os da conta nova. Uma escolha do menu de roteamento pendente é uma transição condicional única e atômica com sua auditoria: só a primeira resposta válida pode transferir contexto, confirmar e fixar DIRECT/JOB; redelivery posterior apenas preserva o transcript privado. Desativação, bloqueio, exclusão e mudança de cargo revogam sockets existentes; para gestores, a revogação inclui canais sem participação explícita e força todos os seus espectadores a reconectar pela autorização atual. Avarias de WhatsApp (healthAlerts.ts) entram na barra única do shell; um meta.error não gera um segundo cartão de webhook; a folha mostra a hora de Londres da última leitura.
Ao abrir um DIRECT pela Inbox, a resposta tardia da criação não substitui uma conversa escolhida depois nem reabre a seleção da conta anterior. No chat do detalhe da tarefa, falha ao ler o histórico ainda inicia a recuperação em tempo real; trocar DIRECT/JOB ou a identidade autenticada encerra o transporte anterior antes de iniciar o da seleção atual. Em estado offline na web, o networkProvider sonda /api/ping periodicamente e na volta de visibilidade para recuperar de falsos estados offline do navegador; falha transitória na leitura inicial de canais (useChannels) faz nova tentativa em 4 s sem aguardar o ciclo de 5 minutos.
Mensagens automáticas (Settings → WhatsApp → Automatic messages)
Section titled “Mensagens automáticas (Settings → WhatsApp → Automatic messages)”Quem assume a conversa: um gerente ou admin que responde fica responsável por ela durante 30 minutos (quem já era responsável sem prazo continua sem prazo) — takeOverOnStaffReply; vale também para a resposta assinada digitada no WhatsApp Business do celular. A resposta de uma pessoa também pausa as respostas automáticas por 2 h.
Tudo o que o sistema envia sozinho a um cliente é uma entrada de src/shared/automations.ts e passa pela regra única automationMayRun: um bot (quem escreve, a reserva confirmada, o retorno do site) é Off / Test / On; um evento que também tem botão nasce Manual e só sai sozinho em Auto, e aí Off / Test / On. Os que só saem do botão não têm seletor. Test só vale para os números de teste, comparados por dígitos. No WhatsApp, para em metaMonthlyWarningThreshold (padrão 800) para deixar o resto da cota à equipa; as obrigatórias (resposta ao STOP, link de login) passam sempre. A regra é consultada antes do trabalho (checkAutomation, que regista a recusa em system_logs como AUTOMATION_SKIPPED) e de novo na camada de envio (sendBotWhatsApp/sendSystemWhatsApp, que carimbam messages.automation). A cota e o uso por automação vêm de GET /api/automations/usage.
Quando o cliente escreve sai no máximo uma mensagem (replyToInbound, functions/api/whatsapp/inboundReply.ts): nada se uma pessoa nossa lhe escreveu nas últimas 2 h, em qualquer conversa; nada se já saiu uma automática nas últimas 24 h (trava atómica inbound_reply_claims, contra webhooks simultâneos). Quem ainda não é cliente recebe New contact uma vez (página de orçamento; no Instagram e no Facebook o link do orçamento e o wa.me ficam no texto, e um perfil sem telefone também vira lead). Um cliente recebe Who is this for? quando há visita aberta — três botões: Manager, uma visita (a em andamento, senão a próxima, senão a última concluída ainda aberta; com as cleaners pelo primeiro nome) e Open the app (botão de resposta, porque a Meta não junta botões de resposta e de link; o toque devolve o botão do app e a pergunta continua aberta). O toque em Manager ou na visita é a escolha; Manager não tem confirmação, a visita responde com o link /chat/ do grupo dela (Open the group, botão na Meta direta), para o cliente continuar no app, onde o que escreve fica azul e não gasta WhatsApp — o que já tinha escrito vai para o grupo, e escrever pelo WhatsApp ainda chega lá; uma pergunta pendente cai quando alguém da equipa escreve; fora do horário a frase de ausência vai no topo, a Away message fora do horário, ou o App link. As do cliente levam o link do app. Saíram o menu, a IA livre, a confirmação do nome, o agradecimento do e-mail, a resposta a chamadas e o envio automático do widget. No chat do app, a ausência aparece uma vez por dia, só no app, e respeita Test. Qualquer mensagem gerada por automação ou sistema que não seja enviada por usuário humano exibe a legenda unificada Bot (em vez de ‘Prime Crown Assistant’ ou ‘System’).
Link do app: https://app.primecrowncleaning.co.uk/go/<8 base62>, sem parâmetros (issueAccessLink, functions/lib/appLinks.ts, tabela app_links com o hash do código, uso único, 48 h, um vivo por pessoa). Cria a conta a quem está numa ficha e ainda não a tem; um número acabado de conhecer recebe a página de orçamento. O GET /go/<code> só serve o cartão de marca (o robô de prévia do WhatsApp não o gasta); o script faz POST /api/go/consume, que entra (ou não gasta, se já há sessão dessa pessoa), confere que a visita/fatura é dela e, vencido, manda para o login com o telefone. Na Meta directa o link vai como botão cta_url (“Open the app”); pelo Chatwoot fica no texto. A sessão de cliente dura 180 dias, renovada a cada uso; a da equipa, 30. No primeiro acesso (conta sem senha, mustChangePassword), o app apresenta modal de boas-vindas para conferir dados (POST /api/auth/verify-profile), vincular Google opcionalmente e criar a senha de acesso. Após a conclusão desse fluxo inicial (ou no login regular), são avaliadas as permissões obrigatórias por perfil móvel: para EMPLOYEE, a sequência completa (PWA, GPS/Localização, Câmera, Notificações e Som); para MANAGER, ADMIN e CLIENT, exige PWA e Notificações (dispensando GPS, Câmera e Som). No desktop, nenhuma dessas permissões é exigida e o acesso é direto. Durante a configuração obrigatória de senha, o gate de requisitos e o prompt de instalação do PWA permanecem suspensos.
App primeiro (2026-10-07). Uma mensagem do escritório para um cliente com aparelho que recebe push (token nativo ou inscrição web) vai só para o app — sem WhatsApp, sem quota, e o compositor não trava pela janela de 24 h (appFirst em messages.ts, isAppFirstChannel no compositor). Cliente sem aparelho continua a receber pelo WhatsApp como antes. Os avisos automáticos de evento (reserva confirmada, a caminho, proposta, taxa, depósito, avaliação…) nunca saem sozinhos pelo WhatsApp. Configurações → Automatic messages → Automatic notices escolhe o destino (automations.noticeDelivery): Internal (o padrão, até a rota do app estar comprovada) grava o aviso como nota interna retida, com o próprio texto como inglês, e avisa o escritório (Waiting for you); um manager libera-o como uma mensagem retida da equipa (Release to client: no app, pelo WhatsApp com a janela aberta, ou pelo WhatsApp Business), em nome da empresa — sem a linha Manager — nome. App grava-o na conversa do cliente e manda o push (deliverInApp em clientMessages.ts; o portão das automações recebe via: 'APP', sem o limite mensal; quem mandou STOP continua sem automáticas). As respostas automáticas a quem escreve no WhatsApp (Who is this for?, ausência, link do app) continuam pelo WhatsApp — são a ponte. Entregue (dois tiques) quer dizer que o aparelho do próprio cliente tem a mensagem: o service worker confirma o push nomeando-o (/api/messages/:id/delivered?n=, que só conta quando o push era do cliente da conversa), e no app nativo, que ainda não confirma, conta o FCM/APNs aceitar o push dele. Uma mensagem só do app sem essa confirmação em 5 minutos (ou na hora, se o cliente não tem aparelho) ganha por baixo Not received in the app · Forward on WhatsApp Business (AppDeliveryFallback: texto + link /chat/ para essa mensagem, aberto no WhatsApp Business do celular), e quem a escreveu recebe um push Not delivered in the app (o escritório inteiro, num aviso automático; alertUndeliveredAppMessages, no cron de 5 min, com cursor para avisar uma vez): o toque abre a conversa nessa mensagem, e os botões são Send on WhatsApp (pela API da Meta, com a janela de 24 h aberta — gasta a nossa quota) e WhatsApp Business (abre o WhatsApp com o texto e o link). A folha do balão oferece o mesmo: Send now on WhatsApp com a janela aberta (/channels/:id/forward-whatsapp, recusado com a janela fechada), senão copiar ou abrir no WhatsApp Business. Vai sempre o texto da mensagem com o link para o app (o convite da equipa é que leva só o link). Enviada pelo WhatsApp, a mensagem fica verde: pela API, a hora de envio chega ao vivo; pelo celular, o eco que começa pelo texto dela e traz o seu link marca a própria mensagem, com o WAMID para os recibos da Meta (markForwardedFromEcho), em vez de virar nota.
Clientes no app (Dashboard). Dentro do cartão Mensagens do Dashboard, abaixo dos três números, a seção Clients on the app (AppAdoptionCard, GET /api/channels/adoption, só escritório) mostra quantos clientes ativos alcançamos no app (com o app nativo ou com notificações no navegador — a mesma regra do ícone do cabeçalho), as nossas mensagens a clientes no mês de Londres por canal (no app, no WhatsApp com Instagram/Facebook, a mesma regra da cor do balão), as que ficaram sem confirmação há mais de 5 minutos e a quota mensal do WhatsApp. Sem clientes, não aparece.
Cor do balão = por onde a nossa mensagem é entregue (deliveryChannel, src/shared/deliveryChannel.ts): azul só para o que fica no app; verde para o WhatsApp (origem WhatsApp — eco do celular —, um provedor de WhatsApp gravado no envio, ou na fila do WhatsApp) e também para Instagram e Facebook, distinguidos pelo ícone ao lado da hora. Vale para as nossas mensagens e as de um colega por esses canais; as do cliente continuam brancas. No verde, os tiques de lido são azul-claro.
Link de uma conversa: https://app.primecrowncleaning.co.uk/chat/<8 base62>, a mesma regra do /go/ (mesma tabela, POST /api/go/consume, uso único, 48 h) com destino chat:<channelId> ou chat:<channelId>:<messageId>; abre /?view=CHAT&channelId= (e &messageId=, que o chat rola e destaca). O consume só abre a conversa a quem a pode ler (canAccessChannelById: nunca a conversa de outro cliente, nunca o DIRECT de um cliente para a equipa); senão vai para o início. O gestor emite-o em POST /api/auth/access-link com channelId, pelo botão de link no cabeçalho de uma conversa de cliente (ConversationLinkButton: o link é criado ao abrir a folha; copiar e abrir o WhatsApp Business são toques próprios, com o convite de conversationInvite). O ícone desse botão é o indicador do escritório (appReach em /api/channels, só para gestor/admin): celular verde = tem token do app nativo, sino azul = tem notificação web (navegador ou PWA), link cinza = nenhum dos dois; um link de conversa substitui só o anterior da mesma conversa, e o link de acesso geral não apaga os de conversa. A prévia que o WhatsApp monta ao colar o link é um cartão largo (og:image 1200×630, link-chat-v1.png no /chat/, link-app-v1.png no /go/, gerados por scripts/generate-link-cards.mjs), quase um botão — o WhatsApp Business do celular não envia botões. /chat sozinho continua a ser o ecrã de chat (widget do site, atalho instalado): só um código de 8 caracteres vai à Function (functions/chat/[code].ts), o resto volta para /chat. No app nativo, /go/<code> e /chat/<code> abrem como página (isNativePublicAppUrl), para o código não se perder no Dashboard. Objetivo: as mensagens da equipa chegam ao cliente pelo app (Release in the app, ver a moderação em whatsapp-integration.md), e o gestor encaminha o link pelo WhatsApp Business (coexistência, fora da quota da Meta); a conversa gestor ↔ cliente pelo WhatsApp não muda.
Primeiro o que o link abriu. O redirecionamento de um link curto para um ecrã do app leva via=link (destinationPath; não a /pay nem a /rate, que são páginas públicas, nem um link para a tela inicial: ali não há nada a ver primeiro, e o link de primeiro acesso deixava o cliente na Home sem nunca pedir a senha). Um cliente que chega assim vê a conversa (/chat/) ou o ecrã (/go/) antes dos passos do primeiro acesso: criar senha (ForcePasswordChangeModal) e o convite opcional para instalar o app (PWAInstallPrompt; o cliente nunca é obrigado a instalar — o MobileRequirementGate é só da equipe e do escritório no celular) esperam (linkArrival.ts, só em memória; o via sai do endereço ao arrancar). O Pay não conta como saída: a página de pagamento é uma camada sobre o ecrã (InvoicePayLayer) — quem chegou a Bills pelo link paga, confirma e baixa a fatura sem criar senha, e ela só é pedida quando sai de Bills. Quando ele sai dessa conversa (o marcador activeChannel, com 300 ms de tolerância para o piscar da re-renderização) ou desse ecrã, os passos voltam na ordem de sempre (pré-carregados durante a leitura, para aparecerem na hora) — senha primeiro, porque no iPhone o app instalado abre sem a sessão do Safari. O convite que o escritório encaminha do celular volta como eco; com um link curto nosso no texto (isAppInvite, em metaEcho.ts e no caminho do Chatwoot) ele é gravado como nota interna: o escritório vê o registo de que o link foi, o cliente — já dentro do app — não vê uma mensagem a pedir-lhe que o abra. A nota mostra à direita do rótulo Internal quando o link foi aberto pela primeira vez (Opened 18:42, ou Not opened yet): o POST /api/go/consume grava essa hora no read_at da nota que traz o código (stampInviteOpened, functions/lib/appLinkOpened.ts) e avisa as conversas abertas como um recibo — ler o convite no WhatsApp não diz se o cliente entrou no app. Quando o cliente abre a conversa (pelo link ou não), a leitura dele grava read_at nas nossas mensagens até ao ponto lido (/channels/:id/read; nunca nas dele nem em notas internas, e o que a Meta já marcou guarda a sua hora): a mensagem liberada só no app não tem recibo da Meta, e o escritório perdia o “lido” ao recarregar. Durante a leitura o chat também não mostra o pedido de notificações (ChatPermissionBanner): ele vem com o passo de instalação. No app nativo, o URL que abriu o app (getLaunchUrl, o mesmo durante todo o processo) é tratado uma só vez por sessão da WebView (isFreshLaunchUrl): o link curto recarrega a página e, perguntado de novo, reabria-se em ciclo. Só para cliente; equipa e escritório não mudam. A página de pagamento (/pay) não tem esses passos: paga (ou a caminho), mostra o convite Open the app.
Quando algo acontece (reserva confirmada, mudança de horário, proposta, a caminho, taxa de cancelamento, depósito, recibo, extrato, avaliação, retorno do site): cada evento tem modo e canal (e-mail, WhatsApp ou ambos); o envio manual da equipa continua sempre disponível. Com a janela de 24 h aberta vai texto livre com o botão do app (grátis dentro da franquia de 1.000/mês da Meta a partir de 2026-10-01); fechada, o template — a versão aprovada escolhida na secção (automations.bots.<id>.template, variáveis de src/shared/templateSpecs.ts, botão /go/{{1}}), senão o original. O retorno do site, mesmo o que espera 15 min na fila, segue esta regra. A fatura automática é só a taxa de cancelamento. O recibo vai só por e-mail. A reserva confirmada sai uma vez por visita, quando ela passa a confirmada.
Templates: o admin submete <base>_v<n> pela secção (/api/automations/templates, variáveis fixas por evento, recusadas antes da Meta se faltar alguma); o webhook de estado troca o evento para a versão aprovada, mantém a anterior se for recusada e volta à anterior se a Meta a reclassificar como marketing. O texto de um template apresenta o app como o jeito de agir sobre aquela fatura ou visita, nunca como anúncio.
O servidor aplica a direção das transferências: apenas DIRECT pode ir para JOB e apenas JOB pode ir para DIRECT. Encaminhar valida que a tarefa existe, pertence ao mesmo cliente e possui canal de equipe antes de mover a mensagem; a interface não é a fronteira de privacidade. Em qualquer direção, um anexo é copiado para a árvore R2 da nova audiência antes da mudança atômica da linha; conflito ou falha não deixa bolha apontando para bytes inacessíveis. O aviso ao vivo de remoção tira a mensagem tanto do fio quanto da prévia da Inbox de origem imediatamente; uma lista iniciada antes da transferência não pode repor o trecho privado, e a próxima leitura atualizada recompõe a prévia anterior ou uma mensagem deliberadamente movida de volta. Um destino de chat vindo de push ou do detalhe da tarefa permanece pendente até a primeira lista de canais autorizada terminar; assim a navegação inicial não perde a conversa por causa da rede. Se o destino não pertencer à lista carregada, o pedido é descartado. Se a primeira leitura do histórico falhar, a conversa ainda inicia o transporte ao vivo e sua busca de mensagens perdidas; uma troca de conversa durante a falha não reconecta o canal anterior.
O feedback de um envio pertence também à conversa e à identidade que o iniciou: uma falha tardia do DIRECT não mostra aviso depois que o utilizador abriu o JOB, nem após troca de conta ou papel. O canal privado inicial de um cliente é garantido uma vez por identidade; quando outra conta de cliente assume a mesma tela sem desmontá-la, ela recebe o próprio canal, sem herdar o bootstrap da conta anterior. No inbound já persistido, uma falha ao preparar o push da equipa é registrada como WHATSAPP_INBOUND_PUSH_FAILED, mas não impede a execução dos passos seguintes (acesso, confirmação de opt-out e bot); a reentrega continua sem repetir esses efeitos. Esse isolamento não reenvia um push perdido.
Um pedido reconhecido de opt-out (por exemplo, STOP) grava o inbound e desativa a autorização WhatsApp do cliente ou lead na mesma transação, inclusive quando promove uma mensagem do formulário. Falha na desativação desfaz a gravação para permitir nova tentativa; falha posterior em push ou confirmação não desfaz o pedido. Só a entrega vencedora altera a autorização: duplicatas não anulam um opt-in posterior. A confirmação continua sendo o único envio desse fluxo que ignora o opt-out já aplicado. Ao promover uma mensagem do formulário para WhatsApp, o mesmo ID recebe a data original do evento WhatsApp (ou a hora atual na entrega ao vivo sem timestamp), nunca a data do formulário nem a hora da varredura; a janela de 24 horas acompanha essa prova sem criar segunda bolha ou segundo push.
Cada inbound Meta, inclusive clique em botão ou lista, preserva o phone_number_id da linha que o recebeu. Assim, uma resposta interativa só reabre a janela de 24 horas e libera mensagens HELD daquele mesmo número comercial; nunca promove filas de outra linha nem linhas históricas do Evolution. Uma entrega sem esse identificador só pode liberar fila legada sem proveniência de linha, nunca uma linha atual. A varredura do Chatwoot guarda a hora original do cliente: histórico recuperado após 24 horas recompõe o chat, mas não libera uma fila HELD nem tenta texto livre fora da janela. Se a gravação do inbound terminar e a liberação HELD falhar, a reentrega reconcilia essa liberação usando canal, provider, linha e hora já persistidos, sem repetir bot ou push de mensagem. Configuração alterada ou timestamp novo no replay não mudam essa prova; mensagem APP ou inbound sem provider conhecido não autoriza a recuperação.
A limpeza de registro push nativo pertence à geração que a iniciou: se outra conta assumir o dispositivo durante a leitura do token, a resposta de remoção ou a espera na fila de armazenamento, as etapas ainda não iniciadas são descartadas. No logout/revogação, a limpeza web/PWA e a chamada de desregistro nativo também expiram ao iniciar outra autenticação, antes da troca do cookie. As remoções levam X-Prime-Expected-User; divergência com a sessão recebe 409 e interrompe a limpeza local. Clientes antigos sem esse cabeçalho mantêm a remoção limitada ao usuário autenticado. Isso não cancela uma chamada já entregue à ponte nativa ou ao navegador; esse limite exige validação em dispositivo.
A renovação de Web Push não apaga o registro do servidor quando o navegador recusa remover a assinatura anterior; a limpeza automática de assinaturas desativadas segue a mesma regra. Remoções na renovação e no controle manual levam a identidade original da conta. O controle manual só confirma a desativação web depois do aceite do servidor e do navegador; recusa ou falha fica visível para nova tentativa. No nativo, falha de desregistro também não aparece como desativação concluída, e etapas pendentes respeitam a sessão que iniciou a ação.
Falhas inesperadas no cadastro ou remoção de push nativo retornam JSON estável e registram NATIVE_PUSH_FAILED, sem entregar o erro bruto ao console. A sanitização de telemetria descarta o bloco SQL e os parâmetros posicionais dos erros Drizzle, inclusive no stack e nas causas estruturadas; tokens nativos e credenciais Web Push não entram nesses diagnósticos. Se o próprio registro de logs falhar, a resposta segura é mantida.
A escolha de fotos/documentos no seletor de arquivos pertence à conta e à conversa que abriram o seletor. Uma troca de conta ou conversa descarta o resultado tardio, mesmo voltando à conversa original; cada abertura aceita um resultado apenas, e abrir novamente permite escolher o mesmo arquivo. A verificação acontece antes do upload, além da proteção já existente durante o envio.
Exclusão também pertence ao par imutável canal+mensagem: mesmo gestão, que pode ler mais de uma conversa, não consegue remover uma mensagem apresentando seu ID pela rota de outro canal.
O contador enviado no push compartilha a autorização do histórico do sino (notificationVisibility), usando o papel atual de auth_accounts, não o cargo guardado na ficha da equipe. Sem uma única conta elegível para a identidade do dispositivo, o envio omite o contador em vez de inferir privilégios; o app autenticado o reconcilia quando abrir. Essa contagem não remove banners já entregues nem substitui a revogação dos tokens.
Diagnósticos e remoção de inscrições expiradas também pertencem ao dispositivo usado no envio: registro+dono+token+plataforma no nativo, e registro+dono+endpoint+chaves no Web Push. A resposta atrasada, inclusive sucesso ou exceção de rede, não sobrescreve nem apaga um registro reassociado ou renovado durante a chamada. A limpeza normal continua para a inscrição expirada que permanece com a mesma identidade.
O cadastro nativo grava o token e retira os anteriores da instalação em uma única transação; cadastros simultâneos não deixam a instalação vazia, e falha na retirada desfaz o novo cadastro. Repetir o mesmo token é idempotente e metadata sem versão não apaga um build conhecido. No Web Push, a própria gravação verifica o dono do endpoint: concorrência da mesma conta atualiza uma única inscrição; outra conta recebe 409 sem alterar suas chaves.
Antes do envio ao provedor, cada dispositivo é relido para confirmar que ainda pertence ao destinatário. Push de chat também exige conta elegível e acesso atual ao canal; metadados de canal conflitantes, canal inexistente ou sem referência verificável não enviam a prévia. Web Push repete essas verificações depois da espera de retry, para que bloqueio ou troca de dono não enviem a tentativa seguinte. Uma recusa de acesso retorna skippedByAccess, sem tratar a revogação como entrega nem apagar tokens de outra conta. Isso não recolhe mensagens que o provedor já recebeu antes da revogação.
O push de JOB aplica a mesma autorização de leitura do chat: usa a alocação atual, mesmo antes de atualizar a tabela auxiliar de participantes, e não envia à equipe de um QUOTE legado. Reatribuição remove o antigo destinatário e inclui o novo já no próximo envio. Histórico DONE/CANCELLED mantém essa autorização; a janela de roteamento WhatsApp não redefine o acesso ao histórico.
O histórico do sino revalida o acesso atual ao canal antes de devolver títulos e prévias de chat. Remoção da equipe, rebaixamento de papel, QUOTE e canal excluído não conservam acesso pelo destinatário original do push. Linhas CHAT sem canal verificável ficam ocultas; avisos não relacionados a chat continuam disponíveis. O limite de 50 vale para avisos autorizados: a leitura percorre blocos por data+ID para não esconder avisos válidos atrás de prévias revogadas. O contador devolvido pelas ações de leitura usa a mesma autorização e conta todos os não lidos, não só a página; marcar todos consulta o restante após a gravação, sem presumir zero se outro aviso chegou durante a operação. Os registros não são apagados, e a verificação não retira notificações já entregues à bandeja do aparelho.
Mídia DIRECT usa o proprietário explícito do canal, não a presença de uma linha em clients. Portanto leads pré-conversão e funcionários em seu canal privado de gestão podem anexar arquivos à própria conversa; para eles, o Worker permite somente o próprio owner ou ADMIN/MANAGER. Um cliente autenticado usa o mesmo clientScopeIds dos canais para ler, anexar e remover mídia DIRECT dos locais do seu grupo de contato; separar um local revoga esse acesso na próxima requisição. Funcionário alocado continua sem acesso a anexos DIRECT de clientes e mantém como superfície permitida apenas a árvore team de tarefas atribuídas. Novas respostas de mídia autenticada enviam Cache-Control: private, no-store, evitando um cache HTTP fresco que contornaria uma nova autorização após troca de conta/cargo; isso não apaga cópias já baixadas nem respostas armazenadas anteriormente.
Push de chat nomeia a conversa, não quem escreveu por último (pushThreadName em notifyParticipants, que agora também serve o WhatsApp recebido via notifyStaff). Numa DIRECT, quando o cliente manda uma mensagem, todos os gestores são notificados. Quando um dos gestores responde para o cliente, os outros gestores não recebem notificação dessa resposta enviada — apenas o cliente a recebe (notas internas na DIRECT continuam notificando os outros gestores com o nome do dono no título e o autor na linha, sem notificar o cliente). Num grupo de tarefa (JOB), toda mensagem sai como <cliente>'s Job para a equipe e Team & Manager para o cliente, sempre com o autor na linha. Assim cliente, gestores e equipe caem na mesma pilha por canal da PWA e do MessagingStyle Android; antes o push levava o nome do último autor, que renomeava a pilha e, no Android, atribuía a ele as linhas anteriores. Como no WhatsApp, o autor viaja também em authorName: o app Android tira o prefixo Ana: da linha e, assim que uma linha é de outra pessoa, desenha a conversa como grupo (MessagingStyle com setGroupConversation, título da conversa e cada autor em negrito com seu avatar de iniciais; o recolhido mostra Ana: …). Linhas sem autor são do próprio dono. PWA e iOS mostram Ana: … em texto, como o WhatsApp Web. O payload não manda channelType: 'JOB': builds anteriores a authorName desenhariam o grupo com o nome da conversa antes de uma linha que já nomeia o autor.
Assunção de Conversa (Takeover / TTL): Em conversas diretas (DIRECT) ou grupos de tarefas (JOB), um gestor pode assumir o atendimento para si ou atribuí-lo a outro gestor (ChannelAssignmentControl no cabeçalho ou auto-assunção por 30 minutos ao responder, via POST /api/channels/:id/assign). O modal completo de assunção (ChannelAssignmentModal), acessível pelo cabeçalho, pelo menu de contexto unificado (clique direito no desktop ou toque longo no iOS Safari/Android) ou deslizando a conversa para a esquerda (swipe actions na lista), reúne a escolha de gestores, períodos de assunção e a opção de marcar como resolvido (quando a conversa estiver sem resposta ou desatribuída). No menu de assunção, uma caixa de seleção lista os gestores disponíveis e já traz o próprio usuário logado pré-selecionado. As opções de duração continuam 30 min, 1h, 2h ou “Até liberar” (indefinido); ao escolher o gestor e clicar no período desejado, a atribuição é concluída e o gestor designado é notificado imediatamente (via push e histórico de notificações) sobre a conversa atribuída e o tempo estipulado. Enquanto a conversa estiver atribuída a um gestor e o tempo não tiver expirado, novas mensagens notificam exclusivamente o gestor atribuído quanto ao papel de gestão, silenciando os demais gestores para reduzir ruído. Em canais de tarefa (JOB), os funcionários alocados na tarefa continuam a receber as notificações normalmente. Notas internas na conversa continuam notificando todos os gestores. Caso a atribuição expire ou seja liberada manualmente (“Liberar atendimento”), o canal volta ao estado aberto e todos os gestores voltam a ser notificados.
Roteamento de Destino WhatsApp: O histórico de visitas lista as conversas internas do Team. Gestores encontram o seletor de destino da próxima mensagem recebida pelo WhatsApp na conversa privada (Manager), quando há mais de um canal. O retorno de uma conversa social ativa ao WhatsApp também fica na conversa privada. Ao escolher Automático, a sessão expirada guarda uma barreira de ordenação: um prompt cujo envio começou antes da escolha não reabre a pergunta ao terminar, mas um novo envio posterior pode fazê-lo normalmente.
Roteamento social: Quando um cliente ou lead envia mensagem via Instagram Direct ou Facebook Messenger, o sistema abre uma janela de resposta social de 2 horas (SOCIAL_WINDOW_MS = 2 * 60 * 60 * 1000). Durante essa janela, as respostas da equipe saem diretamente pelo canal social correspondente (via Chatwoot) e a restrição da janela de 24 horas e templates do WhatsApp fica suspensa (caixa de texto liberada). A expiração automática de 2 horas só reverte a conversa para o WhatsApp caso a janela de 24 horas do WhatsApp esteja aberta; caso a janela do WhatsApp esteja fechada, o sistema mantém a janela da rede social aberta até que o cliente reabra o WhatsApp (ou até que a janela do WhatsApp seja liberada), evitando que respostas da equipe tentem sair pelo WhatsApp e falhem. O painel de roteamento e o retorno manual ao WhatsApp foram removidos; a expiração da janela social continua automática.
E-mails de saída. Todo e-mail sai pela mesma casca (renderEmail, functions/lib/emailLayout.ts): cabeçalho PRIMECROWN com o ícone em CID (não uma URL remota), superfície clara, Plus Jakarta Sans e azul como acento primário — a identidade das páginas públicas e do app — com accent (blue/emerald/amber/rose/slate) pela natureza da mensagem (emerald para dinheiro recebido, amber para o que espera um gestor). O remetente passa só texto (título, olho, saudação, parágrafos, linhas de detalhe, botão, painel, nota) e a casca escapa tudo; só block leva marcação, e é a tabela da fatura, com o seu equivalente em texto ao lado. renderEmail devolve html, text e o anexo do logo, e os três vão em todo envio. A cópia guardada na tela Emails não tem o anexo: ao mostrar o HTML, emailDocument (EmailHtmlBody.tsx) troca cid:primecrown-logo pelo mesmo arquivo servido pelo app (/brand/icon-192-v3.png) — antes o logo aparecia quebrado ali (2026-11-05). Um link digitado no texto (o /pay/<código> do e-mail da fatura) sai como link clicável no HTML (paragraphHtml usa splitTextByUrls, o mesmo do chat, ainda escapado), e a tela Emails mostra links clicáveis também nos e-mails só de texto (LinkifiedMessageText). O nome do remetente é sempre “Prime Crown Cleaning”. Avisos (login, reset, recibo) saem de noreply@primecrowncleaning.co.uk; o que a pessoa pode responder (boas-vindas, fatura, decisão de exclusão) sai de info@ com Reply-To no mesmo endereço. O Cloudflare Email Sending é o caminho; se falhar, cai no Resend e o system_logs registra EMAIL_DELIVERED / EMAIL_FALLBACK / EMAIL_FAILED. O rodapé padrão é só “© ano Prime Crown Cleaning” e os links de privacidade/termos — sem número da Companies House, endereço ou HMRC/VAT, inclusive no e-mail da fatura: os dados legais de cada empresa estão no próprio documento da fatura. O link de login por e-mail cumprimenta pelo primeiro nome (cliente ou equipe; sem nome, “there”). tests/outgoing_email_visual_contract.test.ts recusa HTML escrito à mão no remetente, envio sem parte de texto, e from fora desses dois endereços.
E-mails de entrada (info@). O MX do domínio é o Cloudflare Email Routing: só o info@ de primecrowncleaning.co.uk, primeldn.co.uk e crownldn.co.uk chega, entregue ao Worker chatwoot-inbound-relay (email-relay/); o catch-all descarta o resto. Desde 2026-11-11 o e-mail da Prime Crown vai só para a central de e-mail do app (POST /api/emails/inbound, com INGRESS_PASSWORD — sem o segredo o endpoint responde 503 e não aceita nada), nunca para o Chatwoot: uma recusa do app faz a entrega falhar e o Email Routing tentar de novo, e o app trata um Message-ID repetido na mesma caixa como já guardado (sem gravar duas vezes nem avisar de novo). O Chatwoot recebe só os outros domínios: a conta 2 (Prime Crown) não tem mais caixa de e-mail — as quatro (info@ dos três domínios e spam@primecrowncleaning.co.uk) foram apagadas em 2026-11-12, com o histórico que só existia nelas. O filtro de spam não altera o e-mail da Prime Crown: o veredito vai ao lado, no cabeçalho X-Prime-Spam da chamada ao app, que grava a conversa em Spam; o original no R2 fica como o remetente o mandou. Só o e-mail de uma caixa do Chatwoot (Caraíva e pousadas) ainda tem o To trocado para a caixa Spam da conta, porque o Chatwoot escolhe a caixa pelo destinatário; o app continua a entender esse formato antigo (X-Prime-Spam/X-Prime-Original-To dentro do e-mail, spam@). O mesmo Worker recebe caraivaexclusiva.com.br (contato@ e o catch-all, que leva os endereços reply+<uuid>@ de resposta do Chatwoot de todas as contas), pousadakamaiura.com.br e pousadasuyhe.com.br (reservas@ e catch-all): só os endereços de email-relay/src/filteredInboxes.ts passam pelo filtro — os três info@ da Prime Crown (veredito ao lado, para a central do app) e contato@caraivaexclusiva.com.br + os dois reservas@ (Spam da conta 3, spam@caraivaexclusiva.com.br); reply+, catch-all e o resto seguem intactos. Cada caixa Spam fica sem agentes, então não notifica no Chatwoot; o webhook e as notificações da central (chatwootDeskAlert) também suprimem ativamente qualquer e-mail classificado como spam (caixa Spam, endereço spam@, label spam, cabeçalho X-Prime-Spam, atribuído ao Filtro Anti-Spam ou com termos de oferta comercial/SEO), garantindo que nenhum aviso ou push seja disparado para o app. Um endereço novo na tabela exige criar antes a caixa Spam da conta. O Worker envia o e-mail bruto ao ActionMailbox do Chatwoot (INGRESS_PASSWORD). Oferta de serviço à empresa (SEO, site, marketing, leads, empréstimo…) vai para a caixa Spam da conta: o Worker troca o To pelo endereço dela (o Chatwoot escolhe a caixa pelo To) e guarda o original em X-Prime-Original-To e o motivo em X-Prime-Spam. Bloquear remetente não serve (cada oferta vem de um endereço novo), então a decisão lê o conteúdo: primeiro frases que nenhum cliente escreve (spamFilter.ts; profissões como “web developer” ficam de fora, um cliente cita o próprio trabalho), depois o Workers AI (llama-3.3-70b-instruct-fp8-fast, com o negócio e os clientes de cada caixa descritos na tabela), conservador — só “sales_pitch” com confiança ≥ 0,9 conta; dúvida, erro ou resposta ilegível entrega no endereço original. O filtro só escolhe a caixa, nunca descarta. A regra anti-spam do Chatwoot (infra-stack scripts/chatwoot-setup-spam.rb) continua depois da chegada, com a lista mais larga. Deploy pelo npm run deploy:backend.
Quem assina. O administrador não assina (staffAttributionLine vazia para ADMIN, 2026-11-09) e nunca aparece em Seen by (/channels/:id/readers). Para os demais, a linha de autoria é _Manager_ — <nome>: (ou _Team_), com o papel em itálico do WhatsApp (whatsappDelivery.ts; *…* sairia negrito), e o nome é o apelido (staffName, normalmente o primeiro nome).
Painel no Chatwoot (Dashboard App). https://<app>/chatwoot-panel é registado no Chatwoot (Settings → Integrations → Dashboard Apps) e é o próprio app recortado no contato da conversa aberta: monta AppProviders (os mesmos providers, /api/boot, stores e escritas atômicas de App.tsx) e não tem leitura própria. /api/panel/identity diz quem é o telefone/email do contato pela regra única resolveContactIdentity (cliente antes de lead, primária do grupo); o resto vem das stores. /api/panel/identity devolve também leadIds (matchingLeadIds: todo lead com o mesmo telefone ou email, vivo, convertido ou fundido), e o painel junta os leads convertidos no grupo e os fundidos neles: são as cotações do contato. Orçamentos usa as peças da tela de Orçamentos (QuoteCard, useQuoteRevise, quoteService) e abre o QuoteConfirmationPanel no próprio painel, sem botão de chat (a conversa é o Chatwoot); confirmar leva à aba Visitas com a visita criada aberta. Lead: as cotações vêm primeiro, acima do LeadCard. O cabeçalho do cliente mostra o saldo em aberto (fora DRAFT/VOID/PAID). Seções: Cliente (fichas do grupo de contato, endereços e notas de acesso, editar no ClientModal), Visitas (próximas e anteriores do grupo; abrir, remarcar, cancelar, alocar e agendar pelo TaskActionRegistry, com o BookingModal já no cliente via bookingClientId) e Faturas (InvoiceRowCard + InvoicePreviewModal). Lead: LeadCard; converter abre o ClientModal com leadClientPrefill (o mesmo de People → Leads) e depois convertLeadToClient. Contato de Messenger/Instagram chega sem telefone nem email e o painel pede, no próprio aviso (panel.noPhone), para juntá-lo no Chatwoot ao contato de WhatsApp do cliente (Merge, com o de WhatsApp como base) ou acrescentar telefone/email à ficha; daí a identidade sai pela mesma regra, sem vínculo próprio no app. Número desconhecido: criar cliente (nome, email e celular do Chatwoot) ou buscar um cliente e abrir a ficha dele com o número no celular (ou no fixo vazio) para confirmar. Ficha de pessoa (2026-09-30). O painel mostra a ficha do app, PersonProfile (src/components/people/, no estilo de CRM; a mesma que a tela People vai abrir): cabeçalho com avatar, nome, saldo ou contato e ícones de ação — cliente: Call, Email, Book, App link, Edit; lead: Call, Quote, Make client, Merge, App link (Message só onde há um chat do app para abrir, nunca no painel) — e abas: cliente Overview · Visits · Plans · Invoices · Quotes (só com orçamentos) · Keys · Profile · History · Duplicates (só com leads soltos); lead Overview · Quotes · Profile · History. O Overview traz o que espera por você (PendingCard, regra em panelPending.ts sobre DashboardIntelligenceService.classifyRequests e filterGhostedTasks: orçamentos abertos, visitas passadas e abertas, em revisão, sem equipe e sem confirmação, transferências a confirmar, faturas vencidas, planos que precisam ser agendados adiante e leads soltos da mesma pessoa; cada item abre a aba onde se resolve), três números (cliente: plano, valor em aberto com o link de pagamento, próximas visitas; lead: estado, orçamentos, primeiro contato), o cartão da próxima visita (nota à equipe, remarcar) e a atividade recente (as 5 últimas do Histórico, panelTimeline.ts: orçamento pedido, visita agendada, concluída (hora do clock-out ou do fecho de turno), cancelada (no dia em que ia acontecer), ocorrência, fatura emitida e pagamento concluído; a linha da visita abre a visita). As abas são as seções de sempre: Visits, Invoices (FinanceTab), Plans (ClientPlans), Keys (KeyCustodyPanel), Quotes (QuotesSection), Profile (ClientTab / LeadCard), Duplicates (convertLeadToClient). Quem é a pessoa sai de personContext: o grupo de contato, e os leads — os que o servidor devolve em leadIds, os convertidos no grupo, os fundidos neles e os do mesmo telefone em qualquer formato (normalizePhoneIdentifier). Um só TaskActionRegistry na área de trabalho abre qualquer visita. Rolagem: o CSS do app trava html e body (as telas do app rolam nos próprios contêineres), então o painel rola no seu contêiner raiz (data-panel-scroll em main.tsx); o teste de navegador rola com a roda do mouse. Celular: o app do Chatwoot abre o painel numa WebView de tela inteira (não iframe), com window.ReactNativeWebView e o contexto postado na própria página (inChatwootMobile); lá a página é primeira parte, então o painel mostra o Login do app no lugar e usa a sessão normal (o Google recusa login em WebView — usar senha), e Desconectar é o logout do app. Só manager/admin. Login: o botão Conectar (cartão BrandHeader do login) abre /panel-connect, janela de primeira parte com AuthProvider e a própria tela Login (um Google/Apple sem conta não inicia cadastro ali); com a sessão do app, pede um código de uso único de 60 s (/api/panel/code, só com o cookie session) e entrega-o por postMessage; o painel troca-o em /api/panel/session por panel_session particionado (SameSite=None; Partitioned; Path=/api, 30 dias; tabela panel_sessions, só hashes) e recarrega. Esse cookie autentica a API inteira só em getSessionUser (e /api/auth/me), só sem o cookie session, só com Sec-Fetch-Site: same-origin e, em escritas, X-Prime-Panel: 1, que installPanelFetch põe em todo fetch do painel para /api/; GET dispensa o cabeçalho para <img src="/api/uploads/…">. Cada pedido relê a conta: papel rebaixado, bloqueio ou “sair de todos” derruba o painel, e o AuthProvider (signedOutPath="/chatwoot-panel") volta ao Conectar. Desconectar apaga a linha e o cookie nos caminhos /api e o antigo /api/panel. Só /chatwoot-panel pode ser embutido, e só pelo Chatwoot nos seus dois endereços — https://chatwoot.primecrowncleaning.co.uk e https://chatwoot.caraivaexclusiva.com.br (o FRONTEND_URL, partilhado com a Caraíva) — em _headers e em CHATWOOT_ORIGINS (a origem aceita no postMessage; o pedido do contexto vai a cada endereço e o navegador entrega só ao do pai); um endereço novo do Chatwoot muda os dois. O teste de navegador (tests/browsers/chatwoot-panel.browser.ts, só Chromium) desliga o Local Network Access do Chromium, porque a página de teste é pública e o servidor é localhost; em produção ambos são públicos. Design: docs/superpowers/specs/2026-09-17-chatwoot-panel-workspace-design.md.
No Android, a supressão da notificação enquanto uma conversa está aberta guarda canal e usuário autenticado juntos. Uma seleção antiga, inclusive do mesmo canal compartilhado, não pode silenciar a notificação de outra conta durante logout, impersonação ou troca de usuário. A limpeza do aviso ao ler o canal também confere o dono no Android, no iOS nativo e na PWA; operações atrasadas da conta anterior não apagam a bandeja da nova. No iOS, o plugin seleciona avisos APNs entregues pelo par recipientUserId/channelId; no logout, ambos os plugins nativos removem só os avisos do usuário que saiu, incluindo avisos operacionais e atalhos Android. No Android, a limpeza nativa revoga também a audiência local do usuário que saiu antes de retirar os avisos; a renderização confirma o dono novamente ao publicar banners e atalhos, para não expor um push que cruzou o logout. Builds Android antigos conservam a limpeza geral legada até receberem a atualização nativa. O contador e o aviso de uma conversa só desaparecem quando /channels/:id/read confirma a gravação; recusa ou falha de rede preserva ambos, e uma mensagem que chegue durante a leitura continua não lida até a sua própria confirmação. Uma lista pedida antes de um push não sobrescreve o contador local mais recente; uma leitura que falhou com a conversa aberta é tentada novamente quando a rede ou o primeiro plano retornam. A primeira notificação de outra conta para o mesmo canal reinicia a pilha MessagingStyle, sem repetir as mensagens guardadas para o usuário anterior. O app Android anterior ao novo método nativo deixa o aviso visível em vez de apagá-lo sem verificar o dono, até receber uma versão da loja com o plugin atualizado.
Na bandeja da PWA, a confirmação de leitura identifica os IDs da notificação que iniciou a ação. O app só zera o contador desse canal quando o servidor confirma unreadCount = 0 e não observou outro push fora desses IDs; uma confirmação antiga não apaga mensagem nova, e um push atrasado já coberto pela leitura não volta a contar. Se restarem mensagens, o aviso pede para abrir a conversa sem substituir um push mais recente. Um service worker antigo, sem essa identificação, provoca reconciliação com o servidor em vez de zerar o contador por suposição. A resposta rápida exige success: true da API; se um push novo já ocupou a bandeja durante o envio, não o substitui pela pilha antiga. Depois de uma troca de conta, um push ou uma ação iniciados antes da troca não mostram conteúdo nem atualizam o contador da nova conta; um aviso antigo que termine de aparecer é removido. Mesmo quando o logout não conhece o ID anterior, a limpeza geral que terminar depois do novo login não apaga seus avisos nem seu badge; gravações do badge pelo service worker são serializadas.
Na bandeja Android, Mark as read só fecha o aviso se a API confirmar success: true, devolver um unreadCount inteiro e não negativo igual a zero e ainda for a mesma geração do push e o mesmo usuário; resposta sem contador ou inválida preserva o aviso, e leitura parcial mantém um aviso para abrir o chat. Uma resposta tardia, inclusive de falha, não encobre mensagem mais recente. A resposta inline também exige confirmação explícita do envio; falha mostra aviso separado sem apagar um push novo, e leitura parcial mantém o contador na pilha. Ao marcar como lido dentro do app, Android e iOS limpam somente notificações recebidas até o início da requisição de leitura, preservando as que chegarem durante a espera pelo servidor.
No servidor, a leitura avança uma sequência de inserção (messages.read_sequence → last_read_rowid, nome legado da coluna) além de guardar o horário. A sequência não é reutilizada mesmo quando a mensagem mais nova é apagada. A lista separa a prévia cronológica da última mensagem inserida: recuperar uma mensagem antiga não muda a prévia, mas ela pode ser marcada como lida ao abrir o chat. O app aberto e as ações da bandeja PWA/Android enviam o ID da última mensagem já conhecida; a requisição atrasada não lê um push que chegou depois, mesmo quando as duas mensagens têm o mesmo segundo em created_at. Leituras simultâneas só avançam o cursor; a migração inicial preserva o estado lido anterior e clientes antigos sem ID continuam a usar um instantâneo no momento da requisição. O endpoint devolve o contador restante; só zero permite limpar o aviso, e um cursor parcial é atualizado antes de nova tentativa no chat aberto. A confirmação de leitura enviada ao WhatsApp usa o cursor efetivamente persistido e uma fila durável por canal. Ela tenta um lote curto após a resposta; o processador periódico retoma os lotes restantes ou falhos sem truncar mensagens antigas nem desfazer a leitura do app se o provedor falhar. Usa whatsapp_phone antes de mobile_phone/phone. O evento de WebSocket leva os IDs recentes cobertos pelo cursor para não pintar como lida uma mensagem posterior ou inserida com horário retroativo; páginas antigas reconciliam ao recarregar.
O estado em memória do catálogo fica em templateCatalogueCache, sem dependência do cliente HTTP. A limpeza de sessão invalida somente esse estado; a consulta Meta e a filtragem continuam carregadas apenas quando o composer precisa delas.
O seletor de rota só apresenta destino confirmado após success=true e opções em formato de lista. Respostas recusadas ou incompletas mostram falha e retry, evitando confirmação indevida de Management.
Falha e carregamento do destino WhatsApp permanecem visíveis em telas pequenas e são anunciados por alert/status. O botão de nova tentativa mantém seu tamanho quando a explicação quebra em linhas.
Datas do encaminhamento usam Europe/London tanto no relógio quanto em Today/Tomorrow/Yesterday. Fora desses dias relativos, incluem o ano para distinguir histórico e agenda futura. A comparação usa dias civis, incluindo transições de horário de verão, independentemente do fuso do dispositivo.
ChatPermissionBanner.test.tsx monta React em jsdom e valida cliques simultâneos, estado ocupado, retry após rejeição, resposta tardia após remontagem e separação web/nativa. A ponte do sistema é simulada; abertura real continua pertencendo à homologação em aparelho.
O banner serializa ações de permissão/configurações, mostra processamento durante toda a operação e ignora conclusões após desmontagem. Rejeições inesperadas oferecem erro recuperável.
Feedback de permissão nativa no hook compartilhado usa instruções de configurações do dispositivo, válidas para Android e iOS, e não depende do rótulo Subscribe de uma tela específica.
Quando a permissão está bloqueada, a ação do banner abre as configurações de notificações via adaptador Android/iOS. Na web, o botão informa que verifica a permissão novamente. Falha ao abrir configurações mostra orientação manual.
O aviso de permissão bloqueada distingue o runtime: Android/iOS orientam às configurações do aplicativo no celular; navegador/PWA mantêm a orientação de permissões do site.
A filtragem de templates é importada sob demanda após a resposta válida do catálogo. A limpeza síncrona do cache da sessão não depende da execução desse módulo.
O editor de templates usa a chave composta usuário/canal do composer. Trocar qualquer uma dessas identidades remonta o editor, removendo imediatamente rascunho, seleção e estado de envio anteriores.
O catálogo exige sucesso explícito da API antes de consumir templates. Respostas recusadas não são armazenadas nem apresentadas como lista vazia confirmada; o composer oferece nova tentativa.
A limpeza de conteúdo privado da sessão invalida sincronamente o catálogo de templates antes de aguardar IndexedDB. Logout e revogação descartam sua memória; respostas em voo anteriores não a restauram.
A limpeza do catálogo de templates invalida sua geração: consultas anteriores podem concluir para seus chamadores, mas não repovoam o cache nem removem a consulta compartilhada mais recente.
Falha de carregamento do catálogo oferece “Retry loading templates” na conversa. A tentativa reutiliza a deduplicação do catálogo compartilhado e invalida a conclusão da leitura anterior, sem exigir fechar ou recarregar o aplicativo.
Durante o envio de template, variáveis e retorno à lista ficam desabilitados até a resposta. Falhas usam alertas acessíveis, carregamento usa status e o envio informa aria-busy, preservando feedback em VoiceOver/TalkBack e desktop.
O Worker revalida o template aprovado, a quantidade e o conteúdo não vazio de cada variável antes de reservar ou chamar o provider. Também recusa template enquanto a janela gratuita de 24 horas estiver aberta: um bundle antigo ou payload alterado não converte uma resposta livre em conversa Meta paga. Profissionais veem somente o bloqueio e o pedido para chamar a gestão; apenas ADMIN/MANAGER pode abrir o seletor e decidir esse custo. A chave de retry confirma somente a reserva do mesmo canal — uma UUID reaproveitada em outra conversa não retorna sucesso nem expõe seu recibo. Um template aceito também reabre explicitamente o canal arquivado; entrada inválida ou recusa do provider não muda o lock. Recusas não criam mensagem no histórico nem chave de idempotência.
Tarefas elegíveis com data inválida aparecem em “Schedule unavailable” no encaminhamento, preservando o destino sem inventar um horário. A classificação interpreta cada data uma vez e conserva os pedidos originais.
A seleção de tarefa para encaminhamento reclassifica próximas/passadas pelo relógio compartilhado de foreground. A lista acompanha a passagem do horário e o retorno do aplicativo sem exigir alteração dos pedidos ou recarregamento manual.
Encaminhar para tarefa e mover para Management possuem locks síncronos e cancelamento HTTP por usuário/conversa. A navegação ao destino revalida o contexto após atualizar os canais; trocar de conversa durante a operação impede navegação e feedback tardios. A mensagem movida exibe processamento e aria-busy. Abortar o request não desfaz uma transferência já aceita pelo servidor.
O seletor de rota distingue uma escolha vigente do modo automático: sem sessão válida, mostra Automatic · conversation context, pois o contexto humano recente pode levar ao JOB. Uma pergunta ainda sem resposta aparece como Awaiting client choice · private; Management continua selecionável para fixar explicitamente o destino privado em ambos os casos. O selo Active só aparece para uma tarefa com escolha vigente. Na retomada web/nativa, o banner oculta opções antigas até confirmar a rota no servidor; uma gravação em curso faz essa leitura ao concluir. Trocar de conversa, inclusive do mesmo cliente, invalida operações e feedback anteriores.
O módulo Communication centraliza a mensageria da empresa, unificando conversas internas com o WhatsApp oficial via Meta Cloud API. A coexistência também importa respostas feitas no aplicativo WhatsApp Business para que telefone, web, PWA, Android, iOS e desktop compartilhem o mesmo histórico, identificando inclusive o gestor autor através de assinaturas no padrão Manager - Nome (no início ou fim do texto) para atribuição e assunção da conversa. Quando uma resposta do aplicativo cita uma mensagem de JOB ainda aberto do mesmo cliente, ela permanece naquele grupo e conserva a citação; sem essa prova, ou diante de tarefa fechada/estrangeira, cai no DIRECT privado em vez de adivinhar uma audiência operacional.
Inbox da funcionária (2026-09-24). Só as conversas de tarefa abertas pela nossa janela de conversa — não a janela de 24 h do WhatsApp (sessionWindow, regra da Meta para texto livre ao cliente), que é outra coisa: a tarefa está agendada/em andamento, ou foi concluída há menos de closeWindowHoursAfter horas (Settings → arquivamento, padrão 24 h, contado de completed_at; depois autoLockExpired arquiva), e não está travada. A regra mora em functions/api/channels/taskWindow.ts (isOpenTaskGroup, readGroupLifespanHours; o SQL openJobGroup do roteamento é a mesma regra) e /api/channels manda taskOpen em cada canal JOB. A lista é a mesma no celular e no desktop (ChatHome variante EMPLOYEE; o ChatSidebar é só do gerente): a linha com a gerência fica fixa no topo, compacta (“Management”/“Gerência”, a última mensagem, hora e não lidas — sem o texto explicativo; tocar nela recolhe o cliente aberto) e os clientes rolam por baixo, uma linha por cliente como no Inbox do gerente (employeeInboxGroups + AdminClientGroup com forStaff, sem janela de 24 h do WhatsApp nem selo de tempo de resposta). Tocar no nome abre as tarefas daquele cliente — as 2 mais próximas de agora (nearestTasks) e “+N more tasks” quando há mais —; com uma só, a conversa abre direto. A conversa aberta na tela ou com mensagem não lida nunca some. Dentro da conversa, a funcionária não tem o seletor à direita (ChatConversationSwitcher, showSwitcher={false} no AdminChatHeader), no celular e no desktop: ela troca de conversa pela lista. Gerente e cliente seguem com ele. O atalho para a tarefa é só o ícone (como no canto do painel no desktop): no celular, ao expandir, fica à direita do endereço e das horas. O aviso de conversa da equipe fica só no fio da conversa, não no bloco expandido. O painel lateral não repete tipo de serviço, status nem horário — isso já está na barra. Texto livre no WhatsApp (manager e funcionário): só com a janela Meta de 24 h aberta e a nossa janela de conversa da tarefa (taskOpen); Meta fechada → aviso de janela de 24 h fechada com atalho para abrir o WhatsApp Business no aparelho para resposta direta pela linha comercial oficial da empresa (o seletor de templates foi descontinuado do composer); tarefa fechada → o funcionário não escreve (pede reabertura, só num grupo travado), o gestor reabre ao escrever.
Grupo fechado (2026-11-05). Um grupo de tarefa fechado — travado pelo autoLockExpired ou só fora da janela (taskOpen falso), nunca o de uma visita cancelada (isClosedTaskGroup, src/shared/closedTaskGroup.ts) — abre com o aviso acima da caixa (ArchivedChannelNotice: This group is closed. Sending a message reopens it for 24 hours, as horas de closeWindowHoursAfter) para o cliente e o gestor, que escrevem nele. O envio destrava e grava channels.reopened_at (0258); isOpenTaskGroup e o openJobGroup do roteamento contam o grupo aberto por mais um tempo de vida a partir dali, então a resposta do cliente pelo WhatsApp também volta a poder ir para o grupo. Aprovar o pedido de reabertura da equipe grava o mesmo carimbo. Antes só um grupo travado mostrava o aviso: o que só tinha passado da janela travava o cliente numa pílula “fechado” e deixava o gestor escrever sem aviso.
O breakpoint md é uma decisão de renderização, não apenas de CSS. ChatInbox e ClientChatView montam exclusivamente a árvore desktop ou mobile usando o mesmo useMediaQuery fornecido ao controlador. Isso inclui a conversa, o perfil de cliente/equipe e o painel lateral da tarefa: a árvore escondida não mantém uma segunda instância, polling/WebSocket, marcação de leitura, composer, seletor de rota WhatsApp nem efeitos do dashboard ativos. Ao cruzar 768 px, o React desmonta o lifecycle anterior e monta a superfície apropriada ao novo runtime/tamanho. Ao ocultar a página ou colocar o shell nativo em segundo plano, o transporte da conversa também encerra socket, polling e reconnect pendente sem esquecer o canal visível; no retorno a carga completa do histórico termina antes de abrir o realtime. O catch-up do socket cobre o intervalo subsequente, evitando que uma resposta lenta sobrescreva uma mensagem recém-recebida durante a retomada. Rascunhos offline pertencem ao usuário e só são restaurados/enviados no foreground: uma mudança de rede durante o background nunca transmite uma mensagem em nome do usuário.
O reconciliador de ciclo de vida publica somente mudanças reais de foreground/background. Eventos Capacitor repetidos não fabricam um segundo pause ou resume, portanto não reiniciam polling, reconnect, focus de query ou a sincronização de permissões em Android/iOS; navegador, PWA e desktop continuam usando o mesmo contrato de visibilidade.
O menu desktop de troca de conversa limita sua lista com dvh, acompanhando redimensionamento, split-screen e barras do navegador. A ação selecionada continua visível e rolável sem depender de uma altura vh capturada antes da mudança do viewport.
O banner de destino WhatsApp trata leitura e mudança como operações pertencentes ao cliente/conversa atual. Cada transporte recebe AbortSignal; trocar owner ou desmontar cancela fetch e retries. A mutação possui lock antes do primeiro await, promove 4xx funcional a falha e só atualiza, recarrega ou emite toast se seu epoch ainda estiver ativo.
Falhas inesperadas dos endpoints de canais usam um contrato único em channelError.ts. Listagem/criação de canais, mensagens, participantes, reações, leitura, digitação, agendamento, tradução, encaminhamento e movimentação nunca devolvem error.message do D1, Durable Objects ou Gemini ao cliente. O aplicativo recebe uma mensagem estável com possibilidade de nova tentativa; o diagnóstico completo passa pelo sanitizador central e é gravado em system_logs com ação e tipo de entidade para investigação administrativa. Erros funcionais 400/401/403/404/423 permanecem específicos para orientar a interface igualmente no desktop, PWA, Android e iOS.
Uma mensagem agendada não reabre nem atravessa um canal bloqueado: a criação recebe 423 se a conversa já estiver fechada e o dispatcher descarta uma agenda que ficou vencida depois de cancelamento ou arquivamento. Assim uma intenção anterior não gera histórico, push ou WhatsApp quando a regra atual da conversa passou a ser não comunicar.
O browser pode fornecer um nome apenas para desenhar imediatamente o seu balão otimista; ele não é uma declaração de autoria. Ao persistir a mensagem, o Worker resolve senderId, papel e nome visível a partir da sessão autenticada e do cadastro D1. O endpoint do app também fixa source = APP, ignorando a origem declarada pelo cliente: apenas um webhook Meta/WhatsApp autenticado pode gravar WHATSAPP e abrir a janela oficial de 24 horas. Assim, payloads alterados não conseguem apresentar um cliente como manager/funcionário nem liberar envio livre fora da janela, e o mesmo histórico permanece confiável em web, PWA e shells nativos.
A abertura idempotente de um canal também reaplica os participantes recebidos quando o canal já existe. Assim um JOB criado previamente por automação, webhook ou outro dispositivo passa a refletir a alocação apresentada nos detalhes da tarefa; só adiciona ausentes, sem remover ninguém. Remoções continuam exclusivas da sincronização autoritativa da tarefa, evitando que uma abertura atrasada revogue acesso de uma alocação mais recente. Quando essa sincronização muda a equipe, o Durable Object fecha os sockets ativos do JOB: os membros ainda autorizados reconectam pelo gate Pages e quem foi removido não continua recebendo broadcast em uma conexão antiga. A mesma revogação alcança logout/bloqueio remoto e desativação de funcionário; exclusão captura a audiência, remove os participantes órfãos e então fecha os sockets correspondentes.
Preferências locais do módulo não expõem IDs de canais ou clientes em texto claro. Conversas fixadas usam marcadores opacos com namespace próprio e migram automaticamente chat_pinned_channels_v1 para v2; o dismiss do convite WhatsApp converte a chave antiga baseada em client.id e remove o legado. Esses marcadores servem somente à interface por dispositivo — mensagens e autorização WhatsApp continuam tendo D1 como fonte de verdade.
A velocidade das notas de voz é compartilhada entre o player da conversa e a prévia do compositor, ciclando 1x → 1.5x → 2x. A preferência usa uiPreferenceStorage: persiste normalmente por dispositivo e mantém fallback em memória quando Safari privado, sandbox ou WebView bloqueia localStorage, de modo que players montados depois na mesma sessão continuam na velocidade escolhida. O estado de cada anexo pertence à conta autenticada, papel, canal, mensagem e URL: trocar qualquer um fecha o visualizador anterior e cancela entregas pendentes, sem herdar erro de codec, progresso ou bloqueio de abertura. A identidade de conta é separada do ID de cliente/funcionário usado pelas reações. A saída do player pausa o áudio e invalida rejeições tardias de play(); reutilizar o lightbox com outra URL também reinicia zoom/pan e gestos ativos. Conclusão tardia não libera o bloqueio da entrega nova; uma falha atual de documento continua visível e permite tentar novamente. Cancelar não recolhe uma folha de compartilhamento que já foi entregue ao sistema operacional — esse limite permanece para validação em dispositivo.
O alerta WhatsApp disparado quando um cliente escreve pelo app é um side effect posterior ao envio autoritativo do chat. Ele usa transporte autenticado com teto de 15 segundos, AbortSignal por sessão e contenção explícita da rejeição; não atrasa nem reclassifica a mensagem principal. Troca de identidade antes ou durante o relay invalida o epoch e aborta controllers ativos, impedindo trabalho tardio pertencente à conta anterior.
Anexos de imagem abrem no lightbox compartilhado com pinch, duplo toque e pan. A superfície usa o mesmo contrato dos bottom sheets: diálogo modal nomeado, scroll bloqueado, foco contido/restaurado, Escape apenas no topo da pilha e integração com back nativo. A ação de abrir/entregar o arquivo externamente bloqueia repetição e anuncia progresso. Inbox e chat embutido nos detalhes da tarefa encaminham o mesmo contrato completo de envio — conteúdo, URL de mídia, mensagem citada e cliente proprietário — portanto foto, arquivo e áudio mantêm anexo, contexto e destino de storage em qualquer ponto de entrada. Encaminhar uma mensagem DIRECT com anexo para um JOB primeiro copia o objeto para a árvore team da tarefa e só então move a mensagem, para que a equipe consiga abrir o arquivo sem poder ler a árvore privada Management; a troca exige que a linha ainda esteja no DIRECT, portanto uma segunda decisão concorrente não pode sobrescrever o JOB já escolhido e descarta sua cópia órfã. O Worker repete a fronteira: funcionário alocado pode acessar mídia do JOB atribuído, nunca mídia DIRECT/Management do mesmo cliente, e uma mensagem só aceita URL R2 do mesmo cliente, escopo e tarefa do canal. Criar, listar e cancelar agendamentos revalidam a mesma autorização do canal; um ID antigo não permite que alguém removido de uma conversa altere sua fila. O agendamento também valida a URL de mídia antes de entrar na fila. Chaves legadas sem ownership no caminho exigem ADMIN/MANAGER também na leitura, preservando recuperação administrativa sem expor arquivos antigos a usuários autenticados comuns.
Permissões de push também usam um contrato único. notificationPermissionProvider consulta, solicita e observa autorização; a Permissions API fica restrita ao navegador/PWA com listener removível, enquanto Android/iOS revalidam no resume e no registro APNs/FCM. O perfil recebe o mesmo estado sem manter uma implementação paralela por plataforma. notificationDeliveryProvider separa autorização do sistema e prontidão para entrega. No gate operacional, a concessão só conclui a etapa depois que a assinatura Web Push foi persistida com sucesso ou o token nativo persistido confirma um destino utilizável; falha ou timeout usa registration_failed, mostra que a permissão já está ativa e oferece nova tentativa sem classificar o problema como recusa do usuário. O perfil nativo comunica o mesmo timeout depois de devolver o controle ao botão. Ao restaurar a sessão, a checagem é somente leitura e o evento de registro nativo atualiza a etapa sem exigir reinício.
A lista My devices possui prontidão independente do seu snapshot. Antes da primeira resposta mostra verificação em andamento; somente uma resposta válida pode produzir No devices subscribed yet. Falha inicial ou de atualização mantém alerta persistente e retry, preserva qualquer lista anterior e marca o diagnóstico de registro backend como não verificável. Owner, lifecycle e passe final do single-flight continuam impedindo que uma resposta de outra sessão altere a tela em desktop, PWA, Android ou iOS.
As categorias de What sends a push usam o banco como fonte de verdade; a cópia local serve apenas para a primeira pintura. Login, retorno ao foreground e retry confirmam o snapshot com owner e sequência de request. Enquanto a leitura está pendente ou falhou, os toggles server-side permanecem bloqueados e a tela mostra status/alerta, sem confundir cache com configuração aplicada em outros dispositivos. Uma alteração otimista possui lock no mesmo frame; se o endpoint recusar, apenas disabledPushCategories volta ao último valor confirmado, o cache local acompanha o rollback e as preferências exclusivamente locais, como som e duração, são preservadas.
O destinatário que o renderer nativo consulta é atualizado por uma fila serial e limitada a três segundos. Se uma escrita antiga de Preferences terminar depois de timeout durante logout ou troca de conta, o app reaplica a audiência mais recente; a UI de autenticação nunca espera pela ponte e a identidade anterior não permanece como estado final do aparelho.
As APIs compartilhadas de preferências, inscrições/dispositivos, histórico/ações de notificação e banner global usam dez saídas atomicServerError e um registro específico de configuração VAPID. Falhas inesperadas de D1 ou criptografia ficam sanitizadas no painel; o cliente recebe retry estável. Estados funcionais continuam próprios: sessão/autorização, dispositivo já vinculado, VAPID ausente, nenhum dispositivo, rejeição do push e orientação de re-inscrição. A tela de diagnóstico nunca interpola a exceção que tornou o par VAPID inválido.
Na configuração do bot, os três modos de resposta são um grupo nomeado e cada cartão publica seu estado pressionado. Assim a seleção “Options menu / Keywords only / Every message” permanece compreensível por teclado, VoiceOver e TalkBack, sem criar uma interface alternativa ao toque.
Notas de voz e o checklist compacto usam o indicador quantitativo compartilhado: playback anuncia percentagem reproduzida; checklist anuncia itens concluídos sobre o total. A animação visual continua leve e decorativa, enquanto leitores de tela recebem valores estáveis.
Gravações de voz também obedecem ao lifecycle compartilhado. NativeBridge publica primecrown:app-pause e primecrown:app-resume; inclusive uma leitura inicial que encontre o shell já em segundo plano publica a pausa, sem fabricar uma retomada quando ele nasce ativo. O compositor encerra uma captura ativa ao receber a pausa nativa ou visibilitychange oculto, liberando o microfone e preservando o trecho como prévia não enviada. Os dois sinais podem ocorrer juntos sem chamar stop() duas vezes, e seus listeners são removidos no teardown. Assim, Android/iOS não deixam timer ou microfone ativos no background, enquanto PWA/desktop aplicam a mesma proteção ao ocultar a página.
Configurações do Chat usam CFInput nos editores de instruções do bot e mensagem de ausência e Button nas ações de salvar. Um lock síncrono precede a mutação e toda a superfície editável fica inert/aria-busy durante a tentativa. Instruções e mensagem são aparadas, e horário comercial ativo exige resposta não vazia. saveSettings precisa aceitar o snapshot antes de os stores compartilhados e o háptico de sucesso serem atualizados; falha mantém a edição local visível para retry sem fingir que o próximo boot preservará a mudança.
Uploads de foto, documento e voz no chat pertencem à combinação usuário+canal. O cliente multipart aceita AbortSignal; troca de conversa, conta ou desmontagem aborta o request e invalida envio, agendamento, toast e estado de loading tardios. Até uma callback de câmera mantida pela renderização anterior precisa provar que seu proprietário coincide com o epoch atual antes de iniciar o upload. A listagem de mensagens agendadas usa a mesma propriedade, impedindo dados do canal anterior após navegação rápida.
O compositor também pertence a usuário+canal. Texto digitado é mantido como rascunho separado por conversa, como em mensageiros nativos, sem reaparecer no destinatário seguinte. Trocar de canal limpa reply, menus, sugestões e prévia de voz; invalida câmera e rascunho de IA; e encerra somente a instância de gravador da tentativa anterior. Um rec.start() atrasado não fecha uma nova gravação nem publica áudio no canal seguinte, e dois starts simultâneos são bloqueados antes da resposta da permissão.
O sheet de sugestões inteligentes possui lock síncrono e token por geração. Toque duplo não cria requests concorrentes, e fechamento/troca de canal invalida a resposta antes de escrever sugestões ou loading na conversa seguinte. Quando a IA falha, retorna vazia ou ainda não há histórico, os chips prontos continuam disponíveis, mas o cabeçalho e uma região de status os identificam como Ready-made replies, sem atribuí-los falsamente à IA. A preferência pt-BR continua enviada ao endpoint para o conteúdo gerado; o fallback fixo segue o contrato de cópia inglesa da interface.
O envio textual possui lock síncrono no próprio compositor. Dois toques/cliques antes de o draft limpo voltar pelo React produzem uma única mensagem, mesmo que a API gere a chave de idempotência mais abaixo. Upload e abertura da câmera publicam aria-busy e desabilitam campo e envio; o botão tem nome explícito para VoiceOver/TalkBack. A textarea especializada permanece intencional: capitalização, correção e teclado textual são nativos, Return cria parágrafo no touch e Enter envia no desktop sem interceptar composição IME. A barra de digitação posiciona as opções no lado direito: com a caixa vazia, o botão de clipe/anexo fica visível à direita (com menus alinhados à direita); assim que o usuário digita qualquer caractere, o clipe se oculta e dá lugar ao botão de envio, alternando entre eles conforme o preenchimento do campo.
Mensagens aceitas sem conectividade mudam de Sending para Queued offline depois que o IndexedDB confirma a gravação. A fila guarda também o instante original e recompõe os balões ao reabrir PWA, Android, iOS ou desktop ainda offline. Uma migração de fila legada só preserva registros já vinculados ao mesmo proprietário; sem ownerUserId verificável, o conteúdo é descartado para não aparecer nem ser reenviado pela primeira conta após uma atualização. Gatilhos simultâneos do navegador e do plugin Network entram numa única drenagem serial; troca de conta aguarda a drenagem anterior e revalida o epoch. O Retry manual e a drenagem compartilham a tentativa em voo da mesma mensagem. Uma falha bloqueia apenas as mensagens seguintes do seu canal nessa drenagem, sem impedir o envio de outro DIRECT/JOB. Falha online vira Failed com botão Retry acessível, que reaproveita o externalId original e só remove o item local após confirmação do servidor. Um ACK recebido por WebSocket ou histórico durante o envio vale mesmo se a resposta HTTP se perder: o composer não mostra erro nem cria Retry desnecessário, e a bolha não volta a Failed. Uma leitura de histórico iniciada antes do ACK também não apaga mensagens confirmadas durante a espera. A chave é global e um retry só pode recuperar a mensagem do mesmo canal: se uma integração ou cliente reutilizar a chave em outra conversa, o Worker responde 409 neutro, sem expor conteúdo ou metadados do canal que já a usou.
O painel Inbox operations trata fila e alertas WhatsApp com locks síncronos por item. Retry, dismiss, send now, cancel e decisão de reabertura não aceitam dois toques antes do render; ações em itens diferentes preservam seus próprios spinners, e o sheet não fecha no meio de uma mutação. O conteúdo publica aria-busy e emite feedback háptico somente após aceite. No ACK continua deliberadamente não reenviável — o destinatário pode ainda receber a tentativa original — e o estado vazio diz apenas que não há alertas pendentes, sem afirmar entrega que não foi comprovada.
No Worker, send_now e cancel aceitam exclusivamente registros PENDING. Um item PROCESSING já foi reivindicado atomicamente pelo runner e aparece como In flight, sem ações: recolocá-lo ou apagá-lo nesse intervalo poderia duplicar o envio ou remover um balão que chegou ao WhatsApp. Os textos do painel não falam em janela de envio (na coexistência a fila só tem novas tentativas e retidos pela janela de 24 h), e o alerta “sem ACK” diz qual gateway aceitou o envio (messages.transport). send_now limpa o last_error e acorda o runner com CRON_SECRET (o que isCronCaller aceita — com JWT_SECRET o pedido levava 401 e a mensagem esperava o cron de 5 min). A condição é repetida no SELECT e na mutação; se o runner vencer a corrida, a API responde 409 e o painel recarrega. Falha de D1 ao listar fila/alertas retorna 500 estável e mantém o último estado visível, nunca um falso success: true com lista vazia.
O despachante de mensagens agendadas pode rodar tanto pelo cron quanto pela leitura de canais. Cada agenda materializa a mensagem com uma chave externa derivada do seu próprio ID; a unicidade D1 reivindica essa materialização antes de broadcast, push ou entrega WhatsApp. Assim duas execuções sobrepostas não criam duas mensagens nem duas entregas para o mesmo horário.
Retry e resolução de alertas também reconciliam a conversa aberta pelo Durable Object. Reenfileirar transmite pending; descartar uma falha cuja mensagem foi mantida limpa o estado da fila; reconhecer No ACK persiste e transmite deliveryAlertDismissedAt. Esse marcador integra o tipo compartilhado, o mapper HTTP, o merge/payload WebSocket e isUnconfirmedWhatsAppSend, portanto o alerta desaparece imediatamente e continua ausente após reload, sem exigir fechar a conversa nem sugerir reenvio.
Falha total ou parcial ao carregar Inbox operations não é apresentada como lista vazia. O último snapshot permanece visível com alerta persistente, o ícone fechado recebe marcador e nome “data may be out of date”, e um retry explícito anuncia loading sem competir com o polling serializado. Estados Nothing waiting / Queue is empty / No delivery failures só aparecem quando a leitura atual foi confiável; o polling continua silencioso em toast para não interromper o operador repetidamente.
Cada montagem de Inbox operations também delimita um ciclo de vida. Logout, troca de identidade ou desmontagem invalidam a leitura ativa e todos os resultados de ações ainda pendentes antes que possam alterar listas, busy state, toast, háptico ou callbacks do inbox anterior. O lock da leitura usa um token por request, não apenas um booleano: a remontagem de desenvolvimento do React Strict Mode pode iniciar uma leitura nova sem a resposta antiga limpar ou sobrescrever seu loading.
O pedido de reabertura do funcionário segue o mesmo ownership. Um lock por ref fecha a janela de toque duplo antes do render; Waiting for a manager, háptico e sucesso só aparecem depois de success=true. Recusa e exceção preservam a ação para retry. ownerKey=channelId remonta a notice na troca de conversa, invalidando a conclusão antes de estado, toast ou callback e impedindo que askedNow atravesse canais; somente um aceite solicita refresh da lista.
O save das configurações do chat comunica seu estado ao shell. Enquanto a persistência atômica está pendente, edição, Back interno, tabs do sidebar, troca de seção, backdrop, Escape e gestos de histórico permanecem bloqueados pelo mesmo isChatSettingsSaving. Uma desmontagem forçada, como logout, incrementa o lifecycle epoch e impede que o snapshot, toast ou háptico da identidade anterior seja publicado; a tela só destrava no finally pertencente à execução atual.
O diagnóstico Delivery Health não infere saúde da ausência de dados. Antes da primeira resposta, Line/Queue/Failures mostram Checking; após falha sem snapshot, mostram Unknown, nunca LOW, 0 pending ou 0 failed. Se já existe leitura confirmada, ela permanece visível com alerta de possível desatualização. Entrada automática e botão Refresh reutilizam o mesmo token/lock; saída da seção ou sessão invalida a resposta, e o botão canônico anuncia loading e bloqueia toque concorrente nas quatro plataformas.
Busca por mensagem citada, cancelamento agendado e exclusão usam o mesmo epoch. Os dois requestAnimationFrame necessários para aguardar o prepend do histórico são registrados e cancelados no teardown; cada frame revalida o canal antes de rolar ou destacar. Rollback da agenda e toasts de exclusão também são ignorados depois da troca, evitando foco e feedback pertencentes à conversa anterior.
O dashboard contextual de cliente/funcionário também pertence à identidade selecionada. A identidade tipo:id e os valores atuais de nome, e-mail e telefone invalidam save/timer anteriores e repõem o formulário, portanto uma sincronização externa da mesma pessoa não deixa o editor com dados antigos. O save usa lock síncrono, captura cliente/funcionário antes do await, aguarda a persistência com rollback da store e só então apresenta háptico/estado Saved; teardown limpa o indicador temporário. A lista de adiantamentos ordena uma cópia, de modo que abrir a aba Payroll nunca muda silenciosamente a coleção compartilhada da store.
💬 1. Arquitetura do Chat e Tipos de Canais
Section titled “💬 1. Arquitetura do Chat e Tipos de Canais”graph TD
subgraph UI ["Interface do Chat (src/components/chat/)"]
Inbox["ChatInbox.tsx (Painel Geral)"]
Sidebar["ChatSidebar.tsx (Lista de Clientes & Grupos)"]
MessageList["ServiceMessageList.tsx (Visualizador)"]
end
subgraph Channels ["Tipos de Canais no D1"]
Direct["Channel DIRECT: Suporte Direto Cliente ↔ Gerente"]
Job["Channel JOB: Grupo Operacional do Serviço (Cliente + Equipe)"]
end
subgraph Infrastructure ["Infraestrutura de Mensageria"]
DO["Durable Objects (ChatChannelDO) - Realtime WebSockets"]
WA["Meta Cloud API"]
end
Inbox --> Direct
Inbox --> Job
Direct --> DO
Job --> DO
DO <--> WA
Os canais nascem com o registo, nunca ao abrir. Toda visita (menos QUOTE, hasTeamChannel) tem o seu canal JOB, com a equipa alocada como participante, e todo cliente tem o seu DIRECT (um por grupo de contacto, herdando a conversa de lead) a partir do momento em que a linha existe: provisionChannelsFor (functions/api/channels/provisionChannels.ts) corre depois de cada escrita que cria visita ou cliente — extensão de séries, confirmação de orçamento, visits/book, cadastro Google, /atomic/clients — e o dispatch-scheduled (5 min) corre provisionMissingChannels como rede para o que escapar: só cadastros e visitas com updated_at desde a última passagem (a marca fica dois minutos atrás), mais uma leitura completa por dia para canal apagado ou linha cujo updated_at não se moveu. Antes, a extensão de séries e o fecho de orçamento gravavam visitas sem canal, e a Inbox só as mostrava depois de alguém abrir o chat nos detalhes da tarefa. Como o canal existe sempre, uma visita de série só conta como “tocada” (removeUntouchedLater) se o canal tiver mensagem; ao remover a visita (série ou delete de admin) o canal JOB sai junto.
Grupo de contacto = número partilhado. Cadastros que partilham um número (contact_group_id, 0113) dividem a conversa DIRECT daquele número e o acesso: o perfil do escritório e quem entra no app veem as visitas e faturas de todos (clientScopeIds, personContext). Nada muda de dono — visitas, preços e faturas ficam no cadastro de origem — e as conversas antigas não se juntam. A regra de “mesmo número” é uma só (src/shared/contactGroupMatch.ts: celular, telefone e WhatsApp normalizados). Entrar: ao salvar no formulário do cliente (ClientModal) um número que já é de outro cliente ativo fora do grupo, o escritório vê o aviso com os nomes e escolhe Save and group ou Back; só com essa confirmação o save leva joinContactGroup (nunca guardado em cache) e o servidor confere o número e agrupa (joinGroupBySharedPhone, entrando num grupo que já existe). Outros caminhos (importação, conversão de lead, Google) nunca agrupam. Sair: um save cujo número já não bate com nenhum outro membro tira o cliente do grupo (leaveGroupWithoutSharedPhone); sobrando um só, o grupo acaba, e quem saiu ganha a sua DIRECT na hora.
Abrir uma conversa por link (push, sino, Quotes, chat nos detalhes da tarefa) põe o filtro da lista em All (useChatSelection), nunca no tipo do canal: o filtro sobrevivia ao link, e a linha do cliente passava a mostrar só o Manager, como se o grupo da tarefa não existisse.
As listas de conversa (gestor, equipa, filtro) ordenam e escolhem a prévia da linha pela última mensagem (channelActivityAt, src/shared/channelActivity.ts), nunca pelo updated_at do canal: quando o provisionamento criou 482 canais de tarefa de uma vez, cada cliente passou a ter uma conversa vazia “mais recente”, e a lista inteira mostrava “No messages yet” com as conversas reais enterradas no fundo. Um canal sem mensagem não tem atividade.
A conversa, todos os perfis (2026-09-30). Um só cabeçalho (ConversationHeader) para gerente, funcionária e cliente: voltar → quem é (avatar com a janela de 24 h e o crachá só para a equipe; o cliente vê só Manager/Team) → atendimento (Take over no escritório; no celular só o ícone) → seletor Manager/Team (ChatConversationSwitcher, não para a funcionária; ambos padronizados na mesma altura vertical de 36px h-9, cantos rounded-xl, tipografia e chevron harmônicos). Os botões adicionais (nova cotação, link da conversa) foram retirados da barra para manter a área limpa e ficam acessíveis pelo menu de clique direito no contato (ConversationContextMenu), que traz perfil, cotação, link, atendimento e alternar lida/não lida. A tarefa é uma linha só (JobContextBanner); dois ou mais orçamentos abertos dobram numa linha “N open quotes” (OpenQuotesStack); duas ou mais mensagens agendadas viram um chip que abre a lista. No celular, toda conversa abre na mesma camada (MobileConversationLayer: tela cheia, faixa azul no topo, gesto de voltar pela pilha de modais, abaixo dos modais), a do cliente e a da equipe. A busca segue flutuante no canto superior direito da conversa (escolha do Rafael, 2026-10-01). Avisos, “Latest”, divisor de novas mensagens e a busca falam pt-BR por t(); um erro que o servidor manda segue como veio.
Caixa do escritório (2026-09-30; barra 2026-11-08). Sem cabeçalho nem os seletores Messages/Directory/Settings: uma linha com a busca (nome, apelido, rótulo da tarefa, telefone por dígitos) e o menu ⋯ (Resolvidas, Assumidas por outros, Send queue, Preferences, WhatsApp health, System só no PWA de chat avulso, e Messaging settings, que sai para Settings → WhatsApp); sob as pílulas, uma linha âmbar só enquanto algo espera um gestor — pedidos de reabertura, envios que falharam ou parados na fila (ChatOpsPanel, attentionCount), ou quando essa contagem não pôde ser lida (Não foi possível verificar…, loadError) —, que abre o painel de decisões na aba mais urgente; a fila normal não acende nada e abre por Send queue; embaixo, as pílulas StateFilterPills numa linha que rola no celular e quebra em linhas do md para cima, onde não há dedo nem barra de rolagem (singleLine): filtros por status específicos (Minhas · Sem responsável · A responder) sem pílula All (quando nenhuma pílula está selecionada, todas as conversas ficam ativas), contando contatos, não fios (inboxFilters.ts). Waiting é a regra do Dashboard (/api/channels/activity, a última fala humana é do contato e a conversa não foi resolvida), relida quando a caixa se move. Conversas podem ser marcadas como resolvidas tanto pelo menu de contexto (ConversationContextMenu) quanto pela janela de atendimento (ChannelAssignmentControl): ao marcar como resolvido, o gestor alocado é liberado automaticamente e a conversa é retirada das filas de aguardando resposta (Waiting / to reply) e sem responsável (Unassigned), mesmo que a última mensagem tenha sido do cliente. O acesso às conversas em grupos de um cliente (abertas e arquivadas) é feito a partir da conversa principal, pelo seletor de conversas (ChatConversationSwitcher) no cabeçalho. O agrupamento por contato (DIRECT + tarefas) não muda. O Directory saiu (a lista de pessoas é People; toda pessoa já tem a sua DIRECT); o nome no cabeçalho da conversa abre a ficha (PersonProfile) numa folha lateral dentro de Mensagens (ContactProfileSheet; no celular, tela cheia por cima da conversa) — de alguém da equipe ainda leva a People, que tem os diálogos da ficha de staff, e o antigo UserDashboard e o NewDirectMessageModal, que nada abria, foram apagados. Funcionária e cliente seguem com as próprias telas (ChatHome, ClientChatView).
A caixa do escritório mostra 30 contatos por vez (CONTACTS_PER_PAGE, ChatSidebar), da última mensagem para trás, com Show more para os seguintes; busca ou filtro voltam à primeira página, e a linha do cliente aberto fica sempre listada. É paginação de exibição: /api/channels continua a devolver todos os canais, porque o app inteiro os lê (contadores, detalhes da tarefa, Quotes, Leads). A lentidão da lista vinha da distância, não do volume: a API corria em São Paulo e o D1 está em Londres, ~300 ms por consulta encadeada; o [placement] mode = "smart" do wrangler.toml põe a API junto do D1.
2. Ordem da lista
Section titled “2. Ordem da lista”As listas de conversas (a caixa do escritório, ChatSidebar; a da funcionária, employeeInboxGroups) seguem a ordem de chegada: a última mensagem primeiro (channelActivityAt). Não lidas não sobem — abrir uma conversa não a tira do lugar (2026-10-15). Com uma pílula ligada (Unread, Waiting…), a conversa aberta a partir da lista continua listada enquanto estiver aberta, mesmo depois de lida ou respondida; some quando se sai dela (outra conversa, voltar à lista ou outra pílula). Não há aviso de tempo de resposta na linha: o triângulo vermelho (ResponseSlaBadge) saiu por atrapalhar; quem espera resposta é o filtro Waiting.
2b. Um cliente, uma porta: a conversa direta com os grupos dentro
Section titled “2b. Um cliente, uma porta: a conversa direta com os grupos dentro”Na caixa do escritório (ChatSidebar), tocar num cliente abre sempre a conversa direta com ele (sem conversa direta, o grupo de tarefa mais recente); não há mais a lista “Manager + tarefas” sob a linha, nem o atalho “+N tarefas”. A linha mostra, além do total, um selo azul com as não lidas dos grupos de tarefa. A lista da equipe (ChatHome) mostra uma linha por cliente e abre a visita relevante; as demais visitas autorizadas ficam no histórico. A equipe não tem conversa direta com o cliente.
A conversa privada com Manager mantém somente suas próprias mensagens. Na navegação fixa, Team soma as não lidas e as mensagens retidas de todas as visitas daquele cliente; por isso o toque em Team abre a visita com a mensagem não lida mais recente quando a visita atual não tem nenhuma (teamEntry) — antes o número aparecia e a conversa aberta não tinha nada novo (caso da Claire, 2026-11-06); o histórico dá acesso explícito às outras visitas, sem inserir cartões dentro do texto privado. As mensagens retidas são lidas e liberadas na própria visita (HeldMessageRelease), com a mesma autoria e tradução. /api/channels continua trazendo heldMessages apenas para gestor/admin. Nenhuma mensagem é copiada entre tarefas para compor essa apresentação.
Liberar uma mensagem retida é a primeira ação do menu dela (botão direito, setinha, segurar o dedo) — na conversa da visita; não há mais botão sob a nota, que mostra só “On hold” e o inglês. Liberada, a nota amarela sai da conversa: fica a cópia que saiu (assinada pela pessoa da equipe), publicada no app (releaseHeldNote já gravava essa cópia; o ServiceMessageList esconde a nota RELEASED).
Janela de 24 h fechada na conversa direta: o aviso ocupa o lugar da caixa de envio no mesmo formato — uma pílula de 48 px (“WhatsApp’s 24-hour window is closed”) e, para o escritório, o botão redondo verde que abre o WhatsApp Business no lugar de enviar; sem a segunda linha de instruções.
O gestor modera a conversa toda: Encaminhar para um grupo de tarefa e Mover para a conversa com o gestor valem para qualquer mensagem — do cliente, da equipe ou nossa (antes só para o que o cliente escreveu; o servidor já aceitava qualquer uma de gestor/admin). Uma nota interna movida continua nota interna.
2c. Fotos: álbum e foto com texto
Section titled “2c. Fotos: álbum e foto com texto”Só desenho — nada muda no banco. Duas ou mais fotos seguidas da mesma pessoa, pelo mesmo caminho, sem texto, com até 1 min entre uma e outra e no mesmo dia viram um álbum (groupAlbums, chatAlbums.ts; ImageAlbum): grade 2×2, a quarta mostra “+N” e abre as demais; tocar numa foto abre o visualizador; o menu do álbum (botão direito, segurar) oferece Selecionar, e no modo de seleção (ou com a busca aberta) as fotos voltam a aparecer uma a uma, para apagar ou encaminhar cada uma. Uma foto com texto vira dois balões: a foto sozinha (com a pontinha) e, embaixo, o texto no seu balão com a miniatura da foto e “Foto” no topo, como uma citação — tocar nela abre a foto.
2a. Menu da mensagem
Section titled “2a. Menu da mensagem”Cada balão tem um menu de ações (MessageActionMenu, src/components/chat/), aberto de três jeitos: botão direito no computador (no ponto do cursor), a setinha que aparece no hover (também pelo teclado), e segurar o dedo no celular (uma folha por baixo, com a mensagem no topo e vibração leve no app). Os ícones soltos ao lado do balão saíram. Um texto já selecionado dentro do balão mantém o menu do navegador, com o Copiar dele. Deslizar o balão para a direita responde, como no WhatsApp (longe da borda esquerda, que é o gesto de voltar). O que o menu oferece depende de quem lê e da mensagem: Responder, Copiar texto, Ver original/tradução (equipa), Encaminhar para grupo de tarefa e Mover para o direct (o que o cliente escreveu, gestor), Fixar no topo e Nova visita ou cotação (gestor/admin, conversa de cliente ou lead: abre a janela Nova visita, que alterna entre agendar e cotar), Selecionar e Apagar (a regra de sempre: autor ou escritório, até 1 h, nunca o que o cliente escreveu — canDeleteMessage). Selecionar entra num modo de várias mensagens: copiar juntas (com hora e autor) ou apagar, só quando todas podem ser apagadas; Esc ou o X saem. Reagir continua desligado (REACTIONS_ENABLED); quando voltar, os emojis aparecem no topo do mesmo menu.
Mensagem fixada. O escritório fixa uma mensagem por conversa (POST /api/channels/:id/pin, { messageId | null }, gestor/admin); ela aparece numa faixa acima da conversa para todos que a leem — o cliente também —, por isso nunca uma nota interna nem uma mensagem retida da equipa (422). Fica em channels.pinned_json (migração 0217) como retrato (ChannelPin: id, prévia de uma linha, autor, quem fixou), vem em /api/channels como pinned e chega aos outros pelo socket (channel_pinned). Um toque na faixa leva à mensagem; o X do gestor desafixa. Com mensagem fixada, a busca da conversa fica dentro da faixa (que ocupa a largura toda) em vez de flutuar sobre o canto do chat. Na folha do celular, a mensagem aparece inteira, rolando dentro de uma caixa de até 30% da altura, e as ações ficam abaixo. A mensagem apagada (à mão, pela retenção, com um lead) ou movida para outra conversa leva a fixação junto: dois triggers em messages (messages_unpin_on_delete, messages_unpin_on_move).
Caixa de envio. Desenhada como a do WhatsApp (2026-10-15): sem barra própria — o fundo da conversa (chat-canvas, na raiz do ServiceChat) corre por baixo, e a caixa é uma pílula branca com sombra levíssima, 48 px, que cresce com o texto. O clipe fica dentro dela e não some ao digitar (o menu leva Arquivo, IA, respostas rápidas, nota interna e Send later, que antes só era alcançável com a caixa vazia); a citação de resposta fica dentro da pílula, em cima do texto. À direita, um botão redondo na cor da rota (resolveSendChannelKind): azul no app — conversa da tarefa, conversa com um funcionário e cliente que recebe no app (appFirst) —, verde no WhatsApp. Microfone com a caixa vazia (só numa conversa direta — mayRecordVoice: na conversa da tarefa ninguém grava voz, nem o escritório; a gravação saiu do menu do clipe) e enviar quando há texto. A gravação e a prévia de voz usam a mesma pílula. Margens laterais de 10 px no celular, iguais às da conversa, e poucos pixels abaixo (pb-safe-tight). No celular um balão vai até 88% da linha (68% a partir de sm), de propósito: a margem do lado oposto é o que mostra de quem é a mensagem — a 96% (bad19dd, revertido) não se distinguia mais quem escreveu.
Menu mais curto (2026-11-08). Saíram Salvar nas notas de acesso (as notas se editam na ficha), Dados da mensagem (os tiques bastam) e Enviar link do app pelo WhatsApp (o balão não entregue já oferece o WhatsApp; a rota /channels/:id/to-client foi apagada). Nova visita e Nova cotação abriam a mesma janela e viraram um item.
🛡️ 3. Política de envio do WhatsApp (sendPolicy.ts)
Section titled “🛡️ 3. Política de envio do WhatsApp (sendPolicy.ts)”Todo envio sai direto pela Cloud API da Meta no número em coexistência, sem risco de ban a contornar, então assessSendPolicy aplica uma regra só: a cota mensal da Meta (padrão 1.000 mensagens/mês, aviso em 800). A cota conta os envios do app e exclui as mensagens digitadas no aplicativo WhatsApp Business do celular (WHATSAPP_BUSINESS_APP), Instagram/Facebook e as linhas históricas do Evolution. Atingida a cota, envios automáticos e da fila ficam retidos até o dia 1 do mês seguinte (o “Send now” do operador passa); um número inválido é falha permanente. A janela de 24 h vale sempre: fechada, a mensagem fica HELD até o cliente escrever ou alguém escolher um template. Falhas da fila usam backoff progressivo (1, 5, 15, 60, 180 min).
🚀 5. Aprimoramentos de Comunicação Tripartite (Manager · Equipe · Cliente)
Section titled “🚀 5. Aprimoramentos de Comunicação Tripartite (Manager · Equipe · Cliente)”Para aprimorar a colaboração em campo e a comunicação direta com os clientes, foram introduzidos quatro recursos essenciais:
-
Notas Internas da Equipe (“Whisper” /
INTERNAL_NOTE):- Nos canais
DIRECTeJOB, a equipe (nunca o cliente) liga o modo Nota Interna no menu do clipe (canNote); enquanto está ligado, um selo âmbar acima do compositor diz isso e o×volta à mensagem normal. O botão fixo acima do compositor do JOB saiu (2026-09-29). - Mensagens dessa categoria são marcadas com
direction = 'INTERNAL'ecategory = 'INTERNAL_NOTE'. - Isolamento e Segurança: O endpoint
POST /api/channels/:id/messagesnão despacha notas internas para o WhatsApp nem para push notifications do cliente (isInternalNote: trueemnotify.ts). Uma nota só pode citar outra nota: cliente ou resposta pública de staff não consegue usar sua ID para reexibir o preview privado. Na leituraGET, usuários com papelCLIENTtêm essas mensagens filtradas (ne(messages.category, 'INTERNAL_NOTE')) e qualquer preview interno de uma linha legada ou broadcast compartilhado é ocultado. Tempo real (2026-09-29): o relaychat-domarca cada socket comostaffouclient(cabeçalhoX-Prime-Viewer, posto por/api/channels/:id/websocketa partir do papel); num socket de cliente um eventomessagesperde asINTERNAL_NOTEe um eventostaffOnly(a tradução de uma nota) não vai. Antes, toda mensagem ia a todos os sockets do canal — uma nota em JOB chegava ao cliente com a conversa aberta. Socket sem marca conta como cliente. Exigedeploy:backenddo chat-do. - Interface Visual: As mensagens internas são exibidas com estilo âmbar suave e um distintivo de cadeado
🔒 Internal Note · Team only.
- Nos canais
-
Polimento por Inteligência Artificial (
POST /api/ai/polish-message):- Botão “Polish” (ícone Sparkles) disponível no compositor para funcionários e gerentes ao redigirem mensagens para o cliente.
- O endpoint usa o modelo de
polishMessageno Workers AI. O botão altera o rascunho. O envio usa o texto que está no compositor.
-
Ações Rápidas em 1 Toque: removidas em 2026-09-29 (
QuickActionChips, a barra acima do compositor do JOB). O aviso de atraso continua noTransitDelayModal(/api/channels/transitNotice). -
Indicador Dinâmico de Audiência e Escopo:
- Selo visível sobre o compositor informando para quem a mensagem será enviada antes do envio:
- Client & Team · Delivers to Client WhatsApp (canal da tarefa)
- Client & Management · Direct WhatsApp (conversa direta)
- Internal Note · Visible to Team & Management only (modo nota interna ativo)
- Selo visível sobre o compositor informando para quem a mensagem será enviada antes do envio:
-
Resolução Canônica de Canais DIRECT (
POST /api/channels):- Criação ou recuperação de canais DIRECT resolve a entidade via
ensureDirectChannel. - Se o identificador informado pertence a um lead mesclado (
merged_into_id), o canal do lead canônico é retornado em vez de criar uma conversa em branco paralela. - Agrega leads irmãos que compartilham o mesmo número de telefone (
liveLeadIdsByPhone), reusando canais existentes e unificando conversas de leads convertidos para clientes. - A reconciliação histórica
0133_merge_duplicate_leads_and_channels.sqlusa ambos os campos de telefone, normaliza variantes locais/internacionais e nunca considera campos vazios como identidade. Antes de remover o canal redundante, move mensagens e agendamentos para a conversa canônica; conflito de cotaçãoOPENé resolvido de forma determinística. - No painel de cotações (
QuoteConfirmationPanel), a visualização do orçamento é estritamente de leitura (sem provisionamento prematuro de canais emuseEffect), e o envio da mensagem reutiliza o canal direto existente do contato. - Canais de leads mesclados são filtrados em
GET /api/channels, evitando duplicação na listagem da caixa de entrada.
- Criação ou recuperação de canais DIRECT resolve a entidade via
-
Contexto de Cotação Ativa no Atendimento (
QuoteContextBannereCompactQuoteDetailPanel):- Ao abrir uma conversa com um lead ou contato que possui cotação pendente (
OPEN), o topo do chat exibe um banner com serviço, valor e horas (como o das tarefas): no desktop o toque abre o painel; no celular, ao expandir, o atalho para revisar é só o ícone. - O painel lateral não repete tipo de serviço nem preço/esforço (já estão na barra): mostra timing (período + frequência + semana), endereço e itens, com o atalho de revisão no canto.
- Ao abrir uma conversa com um lead ou contato que possui cotação pendente (
🛠️ 6. Arquivos Principais do Módulo
Section titled “🛠️ 6. Arquivos Principais do Módulo”- Inbox Principal:
src/pages/ChatInbox.tsx - Compositor & Input:
src/components/chat/ServiceChatInput.tsx - Hook de Mensagens:
src/features/communication/hooks/useMessages.ts— WebSocket via Durable Object; poll HTTP só como fallback - Hook de Canais:
src/features/communication/hooks/useChannels.ts— lista da inbox: load inicial + refresh ao focar a aba + reconcile lento (60s) só com tab visível (sem poll a 8s) - Tradução: o cliente consulta em lote traduções persistidas das bolhas visíveis. Veja Tradução no chat.
- Endpoint AI Polish:
functions/api/ai/polish-message.ts - Webhooks: WhatsApp só pela Meta,
functions/api/whatsapp/meta-webhook.ts; Instagram/Facebook pelo Chatwoot,chatwoot-webhook.ts(qualquer outra caixa é ignorada). - A Meta entrega só a nós (2026-10-06; ponte retirada em 2026-11-12, 0282): o número +44 20 3951 5120 tem
webhook_configurationpróprio na Meta, que vale mais que o do app e o da WABA. O onboarding do Chatwoot já o apontou para o Chatwoot, e então a mensagem chegava só ao celular e a janela de 24 h aparecia fechada no app. Aponta para/api/whatsapp/meta-webhook, que grava a mensagem e não repassa nada. O painel de saúde vigia isso (metaWebhook,metaWebhookRoute.ts): a leitura do número na Meta (readMetaNumberStatus) traz owebhook_configuration, vale o nível mais específico (número → WABA → app) e, se não for o nosso/api/whatsapp/meta-webhook— o Chatwoot incluído —, fica DIVERTED: alerta críticoMETA_WEBHOOK_DIVERTEDna barra dos admins (consultada a cada 3 min), em System Errors (no máximo a cada 6 h) e no vigia horário da linha (lineWatch.ts). Sem resposta da Meta, o estado é UNKNOWN. - Durable Object (WebSockets):
chat-do/src/index.js— relay de mensagens + cron*/5para dispatch/auto-lock/fila WA. A rotina semanal do Google Business Profile saiu do app; as publicações vivem emsocial/no repositório do site.
Auditoria de acesso 2026-09-12
Section titled “Auditoria de acesso 2026-09-12”- Canais: toda sub-rota de
/api/channels/:id/*passa porcanAccessChannelByIdou exige ADMIN/MANAGER (participantes, encaminhar, mover para direto, templates, pedidos de reabertura). A funcionária nunca abre a conversa DIRECT de um cliente com a gerência; o canal JOB é, por desenho, a conversa do cliente com a equipe da visita — o cliente não adiciona participantes nem vêINTERNAL_NOTE. - Tempo real: o Durable Object do chat só é alcançado pelo binding do Pages depois de
websocket.tsvalidar sessão e acesso; ofetchdo Workerchat-donão repassa nada ao DO. - Webhooks: Meta confere HMAC-SHA256 do corpo cru em tempo constante e recusa sem App Secret; Chatwoot confere
X-Chatwoot-Signature(HMAC-SHA256 detimestamp.corpocom o secret do webhook, timestamp de até 5 min) e só sem secret salvo aceita o token da URL, em tempo constante. - Cron:
/api/cron/*e/api/whatsapp/process-queueexigemCRON_SECRETcomo bearer (isCronCaller). O Workerchat-doé quem chama e não enviaJWT_SECRET. /api/messages/:id/deliveredé aberto de propósito (o service worker não tem sessão) e só marca entrega de mensagem ainda não entregue, nunca de saída para cliente com WhatsApp autorizado.
O simulador de WhatsApp (Settings) foi removido. Era um menu fixo que não correspondia ao bot real. Fica só o Send test, que envia uma mensagem real.
O chat do cliente não calcula mais urgência por IA. A gravação na visita é só para a equipe, então o cliente recebia “Sync Rejected” depois da própria mensagem. E o alerta de urgência ficava só na sessão do cliente: nenhum gerente via.
- Nada some sem rastro (2026-11-08, migração 0264): resolver uma conversa grava quem (
channels.resolved_by) e quando; se o contato ainda esperava, deixa na conversa uma nota interna Resolved without a reply by Ana (setConversationResolved,externalIdresolved-unanswered:), escrita antes doresolved_atpara não reabrir a conversa, e o card Hoje conta essas por pessoa. O menu de atribuição mostra Resolvida por Ana · 08/11 14:02. Sob a última mensagem de um cliente ainda sem resposta, o escritório vê Vista por Ana · ainda sem resposta (SeenByLine,GET /api/channels/:id/readers: o cursor de leitura de cada pessoa ativa do escritório, atualizado pelo eventoreadsdo socket). A linha da conversa na lista fica vermelha com Não entregue quando a última mensagem é nossa e o envio pelo WhatsApp falhou (deliveryStatus: 'failed'na prévia; um gatilho emwhatsapp_queuemove a prévia quando o envio entra ou sai de FAILED). O rascunho de cada conversa fica no aparelho (IndexedDBchat-drafts, junto da fila offline, apagado ao sair da conta) e volta ao reabrir o app. - Só o escritório ativo (2026-11-08): todo push ao escritório (mensagem nova, retida, reabertura, e-mail, lead, ligação, espera) e todo gerente que pode receber uma conversa leem
activeOffice()(functions/api/common/activeOffice.ts): um gerente desativado não recebe push nem conversa, e uma conversa ainda presa a ele volta a avisar todos. O alarme por palavra-chave (“falar com humano”,isEscalationText) saiu: era um segundo push por mensagem e disparava com qualquer frase que citasse “manager”; o aviso de espera cobre o cliente sem resposta. - Mensagem não recarrega o diretório (2026-11-08, migração 0263): uma dúzia de gravadores de mensagem toca
channels.updated_at, e o gatilho da 0260 contava esse toque: cada mensagem movia a revisão do diretório e cada sessão aberta do escritório relia a lista inteira de contatos. Oupdated_atsaiu do gatilho; os campos que a lista mostra continuam (bloqueio, reabertura, dono, atribuição, fixada, resolvida), e a primeira/última mensagem segue movendo pela 0261. Uma mensagem nova chega só pela prévia incremental. O que precisa acompanhar mensagens novas (o card de Mensagens no Dashboard e a pílula A responder) relê quando muda a última mensagem das prévias (latestActivityAt,src/shared/channelActivity.ts), não oupdatedAt. Junto, a exclusão de conversa no inbox voltou a atualizar o painel (a chave da consulta estava embrulhada num array a mais). - Cliente sem resposta (2026-11-08): uma regra só: está esperando o contato que escreveu depois da nossa última resposta que chegou (
waitingConversation,src/shared/messagesActivity.ts). O banco conta isso numa consulta sobre a janela inteira (readUnansweredRunsemfunctions/api/channels/activityMessages.ts: lê a faixa de datas uma vez pelo índiceidx_messages_activity_timee devolve só as conversas em espera, nunca as mensagens), usada pelo card e pelo cron (readWaiting,activityLoad.ts). Uma resposta nossa cujo envio pelo WhatsApp falhou (filaFAILED) não conta — o balão já mostra a falha. Passado o tempo de aviso a espera de um cliente ou lead está atrasada: a conversa volta para a caixa focada de todos os gestores, mesmo assumida por outro (overdueWaits/inInboxView), e, nos dias e horas de aviso, a rotina da fila (alertOverdueWaiting, emprocess-queue: o cron de 5 min e os envios a chamam; no máximo uma vez por minuto) manda push a todos os gestores e admins ativos no tempo de aviso e no lembrete — uma vez por etapa, estado emsystem_settingschat.waitingAlerts; esperas acumuladas fora do horário avisam uma vez na abertura, e mais de 3 novas numa rodada vão num push só. Os tempos e dias ficam em Configurações → Automatic messages → Clients waiting for a reply (chatConfig.waitingAlertMinutes15,waitingReminderMinutes60 com 0 = sem lembrete,waitingWindowDays15 entre 1 e 60,waitingAlertDays/Start/Endseg–sex 08–18 de Londres, independentes da mensagem de ausência), lidos só porreplyWaitTimes, com os padrões emsettingsDefaults.ts; dias e horas usam o seletor da mensagem de ausência (OpenHoursFields). O selo de Messages da navegação continua sem contar o que outro gestor segura. - Mensagens no Dashboard do escritório (2026-09-28): um card logo abaixo de Hoje (
MessagesActivityCard, dados deGET /api/channels/activity, só gerente/admin, regra emsrc/shared/messagesActivity.ts) mostra, sem contar linhas do bot/sistema e notas internas: Esperando resposta (o contato escreveu depois da nossa última resposta que chegou, na janela configurada; uma reação nossa, como 👍 num “obrigado”, conta como resposta; ordem pela espera mais longa, em âmbar a partir de 30 min e vermelho a partir de 2 h; quem está cuidando = o manager atribuído, senão quem respondeu por último; cada linha traz oChannelAssignmentControlde sempre, com tempo e atribuição para outro manager), Equipe falando com clientes (tarefa aberta,isOpenTaskGroup, em que alguém da equipe e o cliente escreveram nas últimas 24 h; “Cliente esperando” quando a última palavra é dele) e Hoje (cada pessoa do escritório: quantas esperas encerrou desde a meia-noite de Londres, em quanto tempo em média — da primeira mensagem do contato no último dia até a resposta — e quantas resolveu sem responder). Cada linha abre a conversa (setChatToOpen). Atualiza a cada minuto; some quando não há nada. - Resumos das conversas, “desde a sua última visita” e problemas no Issues (2026-09-28): o cron de 5 minutos (
dispatch-scheduled, passo 11) rodarunConversationDigests(functions/api/channels/conversationDigest.ts): pega até 4 conversas que tiveram mensagem humana nas últimas 6 h, estão paradas há 10 min e mudaram desde o último resumo, e guarda uma linha emchannel_digests(resumo em inglês e português, estado RESOLVED/WAITING_US/WAITING_CLIENT, tema, problema com nota). Econômico para caber nos 10.000 neurons grátis ao lado da tradução e do bot: incremental (resumo anterior + só as mensagens novas, até 25), sem IA quando não precisa (primeira mensagem curta ≤ 12 palavras vira o próprio resumo; “ok/obrigado” depois de um resumo só move o marcador, sem contar como novidade) e para de vez quando o gasto medido do dia (ai_usage_daily, todas as funções) passa deDIGEST_NEURON_CEILING(7.000). Função própria no seletor de modelos: Resumo das conversas. Quem lê o Dashboard não gasta IA. O card Mensagens mostra a frase do resumo (com o problema em vermelho) sob cada linha, o aviso de janela de 24 h do WhatsApp fechada ou fechando em até 3 h, e o bloco Desde {hora}: resumos atualizados desde que a pessoa marcou “Marcar como visto” (dashboard_seen, por usuário, no servidor; sem marca, as últimas 24 h), problemas primeiro, até 40. Relatado nas mensagens é um tipo do Issues (mesma contagem deuseOperationsIssues, badges incluídos), lido deGET /api/channels/activity?scope=problems— só a tabela de resumos, não as mensagens; o canto do cartão abre a visita (a da tarefa; numa conversa direta, a última do cliente antes da mensagem, senão a próxima —problemVisit) e a folha abre a conversa onde foi relatado ou marca como resolvido (POST /api/channels/activityclearProblem), e o problema só volta se o contato escrever de novo.
Número nos links de WhatsApp. Todo link wa.me/phone= (liberar no WhatsApp Business, encaminhar a mensagem do app, fatura, lead, widget) usa whatsappDigits (src/shared/loginIdentifier.ts), a mesma regra do login: um número britânico salvo sem código do país (07462 035766) vira 447462035766 — sem isso o WhatsApp diz que não consegue procurar o número porque falta o código do país. Um número que a regra não lê mantém os próprios dígitos.
-
Menu de contexto na lista de conversas e padronização de modais (2026-10-16):
- Menu de contexto com botão direito (
ConversationContextMenu): na lista de conversas do módulo Messages (ChatSidebareAdminClientGroup), o clique com botão direito abre um menu suspenso contextual com ações imediatas para o contato: (1) Abrir perfil do usuário (abre a ficha do cliente/lead ou a gestão de funcionário), (2) Assumir atendimento / Take over (atribui o atendimento da conversa diretamente ao gestor logado com atualização otimista instantânea e haptics, ou permite liberar atendimento caso já esteja atribuído), e (3) Marcar como não lida / Marcar como lida (alterna o estado de não lido da conversa). - Padronização do modal de tarefas encerradas (
ClosedTasksSheet): a janela aberta ao clicar em “Show archived tasks” / “Serviços encerrados” no desktop foi padronizada como modal centralizado (desktopPresentation="modal",size="md"), eliminando a abertura em tela cheia e mantendo a consistência visual com os demais modais do sistema.
- Menu de contexto com botão direito (
-
Exclusão permanente de conversas (ADMIN apenas, 2026-10-25): administradores podem excluir conversas inteiras no módulo Messages (via menu de contexto com botão direito na lista lateral, clique no perfil do contato no cabeçalho ou menu More em
ChannelAssignmentControl). A ação exige confirmação modal explícita não bloqueante (useConfirmation) e realiza o expurgo completo (hard delete) de todas as mensagens, mídias e anexos do bucket Cloudflare R2 associados, além da limpeza atômica de todas as tabelas dependentes no D1 (messages,channel_participants,scheduled_messages,channel_reopen_requests,channel_digests,reply_suggestions,channel_read_ack_queue,whatsapp_queue,whatsapp_routing_sessions,channels) e notificação em tempo real via broadcast doCHAT_CHANNEL_DO.
Nomes das telas (2026-10-22). Cada tela tem um nome só, igual no menu, na barra de baixo e no título: cliente e funcionária — Home e Messages; o cliente — Bills; a funcionária — Visits e Payments; o escritório — a barra também diz Messages (antes Inbox). A tela de mensagens da funcionária abre com o título Messages, e a linha com o escritório se chama Manager. No celular o menu lateral sempre abre com os nomes (recolher é escolha do computador).
Voz da empresa nas notas da equipe. Quando o texto de uma nota retida da equipe é um modelo nosso, e não palavras da funcionária (lembrete de pagamento — speaksForCompany, src/shared/companyVoice.ts), a cópia que chega ao cliente fala pela empresa: no app aparece como “Manager” (remetente BOT). A nota continua no nome da funcionária na conversa da tarefa; mensagens digitadas por ela seguem assinadas por ela.