Not yet released. This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.
Goal
Understand channel synchronization, conversation limits, SLA tracking and delivery recovery.Prerequisites
- The API release containing migrations 000544-000548 after the existing Support/Mail schema. Support jobs run inside the API; the existing Mail worker also needs the Support attachment reader.
- An enabled Support workspace with an inbox, available conversation allowance and message admission enabled.
- A qualified connection and consent to the mailbox, bot or business account you intend to use.
Workflow
1
Create the connection for the intended workspace, environment, brand and inbox. Authorize the provider account; credentials alone do not activate a connection.
2
For OAuth providers, discover accessible accounts and select the verified asset. Managed email uses its configured verified address; Telegram uses its derived bot ID. Queue provisioning with the current connection revision. An owner qualifies server-derived readiness and explicitly enables the connection. Microsoft shared mailboxes require shared scopes plus Exchange delegation.
3
Send an approved test message to the inbox, then reply from Support. Confirm the conversation, reply thread and provider delivery result before directing customers to that channel.
4
Inspect connection health and delivery state when messages are delayed. Reauthorize expired or revoked grants for the same mailbox. Reauthorization requires qualification and activation again.
5
Treat an uncertain delivery as requiring provider evidence. Do not resend simply because a request timed out: the provider may already have accepted it.
Mailbox synchronization
Gmail uses message history with a full rescan from connection creation when its history cursor expires. Microsoft uses Inbox delta queries and resumes the provider continuation link. These flows synchronize messages arriving since connection creation; they are not a historical migration tool. Mailbox polling normally runs every 30 seconds, with a one-minute retry delay after errors. Notifications can wake synchronization early. This implementation does not depend on automatic Gmail watch or Graph subscription provisioning. Refresh tokens are encrypted and rotated. Message admission and the sync cursor commit together. If admission fails after token rotation, the new token is retained while the message cursor stays available for retry.Delivery and queue behavior
Queues drain bounded batches independently, so a slow external provider does not hold up SLA maintenance or other queues. PostgreSQL claims coordinate replicas. These bounds are execution controls, not a throughput guarantee. Interrupted sends with expired leases are marked uncertain and are not automatically sent again. Verified provider receipts can reconcile a known message ID. Sends with no known provider ID still require manual provider-side investigation. Meta app-wide callbacks validate app signatures and fan out only to selected assets, storing only each workspace’s entries. Early WhatsApp/Facebook receipts survive dispatch races, and Facebook recipient watermarks cannot mark another recipient’s parts. Parent delivered/read states require every part. Meta batches commit valid siblings while recording unsupported payloads. Asset routing and the configured app secret are checked before persistence. Ordered text/media parts retain accepted provider IDs, so safe retries do not resend accepted parts. Unknown outcomes remain uncertain. Managed email uses the owning platform account for Mail authorization. Gmail preserves RFC reply headers and thread IDs; Microsoft uses its native reply endpoint and accepts empty successful responses.Server readiness and provider account selection
Each business connects its own WhatsApp Business account and registered phone number to its Support workspace. StackShift supplies the Meta app; the business authorizes access and selects its own account and phone number. Customers do not need to create a developer app or provide StackShift app secrets. The platform test number is not a shared customer sending number. Meta phone onboarding and account eligibility still apply. Connection detail exposes credential-free readiness reasons, provisioning state and selected-account metadata. One-use OAuth state binds the initiating actor, connection revision, workspace, environment and exact API callback origin; Gmail/Microsoft also use S256 PKCE. Caller health cannot prove readiness. Facebook lists accessible Pages; linked Instagram selects the associated professional account and Page token. WhatsApp discovers owned/client WABAs and connected phone numbers. Instagram Login uses a separate app and instagram_direct profile with SUPPORT_INSTAGRAM_CLIENT_ID and SUPPORT_INSTAGRAM_CLIENT_SECRET; Facebook-linked login retains the Meta app settings, including pages_read_engagement. Microsoft can validate an explicitly selected shared mailbox, retaining the consenting user separately. Read access is checked, but Graph cannot enumerate Exchange Send As rights. A real authorized send is needed to qualify sending permission. Shared mailboxes use Inbox delta polling. Provisioning and owned subscription cleanup are durable jobs. Pre-existing unowned subscriptions remain intact; shared Page/WABA subscriptions remain until the last connection disconnects. Ownership is recorded before provider writes for interrupted provisioning cleanup. Disconnect blocks sends immediately and retains history. Telegram preserves pending updates and requires explicit replace_webhook intent before replacing an unrelated callback. Existing active connections are preserved during migration; the new checks apply when owners qualify or reactivate.Scanned media and delivery status
Inbound mail/file IDs and approved provider CDN sources are hydrated through existing Support storage, content/checksum checks, scanning and quota reservations. URL redirects and unsafe destinations are rejected. Erasure cancels late hydration and clears copied content; physical byte removal is asynchronous. Support allows at most five attachments, ordinary files up to 10 MiB, and supported audio up to 20 MiB with the existing five-minute validation. MP4 video requires valid container structure and a video track. Provider limits are stricter: WhatsApp images 5 MiB/audio 16 MiB, Instagram supported image/video/audio types only, and Microsoft inline outgoing attachments below 3 MiB. Existing Mail total-size limits still apply. Gmail preserves MIME attachments and RFC reply headers. Microsoft uses the selected mailbox. Managed email reads scoped scanned Support files through Mail under the owning account/environment. Telegram retains chat/topic/reply routing. Social sends expose ordered per-part outcomes. GET a message provider-status for media, delivery parts and actions. POST provider-retry retries known failed delivery or exhausted transient media fetches, preserving accepted parts. Rejected content requires correction; uncertain sends require provider evidence. Provider 429 responses back off.Telegram groups, templates and message changes
Owners approve bot-accessible Telegram groups through the channel groups route. Unapproved group transcripts are excluded before persistence. Approved conversations retain group/topic routing and participant attribution, and remain outside private customer transcripts, attachments and customer AI. Telegram privacy mode still controls which events the bot receives. WhatsApp template routes synchronize actual provider status and create/update/delete standard typed UTILITY/MARKETING templates in the selected WABA. Authentication authoring/sending and named parameters are unsupported. Template media is sent once within its header. Template sends validate approval and parameter/media shape at dispatch. Outside the reply window, only approved templates with current stored consent are eligible; consent never permits ordinary free-form replies outside the window. Directional capability fields separate incoming edits/deletions from outgoing operations. Telegram supports ordered incoming edited_message updates and explicit bot-owned outbound edit/caption/delete actions with idempotency and conversation revisions. Ordinary Telegram bots do not receive universal user deletion events. Instagram processes signed incoming edit/delete signals; outbound edits/deletes are not advertised. Edits received before originals and duplicate/older changes preserve order and author scope. Accepted deletion redacts local content; later edits cannot revive erased content. Logical Telegram deletes expose provider IDs and per-part outcomes through provider-status. Failed actions retain local content; another explicit delete skips already confirmed deleted parts. Staff authority is rechecked before each part. Email acceptance is not a delivery receipt, and channel synchronization is not historical import.Release and qualification boundary
Production Compose passes the Meta and Instagram Login settings to both API slots. The pre-migration check rejects incomplete provider credentials or verification tokens and malformed Graph versions. Instagram Login can be configured independently. Staged environment changes take effect when the API container is recreated through the release process; when Support is disabled in the running API, provider routes return 404. These backend changes are implemented locally and unreleased. Quiesce API consumers and Mail delivery workers during migration, update every API replica and the existing Mail worker, then resume. Existing SourceUpload storage and scanning configuration is reused. No product UI or new worker service is included. Use the configured API origin with /support/providers/v1/oauth/callback and the app-wide Meta callbacks /support/providers/v1/meta/facebook_linked/events or /support/providers/v1/meta/instagram_direct/events. Configure the matching SUPPORT_META_WEBHOOK_VERIFY_TOKEN or SUPPORT_INSTAGRAM_WEBHOOK_VERIFY_TOKEN. Telegram uses /support/providers/v1/channels/{connectionID}/events. Channel OAuth start requests may omit redirect_uri so the API supplies its registered callback; the dashboard uses this default even behind a same-origin proxy. Explicit overrides still require the configured API origin or SUPPORT_PROVIDER_DEVELOPMENT_ORIGINS. Deploy the API before the updated Support frontend. App registration, app review, phone onboarding, Exchange delegation and real inbox qualification remain external prerequisites; local tests do not establish those outcomes.Expected result
New channel conversations follow the same allowance and SLA rules as other Support conversations. Duplicate provider deliveries do not create duplicate conversations or consume the allowance again.