Omnichannel support (SAC)

The SAC module opens tickets from e-mail and WhatsApp, replies through the channel the message came from, and prepares an AI reply draft for the agent to review.

Status: ✅ Implemented — inbound over IMAP, WhatsApp through the Meta Cloud API and the Evolution API, and AI reply suggestions.

Four independent pieces, each of which can be enabled on its own:

1. Settings → Integrations: create an Email profile with the IMAP (inbound) provider pointing at the mailbox you already use. Hit Test.
2. Support → Channels: create a channel per source (for example email-support, of kind Email).
3. Support → Mailboxes: add the monitored address, pick the channel and the IMAP profile. Use Test connection, then Sync now.
4. Support → Inbound log: send a test e-mail and confirm it shows up — and, if it was discarded, why.

When a message arrives, SAC looks for the ticket in this order and stops at the first hit:

1. Reply address — [email protected], which we generated in the Reply-To.
2. Thread headers — In-Reply-To/References matching the id the provider returned when we sent.
3. Subject tag — [#202608-000042], present in every e-mail sent to the requester.
4. An open ticket from the same sender on the same channel.
5. Nothing matched → a new ticket is opened.

On WhatsApp the first three do not exist: the phone number identifies the conversation, so rule 4 applies directly.

Safety check: the protocol shows up in the subject of every e-mail and leaks on any forward. That is why steps 1–3 only append the message when the sender is the ticket requester, or already authored one of its messages. Otherwise a new ticket is opened, instead of letting anyone write into someone else's ticket.

A ticket that is already resolved or closed is not reopened: a late reply becomes a new ticket.

This is what makes the customer reply come back identified. Without it, the reply lands on the sending profile's from address, which says nothing about which ticket it belongs to.

1. Pick a dedicated subdomain, for example tickets.yourcompany.com.
2. Point a dedicated MX at it, on whichever provider you like, and create a catch-all mailbox — every [email protected] must land there.
3. Settings → Configurations → Support: set Reply Domain to tickets.yourcompany.com.
4. Register the catch-all mailbox under Support → Mailboxes, like any other.

From then on e-mails to the requester go out with Reply-To: <protocol>@tickets.yourcompany.com. A channel can carry its own reply domain if you need to separate brands.

The subdomain is dedicated on purpose: pointing the main domain MX here would take your corporate e-mail down.

Reading is over IMAP because it is the only path that does not require changing the MX: the mailbox keeps working normally in Gmail, in Outlook and on the phone of whoever already uses it.

Console: admin.google.com and myaccount.google.com

1. In the Admin Console, make sure IMAP is allowed for the organization (Apps → Google Workspace → Gmail → IMAP access).
2. On the account being read, turn on two-step verification and create an app password — the regular account password does not work for IMAP.
3. Server: imap.gmail.com, port 993, direct TLS.

The IMAP provider does not work with Microsoft 365. Microsoft permanently disabled Basic authentication for IMAP on 1 October 2022 — the official documentation is explicit: "Now no one (you or Microsoft support) can re-enable Basic authentication in your tenant." App passwords do not help either: the same page states the deprecation also prevents their use.

A shared mailbox additionally has sign-in blocked on Microsoft's own recommendation, so there is no password to use.

Exchange Online mailboxes are read through Microsoft Graph with app-only authentication, reusing the same Entra app registration HedHog already uses for login and Teams meetings — all three read the same integration profile.

Under Support → Mailboxes, pick the Entra profile instead of an IMAP one: the selector only lists providers that can read a mailbox in this installation. Everything else (channel, category, interval) works the same.

Mark as read does not apply here: reading uses its own cursor (a delta token), so marking changes nothing — and it would require write permission, widening access for no benefit.

The first sync opens no retroactive tickets: it only records the starting point, even on a mailbox with years of history.

Scoping it so the app cannot read every mailbox

Application Mail.Read reads every mailbox in the tenant by default. Restricting it is mandatory, and the current mechanism is RBAC for Applications (New-ApplicationAccessPolicy is marked legacy and, on top of that, rejects shared mailboxes as a direct target):

# The mailboxes must live in a mail-enabled security group.
New-ServicePrincipal -AppId <appId> -ObjectId <objectId of the Enterprise Application>
New-ManagementScope -Name "SAC" -RecipientRestrictionFilter "MemberOfGroup -eq '<group DN>'"
New-ManagementRoleAssignment -Role "Application Mail.Read" -App <appId> -CustomResourceScope "SAC"
Test-ServicePrincipalAuthorization -Identity <app> -Resource [email protected]

-ObjectId is the Enterprise Application one, not the App Registration's — using the wrong one fails authentication without saying why.

The trap that voids the whole protection: the two permission systems are a union, not an intersection. If Mail.Read is consented in Entra and scoped through RBAC, the result is unrestricted access. Microsoft's documentation explicitly says to remove the Entra Mail.Read assignment when using RBAC.

Do not use the portal's "Grant admin consent" button. The documentation warns that granting tenant-wide consent "may revoke permissions that have already been granted tenant-wide" — on an app that also signs your users in, that takes their access down. Grant the new app role with New-MgServicePrincipalAppRoleAssignment, and export the current grants first (Get-MgOauth2PermissionGrant, Get-MgServicePrincipalAppRoleAssignment).

Use the IMAP server your provider reports, usually mail.yourdomain.com on port 993.

The first read of a mailbox only picks up unread messages: adopting a mailbox with history must not mean opening a thousand retroactive tickets.

Each number becomes a row under Support → WhatsApp numbers, bound to an integration profile and to a WhatsApp channel. A profile can hold several numbers, and each number can land on a different channel.

The channel must be of kind WhatsApp: the channel kind is what makes the agent reply go out over WhatsApp. Pointing at an e-mail channel would make the reply try to leave by e-mail, to a requester who has no e-mail.

Console: developers.facebook.com

1. Create a WhatsApp integration profile with the WhatsApp Official API provider (see the WhatsApp recipe for the fields).
2. Under Support → WhatsApp numbers, click Provision webhook and copy the URL.
3. In the Meta console, under WhatsApp → Configuration, paste the URL into Callback URL and the profile verify token.
4. Subscribe to the messages field.
5. Fill Phone number ID with the phone_number_id Meta reports.

Console: your instance dashboard

1. Create a WhatsApp profile with the Evolution API provider (host, token, instance_name).
2. Under Support → WhatsApp numbers, click Provision webhook and copy the URL.
3. In the instance Webhook settings, paste the URL and enable the messages.upsert event.
4. Fill Instance with the exact instance name.

Evolution does not sign the request body. Authentication is the profile apikey, compared in constant time, and the profile must have the token filled in — with no token, nothing is accepted. Make sure your instance sends the apikey in the body or the header.

Messages sent by the company itself (fromMe) and group messages are discarded: the first would open a ticket on every agent reply, and the second has no single requester on the other end.

On every new ticket and every customer reply, SAC prepares a draft for the agent. Nothing is ever sent automatically.

1. Settings → Integrations: create an AI profile (OpenAI, Gemini, Claude or DeepSeek).
2. Settings → Configurations → Support: turn on Enable AI reply suggestions and pick the AI Profile.
3. Open a ticket: the draft shows up above the reply editor.

On screen the agent has three ways out:

• Confirm and send — publishes the draft as the reply, through the same path as a hand-typed one.
• Refine — describes the tweak in plain language ("shorter", "mention the 5 business day window") and gets a new version.
• Edit — drops the text into the editor for manual changes.

Only the public messages of the ticket. Internal notes never do — that is where the team writes what is not meant for the customer. A few resolved tickets from the same category go in as a tone reference, favouring the well-rated ones.

• The Enable AI reply suggestions switch ships off: spending tokens per ticket is the operator's decision.
• One automatic draft per received message, enforced by a database index — a WhatsApp conversation with ten messages in a row does not become ten model calls.
• The estimated cost of each call shows up in the core AI execution log.

The prompts live under Settings → AI Instructions and can be adjusted without a deploy. The system prompt is security sensitive: it carries the defence that makes customer content be treated as data, never as instructions. If an override removes that defence, the system discards the edited text and falls back to the original — the protection cannot be removed through the UI.

Support → Inbound log shows everything that arrived, including what was discarded and why. It is the screen that answers "the customer says they e-mailed and nobody replied".

Messages replayed by the provider are recognized and do not create duplicate tickets.