paperclip/doc/plans/chat-adapters/platforms/report-source.md

Platform-specific chat adapter research source

Internal synthesis source — do not publish as the reviewer-facing artifact. Date: 2026-09-04 Paperclip base: origin/master at 8430bd897f01dd4b91e0970efffb71b97e5a2685 Chat SDK snapshot: 51322dde8f4aafd8a7fc7a20cbfd7ae45cafaa5c

This is an implementation research snapshot. The current executable contract is the browser runbook and platform-surfaces companion; upstream capabilities described here are not automatically shipped Paperclip capabilities.

Research question

What provider-specific setup, configuration, and interaction behavior must Paperclip expose for Slack, GitHub, Discord, Microsoft Teams, and Telegram while preserving the shared rule that Paperclip owns agents, issues, runs, permissions, publications, and audit history?

Claim-gap matrix

Claim needed for the product plan	Primary evidence	Confidence	Product consequence
Slack can use verified HTTP webhooks, OAuth installations, or Socket Mode.	Chat SDK Slack adapter at the pinned revision, Slack request verification, Slack Socket Mode	High	Paperclip selects direct verified callback or its relay from instance reachability. Socket Mode is an instance-admin escape hatch, never an endpoint-wizard choice.
Slack events and interactive payloads must be acknowledged quickly.	Slack Events API, Slack interactivity	High	Persist first, acknowledge immediately, process asynchronously; modal-opening callbacks require a fast path because trigger IDs expire.
Slack gives the fullest Chat SDK interaction surface.	Pinned Slack adapter feature table, Slack Agent Sessions	High	Native threads, streaming, Block Kit, actions, modals, slash commands, files, DMs, reactions, and ephemeral responses are used automatically whenever the installation, conversation, and Paperclip authorization permit them.
A GitHub App is the least-privilege production credential.	GitHub App registration, choosing GitHub App permissions, pinned GitHub adapter setup	High	Recommend a GitHub App with Issues/PR write and Metadata read, installed only on selected repositories. PAT is a development-only fallback.
GitHub chat does not imply repository-code tool access.	GitHub permissions are independently selectable and installation repositories are scoped in GitHub App permissions.	High	The chat connector does not request Contents permission. An agent that must read/write code receives a separate tool-purpose connection and grant.
GitHub's native conversation unit is the existing issue, PR conversation, or review-comment thread.	Pinned GitHub adapter thread model, issue comments API	High	A mention binds an existing GitHub object/thread to one Paperclip issue. Paperclip does not create an extra chat thread. PR-level and inline review threads remain distinct.
Teams setup includes app/bot registration, a reachable messaging endpoint, a customer-owned Teams app, and tenant installation policy.	Teams app registration quickstart, pinned Teams adapter setup	High	Provide the exact endpoint and manifest settings; require the customer-owned Entra/Azure Bot/Teams app path; detect disabled sideloading without promising a Paperclip-generated package.
Teams normally receives mentions; subscribed channel/group replies require the shipped RSC entries.	Teams all-message/RSC guidance, resource-specific permissions	High	The customer-owned Teams app includes ChannelMessage.Read.Group and ChatMessage.Read.Chat for fixed addressed-thread behavior. They are not endpoint toggles and do not grant tenant-wide Graph history/directory access.
Some Teams Graph operations require broader Entra permissions and admin consent.	Graph chat message permissions, pinned Teams adapter history/user lookup notes	High	User.Read.All and DM history remain optional, visibly privileged add-ons. The basic mention/reply experience must not depend on them.
Discord bots receive messages and interactions through a long-lived Gateway client.	Discord Gateway documentation, pinned Discord adapter	High	Use a direct outbound Gateway runtime. Do not request a webhook URL, interactions public key, slash-command setup, or endpoint delivery choice for the current feature set.
Discord message content and channel actions require explicit intent and effective bot permissions.	Discord Gateway intents, Discord OAuth2	High	Verify Message Content Intent, server installation, and per-channel permissions. Generate only the bot-scope install URL with the reviewed permission integer; provider availability remains the ceiling on Paperclip access.
Telegram webhooks and long polling are mutually exclusive, and webhooks support a secret-token header.	Telegram Bot API getUpdates and setWebhook, pinned Telegram adapter modes	High	Cloud/public instances use verified webhooks; local long-running development may poll; private production uses the Paperclip relay rather than an unverified webhook.
Telegram privacy mode changes which group replies the bot receives.	Telegram bot privacy FAQ, Telegram bot features	High	Keep privacy mode on. A group starts work with @bot; continuing turns must reply to the bot's message or mention it. Forum topics can use a stable topic boundary.
Telegram's Chat SDK surface is narrower and rate-sensitive.	Pinned Telegram feature/streaming table, Telegram bot FAQ	High	Default to throttled post-and-edit, use native drafts only in private chats when enabled, use inline buttons instead of modals/selects, and never promise ephemeral messages.
Telegram supports commands as a platform, but the pinned Chat SDK adapter does not expose the shared slash-command feature.	Telegram commands, pinned adapter feature table	High	Parse a small Paperclip command vocabulary (/new, /status, /close) as normal messages in Telegram glue until the SDK adapter exposes command events.

