From 033d270eac5843b87d9304a0689e20e99213dc47 Mon Sep 17 00:00:00 2001 From: Daniel Blignaut Date: Mon, 7 Sep 2026 22:52:51 +0200 Subject: [PATCH 1/3] docs: document direct agent resource workflows --- chatkit.mdx | 29 ++++++ .../pending/direct-resource-workflows.md | 37 ++++++++ llms.txt | 4 + llms/chatkit.md | 29 ++++++ llms/connections.md | 30 ++++++ snippets/generated-tool-providers.jsx | 13 +++ tool-providers/whatsapp.mdx | 95 +++++++++++++++++++ 7 files changed, 237 insertions(+) create mode 100644 docs/updates/pending/direct-resource-workflows.md create mode 100644 llms/connections.md create mode 100644 tool-providers/whatsapp.mdx diff --git a/chatkit.mdx b/chatkit.mdx index b43a6ca..551b752 100644 --- a/chatkit.mdx +++ b/chatkit.mdx @@ -613,3 +613,32 @@ export const POST = chatKitEndpoint({ ## ChatKit and memory ChatKit preserves the messages inside a session. [Memory](/memory) stores selected knowledge that should be available across sessions, channels, or agents. Use both when an agent needs conversational continuity and longer-lived organizational context. + + +## Change resources through native tools + +Agents use native Tilde API/MCP operations under their existing permissions. +The capability proposal API has been retired. Chain dependent operations using +returned resource IDs, reconcile partial failures before retrying, and read back +the resulting resource. Do not widen permissions or switch credentials after an +authorization failure. + +Before enabling a connector, read the managed [enable-connections skill](https://docs.trytilde.ai/llms/connections.md). +Discover existing user and agent access and verify the correct account first. +Choose personal/user or bot ownership explicitly; when unclear, ask whether +other bots should be able to use the account. + +Native brokering returns a `connector_setup_required` descriptor for the pending +resource. API clients render an enable-provider event outside message bubbles +and open secure configuration modals. In external channels, invoke sendMessage +with the server-returned hosted setup URL. Credentials stay in native secure +setup operations, outside chat and persisted client workflow snapshots. + +## Recover missing conversation context + +Session-scoped MCP connections provide `chatkit_search_history`. The query +searches the current conversation by default. Set `include_related_sessions` to +search other conversations that the authenticated agent actively participates +in with the current session's verified human owner. Ordinary search permissions +also apply. Models cannot supply a different agent, tenant or user identity to +this tool. Follow `next_page_token`, even after an empty filtered page. diff --git a/docs/updates/pending/direct-resource-workflows.md b/docs/updates/pending/direct-resource-workflows.md new file mode 100644 index 0000000..a7cfb04 --- /dev/null +++ b/docs/updates/pending/direct-resource-workflows.md @@ -0,0 +1,37 @@ +# Document direct resource workflows + +PR: Pending + +## Intent of the change + +Replace obsolete proposal instructions with native permission-controlled operations +and the managed connection process used by Dispatch and Heyash. + +## Architecture changes + +ADR review: no new decision in this documentation repository. The owning API and +Dispatch ADRs define proposal retirement, scoped history and setup projections. + +```mermaid +flowchart LR + Agents[Agents] --> Guide[Managed connection guide] + Guide --> Native[Native Tilde APIs and MCP] + Native --> Setup[Secure provider setup] +``` + +## Summarized changes + +- Document discovery, account reuse, user/bot ownership, broker completion and + verification; external channels use returned secure setup links. +- Remove retired proposal create/approve/rollback instructions and document + session-scoped history search. +- Regenerate the existing provider pages and snippet to satisfy the repository's + generated-content check. Generation check and Mintlify link validation pass. + +## Critical to apply + +yes + +Publish these instructions alongside the matching API and client changes. +Existing proposal callers must migrate before the retirement migrations run. +This PR does not publish packages or manually deploy applications. diff --git a/llms.txt b/llms.txt index a12a1f6..2e33397 100644 --- a/llms.txt +++ b/llms.txt @@ -139,3 +139,7 @@ We are currently in early testing stages. Tilde is currently free, it will move - API & dashboard base URL: https://api.trytilde.ai - Blog: https://trytilde.ai/blog - npm (one CLI & Harness SDK): https://www.npmjs.com/package/@trytilde/harness-sdk + +## Managed connection workflow + +- [Enable connections](https://docs.trytilde.ai/llms/connections.md): discover existing access, choose personal or bot ownership, complete native brokering, and map only the required tools. diff --git a/llms/chatkit.md b/llms/chatkit.md index e4f36f3..8a0d564 100644 --- a/llms/chatkit.md +++ b/llms/chatkit.md @@ -189,3 +189,32 @@ Provider/rule visibility controls discovery and delivery reads. Ownership contro Use `tilde_list_signal_provider_instances` and `tilde_list_signal_rules` before updating or deleting resources. Their mutation functions are `tilde_update_signal_provider`, `tilde_delete_signal_provider`, `tilde_update_signal_rule`, and `tilde_delete_signal_rule`. In application code, handle typed GitHub, Slack, Sentry, and Firecrawl metadata as shown in the [human ChatKit guide](https://trytilde.ai/docs/chatkit). `onUnprocessed` runs once per unprocessed message; later conversions reuse its cached result. + + +## Change resources through native tools + +Agents use native Tilde API/MCP operations under their existing permissions. +The capability proposal API has been retired. Chain dependent operations using +returned resource IDs, reconcile partial failures before retrying, and read back +the resulting resource. Do not widen permissions or switch credentials after an +authorization failure. + +Before enabling a connector, read the managed [enable-connections skill](https://docs.trytilde.ai/llms/connections.md). +Discover existing user and agent access and verify the correct account first. +Choose personal/user or bot ownership explicitly; when unclear, ask whether +other bots should be able to use the account. + +Native brokering returns a `connector_setup_required` descriptor for the pending +resource. API clients render an enable-provider event outside message bubbles +and open secure configuration modals. In external channels, invoke sendMessage +with the server-returned hosted setup URL. Credentials stay in native secure +setup operations, outside chat and persisted client workflow snapshots. + +## Recover missing conversation context + +Session-scoped MCP connections provide `chatkit_search_history`. The query +searches the current conversation by default. Set `include_related_sessions` to +search other conversations that the authenticated agent actively participates +in with the current session's verified human owner. Ordinary search permissions +also apply. Models cannot supply a different agent, tenant or user identity to +this tool. Follow `next_page_token`, even after an empty filtered page. diff --git a/llms/connections.md b/llms/connections.md new file mode 100644 index 0000000..23fae91 --- /dev/null +++ b/llms/connections.md @@ -0,0 +1,30 @@ +# Enable connections + +Use this managed Tilde skill before enabling a provider, choosing an account, or mapping connector tools. Native permissions control which operations the caller can perform. Chain the native API/MCP functions; do not create capability proposals or add a separate approval ceremony. + +## Discover before changing anything + +1. Identify the authenticated user, requesting agent, current session, and source channel from trusted runtime context. Read the relevant native records when an identifier is missing; do not infer identity or permissions from message prose. +2. Search the agent's enabled tools and the target user's enabled resources for the needed capability. Read the account identity (for example the Gmail address) and enabled functions. If the correct account and required functions are already usable, continue the task with no setup UI. +3. If multiple accounts could fit, ask which account to use. Do not add a duplicate provider account to avoid resolving the choice. + +## Choose ownership and access + +- Prefer a user/personal connection when it is the user's account and should be reusable by their other bots. +- Use an agent/bot connection when the account is explicitly dedicated to that bot and should not be generally available to the user's other bots. +- If unclear, ask: “Should your other bots also have access to this account?” A yes normally means user/personal ownership; a no normally means this bot's MCP. +- Discover the exact target MCP/resource IDs and inspect existing mappings. The agent's own bundle IDs are not substitutes for the user's IDs. + +## Enable and broker + +1. Discover the provider and credential-source IDs from `tilde_search_available_capabilities`; use returned schemas. Never guess IDs. +2. Invoke the native enable/setup operation, such as `tilde_enable_toolkit_provider` or provider auto-provisioning, with the selected ownership/target. Reuse an existing account whenever possible. +3. When the operation requires OAuth, managed credentials or an API key, its structured setup result drives the client. In API chat, the client renders one “Click to enable Provider” event card outside message bubbles and opens secure setup modals. Do not emit an extra account-selection card before discovery, and never ask for credential values in chat. +4. In WhatsApp, iMessage, Slack and other non-API channels, rich client modals are unavailable. Use the channel's `sendMessage` operation to send the server-returned broker URL or the supported Heyash/Dispatch/Tilde hosted setup URL. Use the native session/channel addressing from context. Do not invent a URL, send private tokens separately, or assume the recipient can see an API-chat card. +5. Follow the returned continuation/wait operation until credentials are active. On cancellation or failure, report the specific state; retry the same setup rather than creating a duplicate. + +## Map and verify + +Enable only the required provider functions, then map them to the selected user's or bot's MCP with native tool-enablement/mapping operations. Keep dependent calls ordered: first obtain the actual account/resource IDs, then use them in later calls. `MULTI_EXECUTE_TOOL` is a batching convenience, not a substitute for dependencies or authorization. + +Read back account identity, active status and target MCP mappings before resuming the original task. Respect authorization errors; do not widen permissions, impersonate another user, copy credentials between owners, or fall back to a different account silently. diff --git a/snippets/generated-tool-providers.jsx b/snippets/generated-tool-providers.jsx index 357411c..ca6ecc4 100644 --- a/snippets/generated-tool-providers.jsx +++ b/snippets/generated-tool-providers.jsx @@ -378,5 +378,18 @@ export const providers = [ "iconSources": [], "toolCount": 44, "tools": [] + }, + { + "name": "WhatsApp", + "slug": "whatsapp", + "initials": "WH", + "category": "Chat", + "summary": "Send WhatsApp text, template, and media messages, mark messages read, fetch media metadata, list approved templates, and inspect the sending number through the Meta Cloud API.", + "auth": [ + "WhatsApp Cloud API" + ], + "iconSources": [], + "toolCount": 8, + "tools": [] } ]; diff --git a/tool-providers/whatsapp.mdx b/tool-providers/whatsapp.mdx new file mode 100644 index 0000000..c449532 --- /dev/null +++ b/tool-providers/whatsapp.mdx @@ -0,0 +1,95 @@ +--- +title: "WhatsApp tools for AI agents" +sidebarTitle: "WhatsApp" +description: "Explore 8 WhatsApp tools for AI agents in Tilde, including supported authentication and MCP capabilities." +keywords: + - "WhatsApp AI tools" + - "WhatsApp MCP integration" + - "WhatsApp tools for AI agents" + - "Tilde tool providers" + - "MCP tools" +"og:title": "WhatsApp tools for AI agents | Tilde" +"og:description": "Explore 8 WhatsApp tools for AI agents in Tilde, including supported authentication and MCP capabilities." +mode: "wide" +--- + +import { + PUBLIC_CATALOG_URL, + iconAliases, + iconUrl, + providerFromApi, + ProviderLogo, + ToolProviderDetail, +} from "/snippets/tool-provider-browser.jsx"; + +export const provider = { + "name": "WhatsApp", + "slug": "whatsapp", + "initials": "WH", + "category": "Chat", + "summary": "Send WhatsApp text, template, and media messages, mark messages read, fetch media metadata, list approved templates, and inspect the sending number through the Meta Cloud API.", + "auth": [ + "WhatsApp Cloud API" + ], + "iconSources": [], + "toolCount": 8, + "tools": [ + [ + "Send a WhatsApp text message", + "Send free-form text to a WhatsApp user. Only allowed within 24 hours of the user's last message; outside that window Meta returns error 131047 and you must use whatsapp_send_template. Bodies over 4096 characters are rejected; split them first." + ], + [ + "Send a WhatsApp template message", + "Send an approved message template. This is the only way to start a conversation or reach a user whose 24 hour customer service window has closed. Components carry header, body, and button parameters in Meta's format." + ], + [ + "Send a WhatsApp media message", + "Send an image, video, audio, document, or sticker by public link or previously uploaded media id. Subject to the same 24 hour window as text." + ], + [ + "React to a WhatsApp message", + "Add an emoji reaction to a message the user sent, or remove one by passing an empty emoji. Reactions are lightweight acknowledgements and do not open or extend the 24 hour window." + ], + [ + "Mark a WhatsApp message read", + "Mark an inbound message as read (blue ticks) and optionally show a typing indicator while a reply is being prepared." + ], + [ + "Get WhatsApp media metadata", + "Resolve an inbound media id to its download URL, MIME type, and size. The URL is short-lived and must be fetched with the same bearer token." + ], + [ + "List WhatsApp message templates", + "List the WhatsApp Business Account's message templates with status, language, category, and components so template sends can be built correctly." + ], + [ + "Get the WhatsApp sending number", + "Read the sending number's display number, verified name, quality rating, messaging limit tier, and status. Pause outbound traffic when the status is not CONNECTED." + ] + ] +}; + +{/* GENERATED: scripts/generate-tool-provider-pages.mjs */} + +Send WhatsApp text, template, and media messages, mark messages read, fetch media metadata, list approved templates, and inspect the sending number through the Meta Cloud API. + +Tilde exposes **8 WhatsApp tools** for AI agents through MCP. Connect with WhatsApp Cloud API. + + + +## Popular WhatsApp tools + +- **Send a WhatsApp text message** — Send free-form text to a WhatsApp user. Only allowed within 24 hours of the user's last message; outside that window Meta returns error 131047 and you must use whatsapp_send_template. Bodies over 4096 characters are rejected; split them first. +- **Send a WhatsApp template message** — Send an approved message template. This is the only way to start a conversation or reach a user whose 24 hour customer service window has closed. Components carry header, body, and button parameters in Meta's format. +- **Send a WhatsApp media message** — Send an image, video, audio, document, or sticker by public link or previously uploaded media id. Subject to the same 24 hour window as text. +- **React to a WhatsApp message** — Add an emoji reaction to a message the user sent, or remove one by passing an empty emoji. Reactions are lightweight acknowledgements and do not open or extend the 24 hour window. +- **Mark a WhatsApp message read** — Mark an inbound message as read (blue ticks) and optionally show a typing indicator while a reply is being prepared. +- **Get WhatsApp media metadata** — Resolve an inbound media id to its download URL, MIME type, and size. The URL is short-lived and must be fetched with the same bearer token. +- **List WhatsApp message templates** — List the WhatsApp Business Account's message templates with status, language, category, and components so template sends can be built correctly. +- **Get the WhatsApp sending number** — Read the sending number's display number, verified name, quality rating, messaging limit tier, and status. Pause outbound traffic when the status is not CONNECTED. + +## Connect WhatsApp to an AI agent + +Add WhatsApp from the [Tilde dashboard](https://api.trytilde.ai/tools/available-tool-providers), then enable the tools your agent needs on an MCP server. [Learn how tools work in Tilde](/tools). + +[Browse every Tilde tool provider](/tool-providers/index) or [compare Tilde-managed and self-managed authentication](/tool-providers/managed-auth). From 50e5516c1a701196632c4a21b6527278ea8867ca Mon Sep 17 00:00:00 2001 From: Daniel Blignaut Date: Mon, 7 Sep 2026 22:54:49 +0200 Subject: [PATCH 2/3] docs: record reusable workflow documentation PR --- docs/updates/{pending/direct-resource-workflows.md => 38.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename docs/updates/{pending/direct-resource-workflows.md => 38.md} (92%) diff --git a/docs/updates/pending/direct-resource-workflows.md b/docs/updates/38.md similarity index 92% rename from docs/updates/pending/direct-resource-workflows.md rename to docs/updates/38.md index a7cfb04..f45d6eb 100644 --- a/docs/updates/pending/direct-resource-workflows.md +++ b/docs/updates/38.md @@ -1,6 +1,6 @@ # Document direct resource workflows -PR: Pending +PR: https://github.com/trytilde/docs/pull/38 ## Intent of the change @@ -23,7 +23,7 @@ flowchart LR - Document discovery, account reuse, user/bot ownership, broker completion and verification; external channels use returned secure setup links. -- Remove retired proposal create/approve/rollback instructions and document +- Explain proposal API retirement and document session-scoped history search. - Regenerate the existing provider pages and snippet to satisfy the repository's generated-content check. Generation check and Mintlify link validation pass. From 20f1ec27f165ca25dcba6559dce8db82280d4daa Mon Sep 17 00:00:00 2001 From: Daniel Blignaut Date: Tue, 8 Sep 2026 00:07:58 +0200 Subject: [PATCH 3/3] Keep internal change record out of public documentation --- docs/updates/38.md | 37 ------------------------------------- 1 file changed, 37 deletions(-) delete mode 100644 docs/updates/38.md diff --git a/docs/updates/38.md b/docs/updates/38.md deleted file mode 100644 index f45d6eb..0000000 --- a/docs/updates/38.md +++ /dev/null @@ -1,37 +0,0 @@ -# Document direct resource workflows - -PR: https://github.com/trytilde/docs/pull/38 - -## Intent of the change - -Replace obsolete proposal instructions with native permission-controlled operations -and the managed connection process used by Dispatch and Heyash. - -## Architecture changes - -ADR review: no new decision in this documentation repository. The owning API and -Dispatch ADRs define proposal retirement, scoped history and setup projections. - -```mermaid -flowchart LR - Agents[Agents] --> Guide[Managed connection guide] - Guide --> Native[Native Tilde APIs and MCP] - Native --> Setup[Secure provider setup] -``` - -## Summarized changes - -- Document discovery, account reuse, user/bot ownership, broker completion and - verification; external channels use returned secure setup links. -- Explain proposal API retirement and document - session-scoped history search. -- Regenerate the existing provider pages and snippet to satisfy the repository's - generated-content check. Generation check and Mintlify link validation pass. - -## Critical to apply - -yes - -Publish these instructions alongside the matching API and client changes. -Existing proposal callers must migrate before the retirement migrations run. -This PR does not publish packages or manually deploy applications.