# טיוטה: תקשורת החברה

> טיוטת PR #69 — לא מוזגה. מקור: docs/admin-communications.md · 34bdd4e · 2026-11-21.
> בגרסה הציבורית הושמטו מזהים תפעוליים ופרטי חשבון אישיים. קובץ המקור נשמר במאגר.

Date: 21 November 2026. Scope: internal company Admin only. Existing customer/mobile screens and assets are unchanged.

## Delivered in this change

The Admin has an email workspace and a WhatsApp workspace with two independent channels: customer service and sales. Each has search, unread/open/resolved filters, conversation selection, plain-text history and an in-memory draft composer. Mobile users can return from a thread to the list. Opening a conversation does not send a read receipt.

`CommunicationsWorkspace({ section: "email" | "messages", preview?: boolean, initialChannel?: "service" | "sales" })` is a plain React client component. Live defaults are disconnected, empty states. The component performs no provider requests. A public contact address (`info@linknodesenergy.com`) is displayed as a proposed mailbox destination; this does not prove which provider hosts it or that access has been granted. No WhatsApp business numbers are invented.

Only an explicit `preview` prop loads the synthetic records from `communications-preview.ts`. The sample contains non-deliverable `example.invalid` contacts and is visibly labeled. It is never used as a fallback for an unsuccessful real data request. Sample status changes affect component memory only. Drafts are scoped by channel and thread, are not sent to a provider, and disappear when the component is unmounted or the page reloads. The UI communicates this limit. Sending is disabled until a separately implemented and verified connection is available.

There are no new cloud resources, credentials, subscriptions, outbound messages, database migrations or production integration changes in this slice.

## Connection information still needed

| Channel          | Required verified information                                                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Company email    | Actual provider (for example Google Workspace or Microsoft 365), mailbox identity, authorized owner/admin consent and read/send scope decisions |
| WhatsApp service | Company Meta/WABA ownership, verified business phone number and phone-number ID, application configuration and scoped credential                |
| WhatsApp sales   | Its own verified business phone number and phone-number ID, routing and consent policy, approved templates where applicable                     |

Create a server-owned mapping from each provider mailbox/phone-number ID to exactly one company channel. A phone number, sender label or channel supplied by browser input must never select another channel's credential. Bind the company integration to a verified account and record connection status, capabilities, last successful sync and error state. Do not present a configured secret as proof of a healthy connection.

## Email adapter acceptance

Implement the chosen mailbox provider after verifying the actual company account. OAuth refresh tokens and provider keys remain in server secret storage. Start with mailbox-scoped read access; outbound sending needs a distinct server permission and deliberate authorization. Customer messages are untrusted content, never instructions for an AI agent or a privileged operation. Render plain text by default; HTML and attachment handling need a separate sanitization/download design.

For Gmail, notifications identify changes, and `historyId` is the synchronization cursor. A watch must be renewed before expiry. Initial synchronization is bounded and paginated; an expired/unavailable history cursor triggers controlled resynchronization. Official references: [Gmail push notifications](https://developers.google.com\[local-path-redacted]), [Gmail synchronization](https://developers.google.com\[local-path-redacted]).

For Microsoft 365, confirm whether this is a user mailbox or a shared mailbox before choosing permissions. Shared/delegated-folder change subscriptions have different permission requirements from the signed-in user's mailbox. Use mailbox-scoped application access if application permission is necessary, and implement subscription renewal and recovery. Official reference: [Outlook change notifications](https://learn.microsoft.com/en-us/graph/outlook-change-notifications-overview?tabs=http).

## WhatsApp adapter acceptance

The service and sales channels need independent account mappings, conversation routing, counters and staff permissions. A provider-scoped event key includes the account, business phone-number ID and message/event ID. Verify the raw webhook signature before parsing and persist deduplication evidence before acknowledging. Ignore unknown numbers/accounts; handle multiple messages and status updates in a notification. Official reference: [Meta webhook validation](https://developers.facebook.com/docs/graph-api/webhooks/getting-started/).

Free-form service replies require an open customer-service window. Meta currently describes a 24-hour window reset by a customer's message or eligible call; outside it, a pre-approved template is needed. Retain verified consent evidence and the selected template version. An accepted send API response is not proof of delivery: delivery/read/failed states come from verified provider events. Do not resend an uncertain submission blindly. Official reference: [WhatsApp service messages](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages).

Reading a conversation is an internal UI action; sending a read receipt is an outbound provider action and needs a separate explicit policy. Reordered delivery events cannot downgrade a confirmed state. All outbound commands require an authorized staff actor, a durable operation record, channel/account binding, approved recipient scope and an auditable outcome.

## Next implementation gate

Confirm the company mailbox provider and the two business numbers, then implement one read adapter at a time against the existing infrastructure. Prove webhook authenticity, cross-channel isolation, replay handling, cursor recovery and staff access before exposing real messages. Enable sending only after provider setup, permissions and end-to-end delivery tests. An existing paid database can be used once its deployment and schema changes are approved; no additional Supabase project is required by the UI foundation.
