Skip to content

Integração com WhatsApp & Webhooks (Meta Cloud API)

Integração WhatsApp & Webhooks (Meta Cloud API)

Section titled “Integração WhatsApp & Webhooks (Meta Cloud API)”

Estado actual. Linha viva: Meta Cloud API, direto do app; a ponte WhatsApp↔Chatwoot foi removida em 2026-11-12 (migração 0282) e o Chatwoot (conta 2) carrega só Instagram e Facebook. O Evolution foi removido em 2026-11-09 (migração 0266). App Secret da Meta é secret do Pages, não setting D1. Graph API: META_GRAPH_VERSION (v26.0). Cron/fila: CRON_SECRET.

Conversas. O canal direto não mostra “WhatsApp routing”; mensagens para o grupo da equipe são escritas dentro do app. O convite pelo WhatsApp continua a abrir a conversa correspondente.

Destino dos automáticos. Avisos automáticos e respostas do bot ficam na conversa principal do cliente (DIRECT), mesmo quando disparados por uma tarefa. As únicas mensagens retidas para liberação do gerente no chat são mensagens enviadas pelos funcionários (senderRole === 'EMPLOYEE'). Avisos de serviço (avaliação, invoices, recibos) não poluem o chat com mensagens automáticas retidas: o envio de faturas, links de avaliação e mudanças fica a critério manual do gestor através das respetivas janelas/modais. O histórico da visita e a avaliação conservam o vínculo com a tarefa de origem. A mensagem de confirmação de reserva informa serviço, data, horário e equipe.