Provider synthesis

Slack

• External setup: create or select a Slack app; use a generated manifest for the exact bot scopes and events; set the Paperclip webhook URL for Events, Interactivity, and optional slash commands; install to a workspace; store bot/OAuth credentials through Paperclip secret references; verify bot identity, signature, scopes, events, and workspace. Managed Add to Slack remains optional. For Enterprise Grid, installation identity may be the enterprise rather than a single team.
• Default behavior: a root @bot mention activates the endpoint. The first bot reply under that root establishes the Slack thread and the Paperclip issue binding. Human replies in the bound thread continue without another mention. A DM conversation is a stable issue boundary.
• Automatic capability behavior: Agent Sessions/native streaming and stop, Block Kit actions, modals, slash commands, files, and ephemeral denials are used whenever supported and authorized. App Home/suggested prompts are installation concerns. Socket Mode is an instance-admin delivery escape hatch, not an endpoint setting or response-feature switch.
• Operational caveats: acknowledge events and actions within Slack's deadline; persist delivery before asynchronous processing; dedupe by event ID; ignore the bot's own messages; surface missing scopes and bot-not-in-channel distinctly; token rotation and OAuth reinstallation must not change the endpoint identity.

GitHub

• External setup: create a GitHub App with webhook URL/secret, application/json, Issues read/write, Pull requests read/write, and Metadata read; subscribe to Issue comment and Pull request review comment; generate/store the App private key; install to selected repositories. GitHub Enterprise Server adds an API base URL. PAT is a visibly non-production fallback.
• Credential separation: the chat-purpose app does not request Contents, Actions, Administration, or other repository tool permissions. If Maya needs code access during a Paperclip run, /apps creates a separate GitHub tool connection with its own credential audience and agent grant.
• Default behavior: @bot in an issue comment or PR conversation binds that existing issue/PR to one Paperclip issue. An inline review-comment thread has a different stable key and binds separately. Further human comments in the bound context continue the task; self-authored bot comments and redeliveries are suppressed.
• Rendering: GitHub-Flavored Markdown, reactions, comment edits, and links. No native streaming, DMs, ephemeral messages, modals, or Chat SDK buttons/selects. Progress should update one bot comment at a coarse cadence; governed actions link to authenticated Paperclip pages. The current adapter treats URLs in inbound comments as ordinary text and does not ingest them as files. Outbound artifacts become Paperclip URLs because the adapter has no file-upload surface.

Microsoft Teams

• External setup: Paperclip provides the messaging endpoint and required manifest settings. The operator creates the single-tenant Entra app, Azure Bot, and customer-owned Teams app in Microsoft, then enters client ID, tenant ID, and client secret in Paperclip. Custom app upload/install must be allowed. No provisioning helper is shipped; Paperclip does not currently generate a package or install link. Paperclip verifies Entra/bot identity, endpoint reachability, tenant mode, and installation activity.
• Authentication: the portable customer-owned path uses a client ID, tenant ID, and client secret for a single-tenant registration. Federated workload identity and sovereign/GCC deployment remain future instance-level concerns, not endpoint choices.
• Default behavior: personal, team, and group-chat scopes are enabled as installed; direct mentions are the least-privilege trigger. In a Teams channel, a new post and its replies are one native thread and one Paperclip issue. A group chat or DM uses its stable conversation identity.
• Permissions: the shipped customer-owned app manifest includes the resource-specific entries required for subscribed channel/group replies. Broader Entra permissions such as User.Read.All and Chat.Read.All are not required by the basic connector and are not exposed as endpoint controls.
• Rendering: Adaptive Cards, buttons, task-module/modal interactions, reactions, typing, and targeted-message/DM fallback. Paperclip's durable webhook pipeline sets native Teams streaming to false and uses bounded post/edit output in DMs, channels, and groups. Native file receipt/upload is personal-chat-only; channel/group files require a separate Graph connection and otherwise fall back to a safe Paperclip link without ingestion. Select menus and slash commands fall back to text or cards.

Discord

