39633c2217
Connector catalog, setup guides, and shared access documentation, followed by a final code-accuracy repair pass. This PR does not change application behavior. ## Final accuracy pass Checked against shipped Paperclip `v2026.916.0`, commit `dffc2b3ca1b9e88fa21cb17493083e682dffd1ca`, rather than the dirty local checkout or the earlier canary baseline. - Corrects connector/method-specific identity choices, human audiences, and managed GitHub versus PAT scope and verification. - Explains that **Always allow** covers different arguments for the same agent/action/connection, with project scope when present; uses actual button labels and removes the test-panel control from review instructions. - Qualifies new-action quarantine, including safe-default read exceptions. Removes unconditional approval guarantees. - Separates provider channel/repository reach from Paperclip sender authorization. - Completes sandbox sign-in and model credential-selection instructions from the current UI implementation. - Repairs Notion's hub summary, removes incomplete optional Notion/Sentry client-registration procedures, and corrects Linear's provider-versus-Paperclip attribution. - Removes unsupported Postman tier claims, contradictory Cloudinary/Mem0 verification assertions, API-equivalence claims, and overbroad successful-test assurances. - Retains Supabase's required project reference: both released method definitions explicitly require it. An earlier review suggested otherwise; release code is authoritative here. - Updates the release baseline and removes draft commit chronology from the public introduction. ## Availability and remaining runtime gates - **Google:** Verification is pending. Per the product-owner clarification, authorization can continue where Google offers an Advanced option; this is not available for every account and does not override Workspace policy or other Google prerequisites. Notices on the hub and all Google guides now distinguish an unverified-app warning from blocked authorization. - **Slack is available but not yet fully functional; follow-up fixes are planned.** For agent tools, the released OAuth endpoint/scope defaults differ from Slack's documented MCP contract. The page now warns against treating that route as production-ready and removes the misleading bot-scope walkthrough. Chat-channel bot setup remains separate. Engineering must reconcile the integration and run OAuth plus one read before removing this warning. Source: https://docs.slack.dev/ai/slack-mcp-server/ - No credentialed connector run was performed in this pass. Code consistency, provider documentation, UI rendering, and successful live execution are separate evidence levels. No claim of runtime certification for all connectors. ## Validation - Root build: 253 crawlable documentation pages. - Full `docs:test`: all eight suites passed locally, including root/subpath routes, sitemap history, fingerprints, navigation, skill source blocks, crawlable links, doc-link resolution, and SEO metadata. - Internal-link lint: 258 Markdown files; no broken internal links. - Latest cleanup: full build, all eight docs:test suites, internal-link lint and diff whitespace checks passed; 1,878 link-resolution checks. - Fixed the Calendar MCP reference URL; browser-checked the five inconclusive external destinations (Miro article loads; Asana, Google Cloud, OpenAI and xAI reach sign-in/console screens). Authenticated destinations were not tested beyond those screens. - Replaced the Sandbox providers editorial TODO with a scope note and removed the CLI overview's unfinished-guide announcement. - Browser client navigation: 687 checks passed using installed Chrome. Initial launch lacked the downloaded Playwright browser; rerun used `DOCS_CHROMIUM_PATH` without changing the tests. - Nine representative connector/shared pages at 1440px and 390px: HTTP 200, one article H1, no page-level horizontal overflow. Mobile screenshot inspected; approval page opened in the Codex browser. - Navigation audit reports three existing non-connector orphan files; this patch does not alter those files or their navigation. The previous revision's provider-page expansion, Google shared setup guide, navigation additions, and accidental node_modules-symlink cleanup remain in this PR. Internal review ledgers remain outside the publication branch. No merge or production deployment authorized. --------- Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> Co-authored-by: Claude Opus 5 (1M context) <[email protected]> Co-authored-by: Michael Nguyen <[email protected]>
5.9 KiB
seo_title, seo_description
| seo_title | seo_description |
|---|---|
| Telegram Connector | Let people start Paperclip work by messaging a Telegram bot. BotFather setup, the public webhook requirement, agent routing, and fixing a silent bot. |
Telegram
People message your Telegram bot, and Paperclip starts work. Replies come back in the same Telegram conversation.
One connection serves one bot and one agent.
Warning: Telegram delivers messages by calling Paperclip, so your instance needs a publicly reachable HTTPS address. Telegram only accepts webhooks on ports 443, 80, 88, or 8443. If your instance is not reachable that way, this connector cannot work — unlike AgentMail, there is no outbound-only mode.
Before you connect
- Chat connectors must be switched on for the instance. It is an experimental setting, off by default, enabled by an instance administrator under experimental settings.
- A publicly reachable HTTPS URL for the instance, configured by an administrator as
PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL, on one of Telegram's permitted ports. - A Telegram account, to talk to BotFather.
- The agent that will answer.
Connect Telegram
1. Create the bot
- Message @BotFather in Telegram and send
/newbot. - Give the bot a display name and a username ending in
bot. - Copy the bot token BotFather returns. It looks like
123456789:AA....
Create a dedicated bot for this connector rather than reusing one that already has another webhook — a Telegram bot supports one webhook at a time, so connecting here replaces whatever it pointed at before.
Danger: The bot token is a full credential for the bot. Never paste it into a chat, an issue, or a screenshot. If it leaks, use BotFather's
/revoketo rotate it and reconnect.
2. Connect it in Paperclip
- Open Connectors and select Telegram.
- On the Access step, choose the identity and which agents may use the connection.
- Paste the Bot token.
- Choose the agent that will answer, and finish.
Paperclip registers the webhook with Telegram for you, using a generated secret so it can reject forged deliveries. There is no URL for you to paste into BotFather.
How a conversation becomes work
| In Telegram | In Paperclip |
|---|---|
| Someone sends the bot a direct message | A task is created for the connected agent |
| They keep replying | The conversation continues on the same task |
| The agent responds | The reply arrives in the Telegram conversation |
Choose access
Two different controls apply here, on two different sides, and conflating them is the mistake worth avoiding.
On Telegram's side there is no sender allowlist. Anyone who can find the bot can message it. Do not treat the bot's username as a secret — treat it as public, and share it only with the people you intend to serve.
On Paperclip's side there is a control. The connection's Access tab has External identity access with an Allow unlinked people toggle:
| Setting | What happens when an unrecognized person messages the bot |
|---|---|
| On (the default) | They are a restricted guest. Their tasks run only with an isolated workspace and sandbox environment, and Paperclip refuses the request if that is unavailable. Guests cannot approve, hire, spend, manage access, or reassign agents |
| Off | They cannot start work at all. Only senders linked to a Paperclip person get through |
So "anyone can message the bot" is true, and "anyone can make an agent do arbitrary work" is not. Decide which of those two settings you want before you publish the username; the restrictions on a guest are real but they are not the same as refusing them.
In groups, Telegram's default privacy mode means a bot only receives messages that address it directly. Turning that off in BotFather would give the bot every group message; leave it alone unless you have decided you want that.
The connection's identity and agent settings work as for any connector; see How connector access works. The answering agent is set on the connection.
Try it
- Open your bot in Telegram and send
hello, can you confirm you are connected? - Expect a reply in the conversation within a few moments.
- Confirm a matching task appears in Paperclip, assigned to the connected agent.
Message the bot from your own account first. That exercises webhook delivery, routing, and task creation without involving anyone else.
Note: Procedure, not a recorded test result.
Troubleshooting and limitations
| Problem | Likely cause | Fix |
|---|---|---|
| Telegram does not appear in Connectors | Chat connectors is off for the instance | Ask an administrator to enable it |
| Setup fails mentioning HTTPS and ports | The instance's public webhook URL is missing or on an unsupported port | An administrator must set PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL to HTTPS on 443, 80, 88, or 8443 |
| The bot exists and accepts messages but never replies | Telegram cannot reach the instance, or another system replaced the webhook | Reconnect the connection, which re-registers the webhook |
| The bot worked and went silent | The token was revoked, or another tool called setWebhook on the same bot |
Rotate the token if needed and reconnect; use a dedicated bot |
| The bot ignores messages in a group | Telegram privacy mode delivers only messages addressing the bot | Address the bot directly, or reconsider whether a group is the right entry point |
| The wrong agent answers | The answering agent is set on the connection | Change it on the connection |
Limitations: one bot and one agent per connection. No sender allowlist. A Telegram bot has a single webhook, so the bot cannot be shared with another integration.
Related guides
- Discord, Slack, Microsoft Teams — other conversation channels.
- How connector access works
- Telegram bot tutorial