O WhatsApp não passa pelo Chatwoot (removido em 2026-11-12, migração 0282: cópia dos eventos da Meta, espelho dos envios, hub da caixa API, transporte Chatwoot, varredura e ficha do cliente no contato). URL (https://chatwoot.primecrowncleaning.co.uk) e conta ficam no cartão Chatwoot em Settings → WhatsApp, gravados com a página (sem inbox ID); o token e o secret do webhook são segredos do cofre, CHATWOOT_ACCESS_TOKEN e CHATWOOT_WEBHOOK_SECRET (chatwootConnection, chatwootWebhookSecret), com o valor antigo do whatsAppConfig como reserva. O webhook da conta (/api/whatsapp/chatwoot-webhook, assinatura X-Chatwoot-Signature com o secret salvo; sem ele, o token da URL) só trata caixas Instagram/Facebook (detectSocialChannel): mensagem nova → processSocialChatwootMessage; eco de um envio nosso (prime_crown_origin com o par mensagem/canal) e recibos → a mensagem enviada por socialDelivery.ts. Qualquer outra caixa é só reconhecida (200). O Chatwoot não reenvia webhooks: o app responde 200 na hora e trabalha em waitUntil; uma falha vira CHATWOOT_EVENT_FAILED em System Errors.

Código de login nunca passa pelo Chatwoot. Template de autenticação (copyCode / categoria AUTHENTICATION) sai direto pela Graph API da Meta, como todo envio de WhatsApp.

Janela social de 1 hora (Instagram Direct / Facebook Messenger). Quando um lead ou cliente envia mensagem por Instagram Direct ou Facebook Messenger, o canal ativa uma janela de resposta social de 1 hora (socialDelivery.ts). Durante essa 1 hora: (1) respostas da equipe saem pelo canal social correspondente via Chatwoot; (2) o indicador da janela de 24h do WhatsApp não é exibido no chat; (3) a caixa de texto do compositor (ServiceChatInput) permanece liberada para digitação livre (não trava em templates por restrição do WhatsApp). Após a janela de 1 hora expirar, o sistema reavalia automaticamente a janela de 24h do WhatsApp: se fechada, o compositor volta a exigir templates e as mensagens voltam a sair por WhatsApp.

Escolhas persistidas de rota (cliente ou gerente) prevalecem sobre a inferência da última mensagem humana durante sua validade. Uma resposta citada é uma continuação explícita e segue o canal da mensagem original, desde que pertença ao mesmo cliente e a tarefa continue aberta. Uma citação cujo ID não seja encontrado, seja ambíguo, pertença a outro cliente ou a tarefa fechada segue diretamente para DIRECT, mesmo com contexto humano recente ou override vigente para outro JOB; pedido explícito de gerência sempre vence a citação. Tarefa fechada ou menu ainda sem resposta também mantém a mensagem em DIRECT.

O seletor de destino no chat apresenta as tarefas usando startDateTime retornado pela API, formatado em Europe/London, com identificador da tarefa como fallback para datas inválidas. A expiração visual acompanha o relógio compartilhado de foreground em web, PWA e shells nativos.

Token de verificação do webhook (2026-11-11). O que o registro do webhook na Meta precisa ecoar (hub.verify_token) é o segredo do Pages META_WEBHOOK_VERIFY_TOKEN, vindo do cofre (webhookVerifyTokenOf): nunca editável na tela (Settings → WhatsApp mostra só um aviso) e nunca trocado por uma gravação das configurações, que mantém o valor guardado — antes, a tela devolvia a máscara •••••••• e uma gravação a gravou como token em 2026-11-09 (nada parou: as mensagens se autenticam pela assinatura com o META_APP_SECRET; o token só vale no aperto de mão do registro). Enquanto o segredo não existe, vale o whatsAppConfig.webhookVerifyToken antigo. Trocar o token = registrar de novo o webhook do número (POST /<phone-id> webhook_configuration) e o do app (POST /<app-id>/subscriptions) com o valor novo.

O painel da Meta mostra primeiro o status do número (CONNECTED é o que envia e recebe) e o banner alerta quando ele não está conectado. code_verification_status é só o código de posse usado ao registrar o número: num número conectado, EXPIRED aparece neutro (“só é necessário para registrar o número de novo”), sem pedir ação.

Toda chamada à Graph API usa a versão de META_GRAPH_VERSION (wrangler.toml, hoje v26.0); o único padrão no código é functions/lib/whatsapp/graphVersion.ts.

Feita (2026-09-22) e hoje religada só pelo app: ver o roteiro abaixo (Religar o app WhatsApp Business). O antigo roteiro pelo Chatwoot (caixa WhatsApp Cloud, transporte Chatwoot) deixou de existir com a migração 0282.

Se a coexistência ou o número cair (roteiro de recuperação)

Section titled “Se a coexistência ou o número cair (roteiro de recuperação)”

Como está hoje (2026-11-11). Número +44 20 3951 5120 (phone number id 1294466993756880), conta do WhatsApp 1755835892280151, dono o portfólio Prime Crown Cleaning (2147644119180867); app da Meta “Prime Crown” (869378925986312) e o usuário do sistema Crown Messaging (dono do META_WABA_TOKEN) no portfólio Crown London (4185902488322685). O Chatwoot (Oracle) não fala com a Meta nem recebe WhatsApp (ponte removida em 2026-11-12, migração 0282); a antiga caixa API “WhatsApp” da conta 2 (inbox 9) foi apagada em 2026-11-12, e o canal WhatsApp antigo fica aposentado, sem credencial, com prime_crown_retired_whatsapp.rb impedindo qualquer chamada dele à Meta. Quem fala com a Meta é só o app, e ele nunca registra, descadastra nem verifica o número.

Vigia. De hora em hora o executor da fila lê o número na Meta (watchWhatsAppLine, lineWatch.ts, estado em system_settings.whatsappLineWatch) e empurra a cada admin/manager ativo um aviso quando aparece um problema e outro quando ele some; cada problema novo vira linha em System Errors (WHATSAPP_<problema>). Problemas: COEXISTENCE_OFF (is_on_biz_app falso), NOT_CONNECTED (status ≠ CONNECTED), WEBHOOK_DIVERTED (callback que não é /api/whatsapp/meta-webhook), META_REFUSED (o token não alcança o número em duas leituras seguidas). A barra do app mostra a coexistência desligada (META_COEXISTENCE_OFF) e o painel Settings → WhatsApp → Meta a linha Coexistence.

Prevenção. Abrir o WhatsApp Business no celular principal ao menos uma vez a cada 14 dias (regra da Meta; aparelhos ligados não contam). Nunca verificar o número noutro aparelho nem reinstalar sem backup — troca de celular pela transferência do próprio WhatsApp. Nunca remover o app “Prime Crown” como parceiro da conta do WhatsApp (mudança de portfólio de 2026-09-23 derrubou tudo).

Só os aparelhos caíram (coexistência ainda ativa no vigia/painel): entrar de novo no celular principal e escanear o QR em Aparelhos conectados. Nada no app nem no Chatwoot.

COEXISTENCE_OFF — o app segue enviando e recebendo; o celular não. Religar é o Embedded Signup da Meta (login no Facebook + QR no celular principal, feitos pelo Rafael), direto no app: Settings → WhatsApp → Religar o app WhatsApp Business → Religar com a Meta (MetaReconnectCard, só admin, sem o Chatwoot).

  1. O cartão carrega o SDK do Facebook ao aparecer (a janela tem de abrir no próprio toque, senão o navegador a bloqueia) com META_APP_ID e META_SIGNUP_CONFIG_ID (wrangler.toml, ids públicos) e abre FB.login com featureType: whatsapp_business_app_onboarding (metaEmbeddedSignup.ts). Na janela: a conta do WhatsApp e conectar o app WhatsApp Business existente, QR no celular.
  2. POST /api/whatsapp/meta-signup (meta-signup.ts) só aceita a conclusão de coexistência (FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING; a comum registraria o número só na Cloud API e o tiraria dos celulares — recusada antes de tocar na Meta). Troca o código por token no servidor (META_APP_SECRET), escolhe o número (o que a Meta nomeou, senão o salvo, senão o único), inscreve o app na conta (subscribed_apps, sem subscribed_fields: ficam os campos do app), aponta o webhook do número para /api/whatsapp/meta-webhook com o webhookVerifyToken e grava phoneNumberId/businessAccountId no config salvo se mudaram (json_set, o resto intacto). Nunca chama /register. O token do cadastro é usado e descartado; o app segue com o META_WABA_TOKEN, que a resposta confere.
  3. Se o cartão disser que o token do app não alcança o número: Crown London → System users → Crown Messaging → Assign assets → a conta do WhatsApp com Full control.
  4. Prova: o vigia volta a [] (aviso “WhatsApp back to normal”), uma mensagem digitada no celular aparece no app como do Manager.

Pré-requisito único: app.primecrowncleaning.co.uk nos domínios permitidos do Facebook Login for Business do app “Prime Crown” (869378925986312). Plano B, se o app estiver fora do ar: os passos 2–3 à mão pela Graph (o Embedded Signup pede o app; o caminho pelo Chatwoot deixou de existir com a migração 0282).

META_REFUSED — o passo 3 (e, se a Meta tirou o parceiro, religar pelo cartão). WEBHOOK_DIVERTED — religar pelo cartão também reaponta o webhook (ou POST /<phone-id> webhook_configuration.override_callback_uri pela Graph). NOT_CONNECTED — WhatsApp Manager do portfólio Prime Crown Cleaning → o número: o motivo (restrição, pagamento, nome) está ali.

A comunicação externa principal usa a Meta WhatsApp Cloud API. O webhook assinado recebe mensagens, mídia, recibos, reações, respostas interativas e ecos enviados pelo aplicativo WhatsApp Business em coexistência; todos convergem no mesmo histórico do Messaging. Cada linha registra direction (INBOUND, OUTBOUND ou INTERNAL) e provider (META; EVOLUTION só em linhas históricas), sem inferir semântica pelo campo visual source. Índices únicos parciais em external_id e wa_message_id garantem idempotência inclusive quando duas entregas do webhook são processadas ao mesmo tempo.

O adaptador Evolution (sessão não oficial do WhatsApp Web) foi removido: webhook, conexão por QR, anti-ban, presença, checagem de número, @lid, chamadas, recuperação de mensagens e sonda E2E. Linhas históricas com provider = 'EVOLUTION' ficam no banco e nunca são liberadas nem contadas como da Meta. Consentimento e opt-out valem sempre; a janela de atendimento é obrigatória.

A migração 0125_whatsapp_routing_sessions.sql conserva por 60 minutos as opções do convite enviado ao cliente. A escolha fica em whatsapp_routing_sessions, com auditoria em whatsapp_routing_audit. O canal direto não apresenta seletor “WhatsApp routing” nem permite ao gestor forçar o destino da próxima mensagem: para falar com a equipe, o cliente abre o grupo no app pelo convite. As janelas sociais continuam a expirar automaticamente, sem retorno manual pelo painel removido.

Ao abrir pela primeira vez a conversa de uma tarefa, POST /api/channels devolve a mesma forma enriquecida da listagem, incluindo requestLabel derivado do horário agendado. A inserção local mostra a data imediatamente, sem depender de recarregar a janela; tarefa inexistente ou vinculada a outro cliente é recusada antes de criar o canal.

Na Meta, textos e mídias livres sempre respeitam a janela de 24 horas. A janela pertence ao par número comercial/cliente — inclusive cadastros do mesmo grupo de contato — e não ao canal DIRECT ou JOB. Cada saída guarda a linha comercial usada, inclusive quando entra inicialmente como PENDING pela cota mensal; o runner reutiliza essa proveniência tanto para escolher o provider quanto para as duas verificações da janela, em vez de herdar uma linha alterada no painel. Quando a janela fechar, mensagens ficam HELD e deixam de ser consultadas como candidatas de entrega a cada execução da fila; o runner confere essa regra antes de aplicar novo backoff e transmite a mudança ao chat aberto. Uma varredura limitada, mais antiga primeiro, ainda aplica o prazo global de 24 horas e os prazos menores por categoria: retenção vencida vira FAILED, atualiza a bolha e gera o alerta operacional, sem poder ressuscitar em uma resposta tardia do cliente. A próxima mensagem recebida em qualquer conversa da mesma pessoa pela mesma linha comercial promove somente as linhas ainda HELD para PENDING e transmite a atualização de cada bolha DIRECT/JOB já aberta; uma linha Meta diferente não consome essa janela. Linhas antigas sem a proveniência do número permanecem liberáveis como compatibilidade de migração, em vez de ficarem retidas indefinidamente. Se um Durable Object estiver indisponível, a gravação inbound continua e a próxima leitura reconcilia o estado. A recuperação pós-reconexão consulta também mudanças em whatsapp_queue.updated_at e os timestamps de recibo da própria mensagem, portanto uma bolha antiga que mudou de fila ou ganhou confirmação Meta não depende de uma nova mensagem nem de recarregar a conversa inteira. O chat mostra esse estado como janela fechada, para não apresentá-lo como um envio simplesmente agendado. A lista entrega uma identidade de janela sem poder de autorização, permitindo que DIRECT/JOB e cadastros do mesmo grupo reflitam imediatamente a reabertura, mas preservem prévias, ordenação e não lidos próprios. Consentimento e opt-out nunca são desligados. O gestor também pode escolher um template aprovado, cuja identidade, corpo e variáveis são revalidadas no catálogo Meta pelo servidor.

O POST da Meta limita o corpo a 1 MiB, exige hub.mode=subscribe, desafio não vazio, HMAC do corpo cru e JSON válido. A mensagem é deduplicada e persistida antes de buscar mídia; a chave única de external_id é também a arbitragem atômica entre reentregas concorrentes, portanto só quem gravou a linha pode executar push, roteamento, janela e automação. O download protegido e o armazenamento em R2 são confirmados antes do 200: se a mídia falhar, o endpoint devolve 503 e a reentrega localiza a linha já persistida pelo external_id para completar somente o anexo, sem repetir bot, push ou roteamento.


📱 1. Fluxo Completo de Mensagens WhatsApp

Section titled “📱 1. Fluxo Completo de Mensagens WhatsApp”
sequenceDiagram
    autonumber
    actor Client as Cliente (WhatsApp)
    participant Meta as Meta Cloud API
    participant Webhook as /api/whatsapp/meta-webhook
    participant DO as Durable Object (ChatChannelDO)
    participant App as Painel Web (React UI)

    Client->>Meta: Envia mensagem no WhatsApp
    Meta->>Webhook: POST assinado (payload JSON da mensagem)
    Webhook->>Webhook: Valida HMAC e deduplica
    Webhook->>D1: INSERT messages (INBOUND, META)
    Webhook->>DO: Notifica Durable Object via Broadcast
    DO-->>App: Mensagem aparece instantaneamente na Inbox

🛡️ 2. Recuperação de Envio & Gestão de Falhas (whatsappQueue)

Section titled “🛡️ 2. Recuperação de Envio & Gestão de Falhas (whatsappQueue)”

Para evitar perda de mensagens quando o sinal do celular ou a API do WhatsApp oscila:

Falhas inesperadas do envio Meta e dos webhooks Meta e Chatwoot (Instagram/Facebook) usam o mesmo boundary sanitizado do restante do backend. O painel recebe uma mensagem estável; corpo de erro do gateway, stack, SQL e credenciais permanecem apenas na telemetria sanitizada. O gate global impede qualquer Worker de voltar a responder com error.message, serverError(error.message) ou String(error).

Side effects assíncronos usam logSanitizedError: broadcasts de Durable Objects, push, filas, recibos, automações e sincronizações D1 nunca entregam o objeto do provedor diretamente ao console. A fila também grava lastError já redigido e usa a mesma versão no alerta de falha permanente. Assim, tokens eventualmente presentes em mensagem/stack/cause não reaparecem no painel operacional. Falha de par VAPID retorna somente a classificação estável, enquanto o diagnóstico sanitizado permanece no Worker.

Quando um cliente envia uma mensagem pelo aplicativo, o próprio endpoint de canais notifica os participantes por push. O antigo relay paralelo para um número de teste foi removido: além de duplicar a notificação, ele expunha conteúdo do chat a um destino fixo e usava uma rota Meta diferente do provider canônico.

Logs de sucesso e warning também evitam identidade. E-mail, telefone, Google sub/account, client/user/channel/message/subscription IDs e o objeto de resposta do Resend foram removidos. Texto de status, categoria e modo vindos de configuração ou provedor também não são interpolados; permanecem somente mensagens fixas, contagem de dispositivos, booleanos, delay e status HTTP. Diagnósticos variáveis de cota e fallback passam pelo logger redigido.

  1. Fila de Disparos (whatsappQueue): Toda mensagem de saída enviada pela equipe para o WhatsApp do cliente entra com status PENDING.
  2. Re-tentativas com Backoff Exponencial: Se o disparo falhar, o worker faz até 3 re-tentativas.
  3. Painel de Operações do Inbox (ChatOpsPanel.tsx, aba Failures): Se as 3 tentativas falharem, a mensagem é movida para a lista de exceções do Administrador, permitindo Reenviar Manualmente com 1 clique ou dispensar o erro.
  4. Detecção de envio silencioso: sent_at significa apenas que o gateway aceitou a chamada HTTP. O webhook grava server_ack_at somente quando o próprio WhatsApp devolve o recibo sent. Se isso não ocorrer em 5 minutos, o painel mostra Sem confirmação do WhatsApp. Esse alerta não oferece reenvio automático, pois a mensagem original ainda pode chegar e um retry poderia duplicá-la; o operador pode apenas reconhecer o alerta.
  5. Verdicto agregado no Hub (classifyOutboundHealth): o health check mede a taxa de SERVER_ACK das últimas 24 h e classifica a sessão como OK, DEGRADED (menos de 60 % confirmados em pelo menos 8 envios) ou BROKEN (nenhum confirmado em pelo menos 3 envios). Isso separa um gateway quebrado de destinatários simplesmente offline — deliverabilityRate24h, medida por delivered_at, não consegue distinguir os dois casos. O veredicto fica suspenso enquanto o inbound estiver BROKEN, porque os recibos chegam pelo mesmo webhook e a sua ausência não diria nada sobre o gateway.

🤖 3. Robô Híbrido de Atendimento IA (aiWhatsAppBot.ts)

Section titled “🤖 3. Robô Híbrido de Atendimento IA (aiWhatsAppBot.ts)”
  • Killswitch: whatsAppConfig.enableAiAutomation (Messaging). Ausente/false = bot off.
  • Modo de engajamento (engagementMode), só vale com o bot ligado:
    • MENU_ONLY — responde com a lista de opções configurável (botões); sem IA livre. É o padrão, também quando o campo está ausente (servidor e tela seguem settingsDefaults).
    • KEYWORDS — só entra em ação se a mensagem bater em engageKeywords; aí envia o menu.
    • ALWAYS — IA livre em toda mensagem inbound.
  • Menu: menuGreeting + até 3 menuItems (QUOTE_FLOW | SCHEDULE_LINK | HANDOFF | CUSTOM_TEXT).
  • Escalação por palavra-chave (“atendente”, “manager”) foi removida em 2026-11-08: mandava um segundo push por mensagem e disparava com qualquer frase que citasse um gerente. Quem fica sem resposta é avisado pelo tempo de espera (alertOverdueWaiting, ver Comunicação).
  • Persona: botPersona (LUXURY | FRIENDLY | DIRECT) — só no modo ALWAYS.
  • Clique em botão é persistido no chat com skipBot — não re-roda a IA no rótulo [Clicou: …].
  • Executado na borda via o Workers AI, com o modelo configurado para o bot e seu modelo de reserva (modo ALWAYS).
  • Fornece cotações em tempo real dinâmicas conforme as regras de serviço e descontos do banco D1 (service_types e frequency_discounts).
  • Suporta botões interativos ([📋 Solicitar Orçamento], [💬 Falar com Atendente]).
  • O simulador de bot em Settings foi removido: era um menu fixo que não correspondia ao bot real do servidor. Fica só o Send test, que envia uma mensagem real pela Meta.

  • Teste real (POST /api/whatsapp/test-send): envia uma mensagem real; respeita opt-out (whatsappAuthorized).
  • Opt-in do cliente: o prompt compartilhado aguarda saveClient antes de esconder ou anunciar sucesso. Lock síncrono bloqueia toque/dismiss concorrente, epoch ignora conclusão após teardown e uma falha mantém a ação disponível depois do rollback otimista.
  • Opt-outs (GET /api/whatsapp/opt-outs): lista clientes com whatsapp_opted_out_at.
  • URL do webhook: o health compara a rota da Meta com APP_BASE_URL (https://app.primecrowncleaning.co.uk) quando ele é alcançável, nunca com http://localhost:8788 de um pages:dev (resolveWebhookOrigin).
  • Destinatário do envio: loadChannelWhatsAppTarget lê o dono do canal (owner_type). Um fio de lead guarda o id do lead em client_id; procurar só em clients encontrava ninguém e a resposta da equipe ia para o telefone sentinela unknown (Missing WhatsApp number). Conversas internas (EMPLOYEE) não saem no WhatsApp.
  • Métricas em /api/whatsapp/health: sent* / delivered* e o cálculo de SERVER_ACK contam somente envios de gateway (direction=OUTBOUND e o provider ativo, excluindo ecos do WhatsApp Business app no celular source=WHATSAPP, DMs sociais e notas internas). Isso impede que respostas dadas no celular — que não possuem recibos de status emitidos pela Cloud API — distorçam para baixo as taxas de confirmação e entregabilidade do gateway. O diagnóstico inbound lê o caminho da Meta.
  • Smart replies: SmartReplyChips no composer (ADMIN/MANAGER) quando aiConfig.enableSmartReplies; POST /api/ai/suggest-replies e /api/ai/compose-reply (ver ai-integration).

🔀 4. Roteamento Inteligente & Isolamento de Privacidade (DIRECT vs JOB)

Section titled “🔀 4. Roteamento Inteligente & Isolamento de Privacidade (DIRECT vs JOB)”
  • Canal Direto (DIRECT): Atendimento privado entre Cliente e Gerência. Bloqueado no backend para contas de funcionários (EMPLOYEE), inclusive no upgrade WebSocket, no fan-out de push e nas rotas auxiliares de leitura, presença de digitação, reação e tradução: uma linha legada ou adicionada por engano em channel_participants não concede escuta de broadcasts, conteúdo de notificação, confirmação WhatsApp, metadados de atividade nem escrita lateral. A API recusa criar novas participações em DIRECT de cliente/lead e permite apenas removê-las como limpeza; JOB e a linha interna funcionário–gerência preservam participação normal.
  • Canal da Tarefa (JOB): Chat da limpeza compartilhada com a equipe alocada (Cleaners, Co-pilotos e Gerentes). Cliente pode abrir o próprio canal para acompanhar a tarefa, mas participantIds enviados pelo cliente são ignorados pelo Worker: somente gestão pode incluir participantes. A autorização do funcionário confere a alocação atual da própria tarefa e se ela ainda admite equipe; channel_participants continua como projeção para fan-out/leitura, mas uma linha atrasada nunca conserva acesso após remoção.
  • Mídia de tarefa: anexos inbound pela Meta usam o escopo R2 do canal persistido; uma resposta roteada para JOB fica acessível à equipe alocada, sem cair no armazenamento privado DIRECT.
  • Roteamento Contextual pelo Último Emissor:
    • Se o Gerente falou por último no canal DIRECT, a resposta do cliente no WhatsApp vai para o canal DIRECT (Zero vazamento para a equipe).
    • Se o Funcionário falou por último no canal JOB, a resposta do cliente vai para o canal JOB.
  • Escolha inequívoca com várias tarefas: com um único JOB, permanecem as opções Manager/Team. Com dois ou mais canais ativos, o cliente recebe uma opção numerada por data e hora programadas. A confirmação ROUTE_CHOICE_TEAM é gravada no próprio canal selecionado e loadRoutingState conserva esse channelId por 60 minutos; uma tarefa mais próxima criada depois não pode capturar a conversa.
  • Falha segura: texto ambíguo, número fora da lista, tarefa concluída/bloqueada ou seleção expirada permanecem no DIRECT. Nunca se adivinha um grupo da equipe.
  • Resposta citada: segue o canal exato da mensagem original enquanto a tarefa estiver aberta. A citação nunca atravessa clientes; ambiguidade ou vínculo inválido volta ao DIRECT, e um pedido explícito de gerente permanece privado.
  • Sinalização visual: o contexto expandido do canal JOB informa que é uma conversa de equipe visível somente a gestores e funcionários alocados.
  • Lifecycle do seletor interno: leitura e gravação recebem cancelamento por cliente/canal. Um lock bloqueia duas mudanças no mesmo frame, respostas 4xx não viram sucesso e troca de conversa invalida dados, loading e toast tardios antes de alcançar a interface.
  • Lifecycle do composer fora da janela: template e variáveis pertencem ao canal aberto. Trocar de conversa limpa o rascunho, invalida catálogo tardio, aborta envio em curso e o lock síncrono impede duas cobranças/mensagens por duplo toque.
  • Lifecycle do template fora da janela: o composer pertence ao canal aberto. Trocar de conversa limpa template e variáveis, invalida o catálogo tardio, aborta o envio em voo e um lock síncrono impede mensagem ou cobrança duplicada por duplo toque.
  • Bypass de Emergência (isPrivateManagerIntent): Se o cliente pedir atendimento com o gerente (“gerente”, “privado”), o sistema desvia o WhatsApp para DIRECT instantaneamente.

🧑‍⚖️ 4b. O escritório modera a equipe (messageModeration.ts, release.ts)

Section titled “🧑‍⚖️ 4b. O escritório modera a equipe (messageModeration.ts, release.ts)”

Por enquanto, nada do que a cleaner escreve chega ao cliente sem passar pelo escritório. Uma mensagem da equipe numa conversa que o cliente lê (o grupo da tarefa, JOB, ou a conversa direta de um cliente) é gravada como nota interna HELD (crewMessageHeld, coluna messages.moderation, migração 0180): no POST /channels/:id/messages, nas agendadas (dispatchScheduled) e no aviso de atraso (transitNotice). Ela não sai pelo WhatsApp, o cliente não a vê (o GET e o relay chat-do já filtram notas) e o push vai só para a equipe. As conversas da cleaner com o escritório (DIRECT de funcionário) não são retidas.

Liberação automática no app (2026-10-07). Uma mensagem de chat da equipe retida vai sozinha para o app do cliente quando ele tem aparelho com push (token nativo ou inscrição web) e há inglês em que confiar — a tradução guardada (crewMessageTranslations, com a trava de fidelidade) ou o próprio texto quando já é inglês; um ficheiro sem texto também vai (autoReleaseHeld, functions/api/channels/releaseHeld.ts). É o mesmo Release in the app (releaseHeldNote, a única liberação: cópia em inglês com a autoria da cleaner, nada pelo WhatsApp), sem o escritório. Notas retidas à espera de revisão não disparam push para os gestores (skipOffice) e não entram na contagem de mensagens não lidas da caixa de entrada nem do badge; o gestor tem a opção de liberação (Release to client) ao entrar na conversa do job. Na dúvida sobre o idioma a mensagem espera: português curto e sem acentos já passou por inglês. Agendadas e aviso de atraso continuam à espera do escritório.

Embaixo da nota, a cleaner lê Waiting for the office…; o manager/admin tem Release to client (HeldMessageRelease), que abre a janela de mensagem ao cliente (openClientMessage) com o texto editável:

  • Primeiro, no app (todas menos o aviso de atraso): Release in the app (mode: LINK) grava a cópia da cleaner no chat, manda o push ao cliente e devolve um link /chat/<código> para essa mensagem (chat:<canal>:<mensagem>). Nada sai pelo WhatsApp, então não conta na quota da Meta. Se o aparelho do cliente aceitou o push (notifiedInApp, de notifyParticipants), a janela diz que ele já foi avisado; senão pede para encaminhar pelo WhatsApp Business do celular a mensagem com o link para o app no fim (forwardWithAppLink, o mesmo texto da reserva de uma mensagem não recebida; o eco marca a cópia como enviada pelo WhatsApp), onde não há quota nem janela de 24 h. O link abre o app nessa conversa e rola até a mensagem (messageToView, como um toque numa citação). A conversa gestor ↔ cliente pelo WhatsApp não muda.
  • Janela de 24 h aberta: Send libera (POST /api/channels/:id/release, mode: SEND): uma cópia USER_MESSAGE com a autoria da cleaner entra no chat da tarefa e sai no WhatsApp assinada _Team_ — Nome: (staffAttributionLine, agora em src/shared/staffAttribution.ts). Leva também o caminho de volta: um link /chat/ para a cópia, como botão Reply in the app (cta_url); quando o envio espera na fila, a URL vai no fim do texto (link em deliverViaWhatsApp).
  • Janela fechada: WhatsApp Business (copiar/abrir já assinado) e depois I sent it on WhatsApp Business (SENT_OUTSIDE: grava a cópia sem enviar); ou o template aprovado, quando a mensagem tem um — hoje só o aviso de atraso (visit_on_the_way; depois TEMPLATE só fecha a nota, o template já gravou a sua mensagem). Não existe template de texto livre.

Português → inglês. A cleaner escreve em português; ao gravar a nota retida, o servidor guarda a tradução para inglês (crewMessageTranslations, autoPolish.ts, com a mesma trava de fidelidade da tradução do cliente; só um texto claramente em inglês não é traduzido — a detecção não reconhece português curto e sem acento, e tratar “não sei” como inglês mandou português a um cliente). Se a nota ficou sem inglês (o modelo falhou ou a trava descartou), Release to client pede a tradução na hora (POST /channels/:id/held-english, escritório) antes de abrir a janela; sem ela, avisa e abre com o original para o manager escrever o inglês. O manager vê o original no balão e o inglês logo abaixo (In English — what the client will read), e Release to client abre com o inglês, editável. Um aviso automático (Bot/sistema, automation — o link de acesso incluído) já é inglês: grava o próprio texto como inglês e nunca passa pelo modelo, nem no held-english nem na tela (que não mostra o quadro de inglês para ele) — antes, o link de acesso ia sem inglês e o modelo “traduzia” inglês para inglês, reescrevendo e cortando a saudação. O link de acesso não tem liberar no app (quem pede está fora do app): só WhatsApp — API na janela de 24 h, senão WhatsApp Business; o servidor recusa LINK para ele (422).

O chat reconhece a liberação sozinho. A nota passa de On hold a Sent to the client ao vivo (a liberação retransmite a nota pelo chat-do; o chat mescla por id). Quando o manager envia pelo WhatsApp Business do celular, o eco da coexistência chega assinado _Team_ — Nome:; releaseHeldFromEcho (metaEcho.ts) fecha a nota retida mais recente daquela cleaner para aquele cliente e grava o eco no chat da tarefa como mensagem dela — sem precisar do I sent it on WhatsApp Business, que fica como reserva (por exemplo, se a assinatura for apagada).

Sem a trava de 24 h para a equipe. Como nada da cleaner sai direto para o WhatsApp, a janela de 24 h da Meta não trava o compositor dela (heldForOffice no ServiceChatInput, ligado por crewMessageHeld): ela escreve sempre, o botão diz Send to the office e o contador de 24 h some do cabeçalho e da lista para ela. Continua valendo a janela da conversa da tarefa (taskOpen, também exigida pelo servidor). A janela de 24 h passa a importar só na liberação, para o manager.

O clipe da equipe. Para a cleaner, o clipe tem só File e Record voice note na conversa com a Gerência, e só File no canal da equipe (mayRecordVoice, que vale para todos: ninguém grava voz num JOB); nota interna e agendamento ficam com o escritório. O servidor recusa áudio num JOB (400, no envio e no agendamento). A Gerência aparece com o escudo (ShieldCheck) também no seletor de conversa da tarefa.

A liberação vale uma vez por nota (o UPDATE … WHERE moderation = 'HELD' é o trinco; a segunda dá 409) e a nota fica no histórico como Sent to the client.

➡️ 5. Encaminhamento & Transferência de Mensagens (forward.ts & move-to-direct.ts)

Section titled “➡️ 5. Encaminhamento & Transferência de Mensagens (forward.ts & move-to-direct.ts)”
  • Encaminhar para o Grupo ([➡️ Encaminhar p/ Grupo]): Copia mensagem do atendimento direto para o chat da tarefa da equipe sem re-enviar para o WhatsApp do cliente.
  • Mover para o Privado ([🔒 Mover p/ Privado]): Transfere mensagens do chat do grupo para o canal exclusivo da Gerência e tranca as respostas futuras do WhatsApp no gerente.

🗑️ 6. Exclusão & Revogação Nativa do WhatsApp (Janela de 60 Minutos)

Section titled “🗑️ 6. Exclusão & Revogação Nativa do WhatsApp (Janela de 60 Minutos)”
  • Regra Oficial do WhatsApp: Mensagens podem ser apagadas para todos (Delete for Everyone) dentro de 60 minutos após o envio, independentemente do status de leitura.
  • Sem revogação remota: a Meta Cloud API não oferece Delete for Everyone. Uma mensagem que saiu pelo WhatsApp não pode ser apagada por quem não é admin (o backend recusa, em vez de fingir que sumiu do celular do cliente); o admin apaga só o registro no app, e o aviso diz que o cliente ainda a tem.

⚡ 7. Resposta do cliente a confirmação ou remarcação

Section titled “⚡ 7. Resposta do cliente a confirmação ou remarcação”

Não há confirmação automática. Um “ok”, “sim”, “Confirm” ou “Remarcar” do cliente — digitado ou tocado num botão de template — chega como mensagem comum à conversa; a equipa confirma ou remarca pela tarefa (Edit task / client-change). O antigo bookingConfirmation.ts mudava o status e respondia sozinho a qualquer “ok” e foi removido.


🎯 8. Exibição Contextual de Templates pelo Momento da Tarefa (templateMoments.ts)

Section titled “🎯 8. Exibição Contextual de Templates pelo Momento da Tarefa (templateMoments.ts)”

Para evitar envios equivocados ou inconsistências (como ofertar alteração de horário para uma tarefa que já está confirmada), a interface filtra e prioriza os templates estritamente de acordo com a fase operacional da tarefa:

  1. Aguardando Confirmação Inicial (PENDING_BOOKING):

    • Tarefa em PENDING ou PENDING_REVIEW inicial.
    • Template recomendado: booking_confirmation (“…is confirmed for {{3}} at {{4}}…”).
    • Quick Action na Janela Aberta & Fechada: 📋 Confirm Booking (abre o template diretamente).
    • Bloqueados: schedule_change, booking_reminder e templates de campo.
  2. Mudança de Horário / Reagendamento (SCHEDULE_CHANGE):

    • Tarefa que teve o dia/horário alterado (originalDateTime != null ou solicitação do cliente).
    • Template recomendado: schedule_change (“…has been rescheduled to {{3}} at {{4}}… Please confirm your availability”).
    • Quick Action na Janela Aberta & Fechada: 📅 Reschedule Notice (abre o template diretamente).
    • Atalho no Modal de Edição Rápida (QuickEditTaskModal): Ao salvar a alteração de horário com a opção “Notify client on WhatsApp” ativada, o sistema abre a folha do template schedule_change pré-preenchido em 1 clique.
    • Bloqueados: booking_confirmation, booking_reminder e templates de campo.
  3. Visita Já Confirmada (CONFIRMED_UPCOMING):

    • Tarefa em SCHEDULED sem remarcação pendente.
    • Templates recomendados: booking_reminder (lembrete de véspera e acesso) e templates operacionais de campo.
    • Quick Action na Janela Aberta & Fechada: 🔔 Reminder.
    • Bloqueados: schedule_change (nunca ofertado para tarefas já confirmadas) e booking_confirmation.
  4. Visita em Andamento (IN_PROGRESS):

    • Tarefa em execução no dia.
    • Templates recomendados: cleaner_arrival_access, cleaner_key_return, cleaner_transit_delay.
    • Bloqueados: templates gerenciais de agendamento.
  5. Acesso Flexível e Ações Rápidas Integradas:

    • Atalho no Agendamento (BookingModal): Ao criar uma nova visita com o toggle “Notify client on WhatsApp” ativado, a folha do template booking_confirmation abre automaticamente pré-preenchida para envio com 1 toque.
    • Botão WhatsApp nos Detalhes da Tarefa (ServiceLogistics): Botão direto verde esmeralda na aba de logística permitindo abrir a folha contextual de templates (com cliente, serviço, data/hora e cleaner preenchidos) sem sair da tela.
    • Aviso de trânsito: POST /api/channels/transitNotice confere a associação entre tarefa e cliente antes de criar o canal ou enviar qualquer mensagem. É permitido a ADMIN/MANAGER e, para EMPLOYEE, somente quando a profissional está alocada na tarefa; cotações não aceitam esse aviso operacional.
  6. Briefing operacional seguro: GET /api/channels/summary/:id resume somente canais aos quais a pessoa autenticada já tem acesso. Se a IA ou o provider falhar, o cliente recebe uma resposta estável para retry; o diagnóstico sanitizado fica restrito ao log operacional.

    • Alerta de Remarcação na Grade (ScheduleEventCard): Visitas movidas para PENDING_REVIEW via WhatsApp recebem card âmbar com badge Review e ring destacado para rápida intervenção do despacho.
    • Catálogo Completo: Gestores contam com o botão “Show all templates” no seletor para acessar outros modelos da conta Meta quando necessário.