• External setup: create one customer-owned application bot per immutable Paperclip agent, enable Message Content Intent, and enter Application ID, Server ID, and bot token. Paperclip generates a server-pinned install URL with only the bot scope and the reviewed permission integer, then verifies application identity, intent, membership, and effective text-channel permissions.
• Transport: a long-lived outbound Gateway client receives messages, reactions, interactions, edits, and deletes. Discord therefore needs no public Paperclip callback, interactions public key, or endpoint delivery selector. Reconnect, resume, and provider retry_after timing are runtime behavior.
• Default behavior: a root @bot mention creates a Discord public thread and exactly one Paperclip task; replies in that thread continue it without another mention. Direct messages use separate linear task generations. A globally unique Discord Application ID prevents one provider bot identity from representing multiple Paperclip agents.
• Rendering: bounded post/edit output, embeds, supported buttons, reactions, and native files are automatic when permitted. The current connector does not advertise slash commands, modals, true ephemeral responses, or proactive DMs.
• Qualification boundary: Paperclip preflights endpoint, resource, principal, and root-message admission before provider-thread creation, so a denied root creates no Discord thread or Paperclip work. An allowed root persists a provisional receipt before the provider effect, and recovery idempotently creates or reuses the thread, including existing-thread error 160004. Those guarantees have deterministic and fresh-database evidence but still require real-provider fault-path proof.

Telegram

• External setup: create one bot per Paperclip agent with BotFather; set name and an available username; paste the bot token into Paperclip. Paperclip calls getMe, registers suggested commands, and selects verified webhook, relay, or local-development polling from the deployment. The operator adds the bot to intended chats and keeps privacy mode on. Forum-topic creation requires additional admin rights and is optional.
• Default privacy: privacy mode stays on. In a group, an @bot message activates a task; follow-ups must reply to a bot message or mention it. Unaddressed group traffic is invisible/ignored. A forum topic is a stable task boundary when present.
• Linear conversation boundary: the first DM creates the active Paperclip issue. /new or the New task inline button closes/shelves the current binding and starts another; /status and /close are parsed from normal Telegram messages. Ordinary groups without topics use the activation message/reply chain as the visible conversation, while Paperclip stores the explicit active binding.
• Rendering: typing/reaction acknowledgement, throttled post-and-edit by default, native draft preview in DMs when available, MarkdownV2/rich-message fallback, inline buttons and URL buttons, files/media. No ephemeral response, modal, select, or list-threads support. Permission denials use a concise normal reply or DM.
• Operational caveats: dedupe by update_id; configure allowed_updates; show pending webhook updates and last error; respect per-chat/group flood limits; callback payloads contain only opaque short IDs; rotate a leaked bot token through BotFather and update the secret reference.

Cross-provider decisions resulting from the research

1. The shared two-decision onboarding remains intact. Provider complexity belongs in the provider handoff and post-connect settings, not in a universal wizard.
2. Each setup surface follows one vertical sequence while clearly labeling what Paperclip provides and what must be completed at the provider. Paperclip can generate manifests, URLs, secrets, and copyable commands, but it cannot pretend that tenant/workspace/repository installation policy is under Paperclip control.
3. Capability status is rendered from the adapter registry on Overview. Response features are not endpoint controls: the runtime uses the maximum safe supported behavior and explains the exact fallback when provider support, installation permissions, conversation type, or Paperclip authorization prevent it.
4. Provider permission escalation is incremental. Basic mention/reply operation uses the smallest viable permission set; history, all-message visibility, user-directory lookup, and code/tool access are separate grants.
5. Conversation boundaries are provider-native and explicit: Slack thread, GitHub object/review thread, Teams post thread or conversation, Discord public thread or DM generation, Telegram DM/group active binding or forum topic.
6. Every provider-specific interaction still enters the same durable delivery → principal/permission → issue binding → Paperclip wakeup → safe publication flow.

Residual validation before implementation

• Confirm the exact Slack app manifest against the Chat SDK version finally pinned for implementation, including any optional Agent Sessions scopes/events.
• Test Teams channel reply events in mention-only mode and document precisely when subscribed replies require RSC versus ordinary bot conversation delivery.
• Test Telegram privacy-on reply delivery, forum-topic identifiers, native draft support, and effective file-download ceilings against the production Bot API version.
• Confirm whether the GitHub adapter should include Discussion comments in the first release; the pinned adapter documents issues, PR conversations, and review comments, so Discussions should remain out of the launch promise unless implemented and tested.
• Run provider sandbox fixtures for redelivery, edits/deletes, bot self-messages, credential revocation, permission drift, and uninstall/reinstall identity stability.