Atendimento omnichannel (SAC)

O módulo SAC abre chamado a partir de e-mail e de WhatsApp, responde pelo mesmo canal de origem e prepara um rascunho de resposta com IA para o atendente revisar.

Status: ✅ Implementado — entrada por IMAP, WhatsApp pela Meta Cloud API e pela Evolution API, e sugestão de resposta por IA.

Três coisas independentes, que podem ser ligadas separadamente:

1. Settings → Integrations: crie um perfil do tipo E-mail com o provider IMAP (recebimento), apontando para a caixa que você já usa. Clique em Test.
2. Atendimento → Canais: crie um canal para cada origem (por exemplo email-suporte, do tipo E-mail).
3. Atendimento → Caixas de e-mail: cadastre o endereço monitorado, escolha o canal e o perfil IMAP. Use Testar conexão e depois Sincronizar agora.
4. Atendimento → Log de entrada: mande um e-mail de teste e confirme que ele aparece — e, se foi descartado, por quê.

Quando uma mensagem chega, o SAC procura o chamado nesta ordem e para no primeiro acerto:

1. Endereço de resposta — [email protected], gerado por nós no Reply-To.
2. Cabeçalhos de thread — In-Reply-To/References casando com o id que o provedor devolveu quando enviamos.
3. Tag no assunto — [#202608-000042], que vai em todo e-mail enviado ao solicitante.
4. Chamado aberto do mesmo remetente no mesmo canal.
5. Nada casou → abre chamado novo.

No WhatsApp não existem os três primeiros: o número identifica a conversa, então vale direto a regra 4.

Trava de segurança: o protocolo aparece no assunto de todo e-mail e vaza em qualquer encaminhamento. Por isso os passos 1–3 só anexam a mensagem se o remetente for o solicitante do chamado ou já for autor de alguma mensagem dele. Caso contrário, abre um chamado novo em vez de deixar qualquer um escrever no chamado alheio.

Um chamado já resolvido ou fechado não é reaberto: a resposta tardia vira um chamado novo.

É o que faz a resposta do cliente voltar identificada. Sem ele, a resposta cai no remetente do perfil de envio, que não diz de qual chamado se trata.

1. Escolha um subdomínio dedicado, por exemplo tickets.suaempresa.com.
2. Aponte um MX próprio para ele, no provedor que você preferir, e crie uma caixa catch-all — todo [email protected] precisa cair nela.
3. Settings → Configurations → Atendimento: preencha Domínio de Resposta com tickets.suaempresa.com.
4. Cadastre a caixa catch-all em Atendimento → Caixas de e-mail, como qualquer outra.

A partir daí os e-mails ao solicitante saem com Reply-To: <protocolo>@tickets.suaempresa.com. Um canal pode ter o próprio domínio de resposta, se você precisar separar marcas.

O subdomínio é dedicado de propósito: apontar o MX do domínio principal para cá tiraria o e-mail corporativo do ar.

A leitura é por IMAP porque é o único caminho que não exige mudar o MX: a caixa continua funcionando normalmente no Gmail, no Outlook e no celular de quem já a usa.

Console: admin.google.com e myaccount.google.com

1. No Admin Console, garanta que o IMAP está liberado para a organização (Apps → Google Workspace → Gmail → Acesso IMAP).
2. Na conta que será lida, ative a verificação em duas etapas e gere uma senha de app — a senha normal da conta não funciona para IMAP.
3. Servidor: imap.gmail.com, porta 993, TLS direto.

O provider IMAP não funciona com o Microsoft 365. A Microsoft desligou a autenticação básica de IMAP em 01/10/2022, em definitivo — a documentação oficial é explícita: "Now no one (you or Microsoft support) can re-enable Basic authentication in your tenant." Senha de app também não resolve: a mesma página diz que a depreciação impede o uso de senhas de app.

Uma caixa compartilhada ainda por cima tem o sign-in bloqueado por recomendação da própria Microsoft, então não há senha a usar.

Caixas do Exchange Online são lidas pelo Microsoft Graph com autenticação app-only, usando o mesmo registro de aplicativo do Entra que o HedHog já usa para login e para as reuniões do Teams — os três leem o mesmo perfil de integração.

Em Atendimento → Caixas de e-mail, escolha o perfil do Entra em vez de um perfil IMAP: o seletor mostra apenas os providers que sabem ler caixa nesta instalação. O resto da configuração (canal, categoria, intervalo) é igual.

A opção Marcar como lida não se aplica aqui: a leitura usa um cursor próprio (delta token), então marcar não muda nada — e exigiria permissão de escrita, ampliando o acesso sem benefício.

A primeira sincronização não abre chamados retroativos: ela só registra o ponto de partida, mesmo numa caixa com anos de histórico.

Como escopar sem dar acesso a todas as caixas

Mail.Read de aplicação, por padrão, lê todas as caixas do tenant. Restringir é obrigatório, e o mecanismo atual é o RBAC for Applications (o New-ApplicationAccessPolicy está marcado como legado e, além disso, recusa caixa compartilhada como alvo direto):

# As caixas precisam estar num grupo de segurança habilitado para e-mail.
New-ServicePrincipal -AppId <appId> -ObjectId <objectId da Enterprise Application>
New-ManagementScope -Name "SAC" -RecipientRestrictionFilter "MemberOfGroup -eq '<DN do grupo>'"
New-ManagementRoleAssignment -Role "Application Mail.Read" -App <appId> -CustomResourceScope "SAC"
Test-ServicePrincipalAuthorization -Identity <app> -Resource [email protected]

O -ObjectId é o da Enterprise Application, não o do App Registration — usar o errado falha na autenticação sem dizer por quê.

Armadilha que anula a proteção inteira: os dois sistemas de permissão são união, não interseção. Se Mail.Read for consentido no Entra e houver escopo por RBAC, o resultado é acesso irrestrito. A documentação da Microsoft é explícita ao mandar remover o Mail.Read do Entra quando se usa RBAC.

Não use o botão "Grant admin consent" do portal. A documentação avisa que conceder consentimento para toda a organização "may revoke permissions that have already been granted tenant-wide" — e num app que também faz o login dos usuários, isso derruba o acesso deles. Conceda o app role novo com New-MgServicePrincipalAppRoleAssignment, e exporte os grants atuais antes (Get-MgOauth2PermissionGrant, Get-MgServicePrincipalAppRoleAssignment).

Use o servidor IMAP informado pelo provedor, normalmente mail.seudominio.com na porta 993.

A primeira leitura de uma caixa pega apenas as mensagens não lidas: adotar uma caixa com histórico não pode significar abrir mil chamados retroativos.

Cada número vira uma linha em Atendimento → Números de WhatsApp, vinculada a um perfil de integração e a um canal do tipo WhatsApp. Um perfil pode ter vários números, e cada número pode cair num canal diferente.

O canal precisa ser do tipo WhatsApp: é o tipo do canal que faz a resposta do atendente sair pelo WhatsApp. Apontar para um canal de e-mail faria a resposta tentar sair por e-mail, para um solicitante que não tem e-mail.

Console: developers.facebook.com

1. Crie um perfil de integração do tipo WhatsApp com o provider WhatsApp Official API (veja a receita de WhatsApp para os campos).
2. Em Atendimento → Números de WhatsApp, clique em Provisionar webhook e copie a URL.
3. No painel da Meta, em WhatsApp → Configuração, cole a URL em Callback URL e o verify token do perfil.
4. Assine o campo messages.
5. Preencha o ID do número com o phone_number_id que a Meta informa.

Console: o painel da sua instância

1. Crie um perfil do tipo WhatsApp com o provider Evolution API (host, token, instance_name).
2. Em Atendimento → Números de WhatsApp, clique em Provisionar webhook e copie a URL.
3. Nas configurações de Webhook da instância, cole a URL e habilite o evento messages.upsert.
4. Preencha Instância com o nome exato da instância.

A Evolution não assina o corpo da requisição. A autenticação é a apikey do perfil, comparada em tempo constante, e o perfil precisa ter o token preenchido — sem token, nada é aceito. Confirme que sua instância envia a apikey no corpo ou no cabeçalho.

Mensagens enviadas pela própria empresa (fromMe) e mensagens de grupo são descartadas: a primeira abriria um chamado a cada resposta do atendente, e a segunda não tem um solicitante único do outro lado.

A cada chamado novo e a cada resposta do cliente, o SAC prepara um rascunho para o atendente. Nada é enviado automaticamente.

1. Settings → Integrations: crie um perfil do tipo IA (OpenAI, Gemini, Claude ou DeepSeek).
2. Settings → Configurations → Atendimento: ligue Habilitar sugestão de resposta por IA e escolha o Perfil de IA.
3. Abra um chamado: o rascunho aparece acima do editor de resposta.

Na tela, o atendente tem três saídas:

• Confirmar e enviar — publica o rascunho como resposta, pelo mesmo caminho de uma resposta digitada à mão.
• Refinar — descreve o ajuste em linguagem natural ("mais curto", "cite o prazo de 5 dias úteis") e recebe uma nova versão.
• Editar — joga o texto no editor para ajustar à mão.

Somente as mensagens públicas do chamado. Notas internas nunca entram — é onde o time escreve o que não vai para o cliente. Entram também alguns chamados já resolvidos da mesma categoria, como referência de tom, priorizando os bem avaliados.

• O interruptor Habilitar sugestão de resposta por IA vem desligado: gastar token por chamado é uma decisão do operador.
• Um rascunho automático por mensagem recebida, garantido por índice no banco — uma conversa de WhatsApp com dez mensagens seguidas não vira dez chamadas ao modelo.
• O custo estimado de cada chamada aparece no log de execuções de IA do core.

Os prompts ficam em Settings → Instruções de IA e podem ser ajustados sem deploy. O prompt de sistema é sensível à segurança: ele contém a defesa que faz o conteúdo do cliente ser tratado como dado, nunca como instrução. Se um override remover essa defesa, o sistema descarta o texto editado e volta ao original — a proteção não sai pela tela.

Atendimento → Log de entrada mostra tudo que chegou, incluindo o que foi descartado e por quê. É a tela que responde "o cliente diz que mandou e-mail e ninguém respondeu".

Mensagens repetidas pelo provedor são reconhecidas e não geram chamado duplicado.