chat 4.31.0 → 4.33.0

package/resources/guides/build-a-slack-bot-with-vercel-connect.md

@@ -0,0 +1,239 @@
+# Build your own Slackbot with Vercel Connect
+
+**Author:** Ben Sabic
+
+---
+
+You can build an AI-powered Slack bot that responds to mentions, maintains conversation history, and calls tools autonomously, without storing a long-lived Slack bot token or signing secret in your environment. Chat SDK handles the platform integration (e.g., webhooks and message formatting) and AI SDK's `ToolLoopAgent` runs the reasoning loop that lets your agent call tools and act on results. [Vercel Connect](https://vercel.com/connect) issues a user-authorized Slack token at runtime and forwards Slack events to your project, keeping credentials scoped to the environments that need them.
+
+You'll create a Slack connector using Vercel Connect, link it to your project, and request a scoped runtime token from your agent's code. Along the way, you'll enable streaming responses, tool calling, and more using Redis and the [Vercel AI Gateway](https://vercel.com/ai-gateway).
+
+> **Vercel Connect is in beta and available on all plans.** Features and behavior, including available connectors and trigger forwarding, may change before general availability. Usage is subject to the [Beta Agreement](https://vercel.com/docs/release-phases/public-beta-agreement) and [Vercel Connect terms](https://vercel.com/docs/connect/legal).
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+*   Node.js 20+ and a package manager (e.g., [pnpm](https://pnpm.io/))
+    
+*   Access to a Vercel team and project with Vercel Connect enabled
+    
+*   Vercel CLI installed (`npm i -g vercel`)
+    
+*   A Slack workspace where you can install an app
+    
+
+## How it works
+
+Chat SDK is a unified TypeScript SDK for building chatbots across Slack, Teams, Discord, and other platforms. You register event handlers (like `onNewMention` and `onSubscribedMessage`), and the SDK routes incoming webhooks to them. The Slack adapter handles message parsing and Slack API interactions. The Redis state adapter tracks which threads your bot has subscribed to and manages distributed locking to handle concurrent messages.
+
+AI SDK's `ToolLoopAgent` wraps a language model with tools and runs an autonomous loop: the model generates text or calls a tool, the SDK executes the tool, feeds the result back, and repeats until the model finishes. When you pass a model string like `"anthropic/claude-opus-4.8"`, and host your application on Vercel, the AI SDK will route the request through the AI Gateway automatically.
+
+Chat SDK accepts any `AsyncIterable<string>` as a message, so you can pass the agent's `fullStream` directly to `thread.post()` for real-time streaming in Slack.
+
+Vercel Connect provides Slack credentials at runtime, so you don't have to manage a static bot token. You register a Slack connector once, link it to your project, then call `getToken` from your code for a short-lived, scoped Slack token. Connect also forwards inbound Slack events to a trigger destination you register on the connector. For this agent, that destination is your project at `/api/webhooks/slack`.
+
+Connect handles authentication in both directions:
+
+*   For outbound calls to the Slack API, `getToken` from `@vercel/connect` gives your agent a short-lived Slack token.
+    
+*   For inbound events, Connect verifies them with Slack and forwards them to your app. Your `webhookVerifier` then confirms each one came from Connect using `verifyVercelOidcToken` from `@vercel/oidc`.
+    
+
+## Steps
+
+### 1\. Scaffold the project, install dependencies, and add the Vercel Plugin
+
+Create a new [Next.js](https://nextjs.org/) app and add your dependencies:
+
+`npx create-next-app@latest my-slack-agent --typescript --app cd my-slack-agent pnpm add chat @chat-adapter/slack @chat-adapter/state-redis ai zod @vercel/connect @vercel/oidc`
+
+Here's what each package does:
+
+*   The `chat` package is the Chat SDK core.
+    
+*   The `@chat-adapter/slack` and `@chat-adapter/state-redis` packages are the [Slack platform adapter](https://chat-sdk.dev/adapters/slack) and [Redis state adapter](https://chat-sdk.dev/adapters/redis), respectively.
+    
+*   The `ai` package is the AI SDK, and includes the [AI Gateway provider](https://ai-sdk.dev/providers/ai-sdk-providers/ai-gateway).
+    
+*   `zod` is used to define tool input schemas.
+    
+*   `@vercel/connect` is the Vercel Connect SDK, which provides `getToken`.
+    
+*   `@vercel/oidc` verifies the Bearer OIDC token on Connect-forwarded webhooks (`verifyVercelOidcToken`).
+    
+
+* * *
+
+The [Vercel Plugin](https://vercel.com/docs/agent-resources/vercel-plugin) turns your AI coding agent (e.g., OpenAI Codex, Claude Code, or Cursor) into a Vercel expert. It adds skills, slash commands, and current knowledge of the tools this template uses, including Vercel Connect, Chat SDK, and AI SDK. The plugin is optional; it isn't required to build your Slackbot or to follow this guide.
+
+`npx plugins add vercel/vercel-plugin`
+
+### 2\. Create a Slack connector with Vercel Connect
+
+Vercel Connect creates and manages the Slack app for you. You don't register an app at [api.slack.com](https://api.slack.com), write a manifest, or copy any credentials. You create a connector in the Vercel dashboard, set its scopes and events there, and install it in your workspace.
+
+Open the [Connect page](https://vercel.com/d?to=%2F%5Bteam%5D%2F~%2Fconnect) on your team's dashboard, then click Create Connector to start the Add Connection flow. Once you've done that:
+
+1.  Choose Slack as the provider.
+    
+2.  Select your Slack workspace and name the app (e.g., `acme-slack`). If you haven't connected a Slack workspace yet, connect and authorize one first, then return to the [Connect page](https://vercel.com/d?to=%2F%5Bteam%5D%2F~%2Fconnect). Keep Triggers enabled so Slack events reach your project.
+    
+3.  Open Advanced and set:
+    
+    *   Bot Scopes the agent needs: `chat:write`, `channels:history`, `channels:read`, `groups:history`, `im:history`, `mpim:history`, `reactions:write`, and `users:read`.
+        
+    *   Trigger Event Types to forward: `app_mention`, plus the message events for the surfaces your agent supports (`message.channels`, `message.groups`, `message.im`, `message.mpim`), so both new mentions and follow-up replies work.
+        
+4.  Click Create Slack Connector, then Install to your Slack Workspace.
+    
+5.  In the connector's settings, link it to your project, select the environments it applies to (e.g., production), and register your project as a trigger destination with the path `/api/webhooks/slack`, the route you'll create in step seven.
+    
+
+Because Connect manages the Slack app, Slack delivers events to Connect's intake URL (shown in the connector settings), not directly to your deployment's `/api/webhooks/slack`. Connect verifies Slack, then forwards each event to the trigger destination you registered.
+
+### 3\. Provision Redis and pull environment variables
+
+Your agent uses Redis for thread subscriptions and distributed locking. Provision [Upstash Redis](https://vercel.com/marketplace/upstash) and connect it to your project with the Vercel CLI:
+
+`vercel link vercel integration add upstash`
+
+`vercel integration add` installs the Upstash integration if it isn't already, provisions a database, connects it to your project, and pulls its connection environment variables into `.env.local`. Follow the prompts to pick the Redis product and a plan.
+
+To use the dashboard instead, open the [Storage](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fstores) page for your project, click Create Database, and follow the flow to add Upstash Redis. Then sync the variables locally:
+
+`vercel env pull`
+
+`vercel env pull` also adds a `VERCEL_OIDC_TOKEN`, which AI SDK uses to authenticate requests to the AI Gateway, so there's no API key to generate or store. The OIDC token expires after 12 hours, so re-run `vercel env pull` to refresh it, or start the dev server with `vercel dev` to refresh it automatically. Linking the project also lets Vercel Connect resolve the connector when your code calls `getToken`.
+
+You should see `REDIS_URL` (from Upstash) and `VERCEL_OIDC_TOKEN` (for AI Gateway and `@vercel/connect`). You should not add `SLACK_BOT_TOKEN` or `SLACK_SIGNING_SECRET`.
+
+### 4\. Define your agent's tools
+
+Create `lib/tools.ts` with the tools your agent can call. This example defines a weather tool and a docs tool, but you can add any tools your use case requires:
+
+``import { tool } from "ai"; import { z } from "zod"; export const tools = { getWeather: tool({ description: "Get the current weather for a location", inputSchema: z.object({ location: z.string().describe("City name, e.g. San Francisco"), }), execute: async ({ location }) => { // Replace with a real weather API call const response = await fetch( `https://api.weatherapi.com/v1/current.json?key=${process.env.WEATHER_API_KEY}&q=${encodeURIComponent(location)}` ); const data = await response.json(); return { location, temperature: data.current.temp_f, condition: data.current.condition.text, }; }, }), searchDocs: tool({ description: "Search the company documentation for a topic", inputSchema: z.object({ query: z.string().describe("The search query"), }), execute: async ({ query }) => { // Replace with your actual search implementation return { results: [`Result for: ${query}`] }; }, }), };``
+
+Each tool has a `description` (which tells the model when to use it), an `inputSchema` (a Zod schema that the model fills in), and an `execute` function that runs when the tool is called. If a tool calls another provider that Vercel Connect supports (e.g., GitHub), it can request a scoped token for itself.
+
+### 5\. Create the Connect webhook verifier
+
+Before the bot can trust an incoming event, it needs to verify the OIDC Bearer token that Connect attaches to each forwarded webhook. Create `lib/slack-connect-webhook-verifier.ts`:
+
+`import { verifyVercelOidcToken } from "@vercel/oidc"; const BEARER_TOKEN_PATTERN = /^Bearer\s+(.+)$/i; export async function verifySlackConnectWebhook( request: Request ): Promise<true> { const token = request.headers .get("authorization") ?.match(BEARER_TOKEN_PATTERN)?.[1] ?.trim(); if (!token) { throw new Error("Missing Authorization bearer token"); } await verifyVercelOidcToken(token); return true; }`
+
+`verifyVercelOidcToken` checks the JWT against Vercel's JWKS and, by default, matches `project_id` and `environment` to `VERCEL_PROJECT_ID` and `VERCEL_ENV` on the deployment. Returning `true` tells the adapter the body is trusted; throwing or returning a falsy value yields a `401`. When you use `webhookVerifier`, the adapter doesn't run Slack's 5-minute timestamp check, since Connect is your freshness boundary.
+
+For more details, see the [OIDC API reference](https://vercel.com/docs/oidc/api) and [Connect triggers](https://vercel.com/docs/connect/concepts/triggers).
+
+### 6\. Create the agent and bot
+
+Create `lib/bot.ts` with a `ToolLoopAgent` and a `Chat` instance.
+
+Instead of reading a long-lived `SLACK_BOT_TOKEN`, the Slack adapter fetches a short-lived token with Vercel Connect:
+
+`import { Chat } from "chat"; import { toAiMessages } from "chat/ai"; import { createSlackAdapter } from "@chat-adapter/slack"; import { createRedisState } from "@chat-adapter/state-redis"; import { ToolLoopAgent } from "ai"; import { getToken } from "@vercel/connect"; import { tools } from "./tools"; import { verifySlackConnectWebhook } from "./slack-connect-webhook-verifier"; const agent = new ToolLoopAgent({ model: "anthropic/claude-opus-4.8", instructions: "You are a helpful AI assistant in a Slack workspace. " + "Answer questions clearly and use your tools when you need " + "real-time data. Keep responses concise and well-formatted for chat.", tools, }); export const bot = new Chat({ userName: "ai-agent", adapters: { slack: createSlackAdapter({ // Outbound: short-lived Slack token from Connect botToken: () => getToken("slack/acme-slack", { subject: { type: "app" } }), // Inbound: verify Connect-forwarded OIDC Bearer token webhookVerifier: verifySlackConnectWebhook, }), }, state: createRedisState(), }); // Handle first-time mentions bot.onNewMention(async (thread, message) => { await thread.subscribe(); const result = await agent.stream({ prompt: message.text }); await thread.post(result.fullStream); }); // Handle follow-up messages in subscribed threads bot.onSubscribedMessage(async (thread, message) => { const allMessages = []; for await (const msg of thread.allMessages) { allMessages.push(msg); } const history = await toAiMessages(allMessages); const result = await agent.stream({ messages: history }); await thread.post(result.fullStream); });`
+
+The `botToken` option accepts a function that returns a token, and the adapter calls it on each Slack API request. That makes it a natural fit for Vercel Connect's short-lived tokens, since `getToken` returns a fresh token for the connector's installation each time. Request the token with subject `app` so the agent acts as the application itself; the bot scopes you set on the connector determine what the token can do.
+
+Replace `slack/acme-slack` with your connector UID from the Connect dashboard or `vercel connect list`.
+
+Pass `webhookVerifier` whenever Slack events arrive via Connect triggers. Omit `signingSecret` and don't set `SLACK_SIGNING_SECRET`. If both are present, `webhookVerifier` wins, but leaving `SLACK_SIGNING_SECRET` unset avoids mixing direct-Slack and Connect modes.
+
+When someone tags the bot, `onNewMention` fires. The handler subscribes to the thread (to track future messages in that thread) and streams the agent's response.
+
+For follow-up messages, `onSubscribedMessage` retrieves the full thread history using `thread.allMessages`, converts it to the AI SDK message format with `toAiMessages`, and passes it to the agent so it has complete conversation context.
+
+Using `fullStream` is preferred over `textStream` because it preserves paragraph breaks between tool-calling steps. Chat SDK auto-detects the stream type and handles Slack's native streaming API for real-time updates.
+
+### 7\. Wire up the webhook route
+
+Create the API route at `app/api/webhooks/[platform]/route.ts`:
+
+``import { after } from "next/server"; import { bot } from "@/lib/bot"; type Platform = keyof typeof bot.webhooks; export async function POST( request: Request, context: RouteContext<"/api/webhooks/[platform]"> ) { const { platform } = await context.params; const handler = bot.webhooks[platform as Platform]; if (!handler) { return new Response(`Unknown platform: ${platform}`, { status: 404 }); } return handler(request, { waitUntil: (task) => after(() => task), }); }``
+
+This creates a `POST /api/webhooks/slack` endpoint. The `waitUntil` option ensures your event handlers finish processing after the HTTP response is sent, which is required on serverless platforms where the function would otherwise terminate early.
+
+With trigger forwarding enabled, Connect POSTs verified Slack payloads to this route. Verification happens in `webhookVerifier` before the adapter parses the body. The route itself stays unchanged. Only the adapter config gains `webhookVerifier`.
+
+### 8\. Test the agent
+
+Slack sends events to Connect, which forwards them to a deployed Vercel project rather than to your machine. You test the full round trip against a preview or development deployment, with no local tunnel to spin up. Your app rejects direct Slack POSTs unless you add a separate direct-webhook path with `SLACK_SIGNING_SECRET`.
+
+1.  Deploy a preview build to receive the Slack events:
+    
+
+`vercel`
+
+1.  In the [connector's settings](https://vercel.com/d?to=%2F%5Bteam%5D%2F~%2Fconnect?service=slack), make sure that deployment's environment is linked and registered as the trigger destination at `/api/webhooks/slack`.
+    
+2.  Invite the bot to a channel (`/invite @AI Agent`).
+    
+3.  Tag the bot and ask it, "What's the weather in San Francisco?". You should see a streaming response appear in the thread.
+    
+
+### 9\. Deploy to Production
+
+Once you've tested your agent, deploy it to production:
+
+`vercel --prod`
+
+Your Slack AI agent is now live and will respond to mentions in your workspace.
+
+## Troubleshooting
+
+### Bot doesn't respond to mentions
+
+Check that your Slack connector has trigger forwarding enabled and that your project is registered as a trigger destination with the correct path (`/api/webhooks/slack`). Confirm the connector is installed in your workspace and that its Trigger Event Types include the events your agent needs (`app_mention` and the relevant message events). You can review all of this in the connector's settings. Verify production/preview deployment logs on `/api/webhooks/slack` for 401s before debugging `getToken`.
+
+### Token requests fail or return unauthorized
+
+Make sure the project is linked (`vercel link`) and that the connector is linked to it for the current environment. Confirm the connector is installed in your workspace and that the bot scopes the agent uses are enabled on the connector. You can check the connector's link, environments, and scopes in its settings.
+
+### Webhook returns 401 / Invalid signature
+
+*   Confirm `webhookVerifier` is set and imports `verifyVercelOidcToken`.
+    
+*   Confirm OIDC Federation is enabled on the project.
+    
+*   Remove `SLACK_SIGNING_SECRET` from the project if set (can force the wrong verification path in some setups).
+    
+*   Confirm the request is coming from Connect (trigger destination configured), not from Slack hitting your app directly.
+    
+
+### Missing Authorization bearer token
+
+*   The event reached your app without Connect forwarding (wrong Events URL on the Slack side, or trigger destination not registered).
+    
+*   Fix the trigger path to `/api/webhooks/slack` and link the correct environment.
+    
+
+### Streaming appears choppy or delayed
+
+Chat SDK uses Slack's native streaming API for smooth updates. If you're seeing issues, check that your Redis connection is stable, as the SDK uses distributed locks to manage concurrent messages.
+
+### Tool calls fail silently
+
+If the agent calls a tool but no result appears, check for errors in your tool's `execute` function. AI SDK surfaces tool execution errors back to the model, which may attempt to recover. Add error handling in your tools and check your server logs for details.
+
+### Thread history grows too large
+
+For long-running threads, the conversation history can exceed the model's context window. Consider limiting the number of messages you pass to the agent by slicing the history array or by using a summarization step for older messages.
+
+## Related resources
+
+*   [Vercel Connect overview](https://vercel.com/docs/connect)
+    
+*   [Vercel Connect quickstart guide](https://vercel.com/docs/connect/quickstart)
+    
+*   [Chat SDK streaming](https://chat-sdk.dev/docs/streaming)
+    
+*   [Chat SDK actions](https://chat-sdk.dev/docs/actions) and [cards](https://chat-sdk.dev/docs/cards)
+    
+*   [AI SDK agent documentation](https://ai-sdk.dev/docs/agents/building-agents)
+    
+*   [AI Gateway documentation](https://vercel.com/docs/ai-gateway)
+
+---
+
+[View full KB sitemap](/kb/sitemap.md)

package/resources/guides/create-a-discord-support-bot-with-nuxt-and-redis.md

@@ -56,7 +56,7 @@ The `chat` package is the Chat SDK core. The `@chat-adapter/discord` and `@chat-
 
 Then set up the Interactions endpoint:
 
-1.  In **General Information**, set the **Interactions Endpoint URL** to [`https://your-domain.com/api/webhooks/discord`](https://your-domain.com/api/webhooks/discord)
+1.  In **General Information**, set the **Interactions Endpoint URL** to `https://your-domain.com/api/webhooks/discord`
     
 2.  Discord will send a PING to verify the endpoint. You'll need to deploy first or use a tunnel
     
@@ -128,7 +128,7 @@ The Gateway listener connects to Discord's WebSocket, receives messages, and for
     
 3.  Expose your server with a tunnel (e.g. `ngrok http 3000`)
     
-4.  Update the **Interactions Endpoint URL** in your Discord app settings to your tunnel URL (e.g. [`https://abc123.ngrok.io/api/webhooks/discord`](https://abc123.ngrok.io/api/webhooks/discord))
+4.  Update the **Interactions Endpoint URL** in your Discord app settings to your tunnel URL (e.g. `https://abc123.ngrok.io/api/webhooks/discord`)
     
 5.  @mention the bot in your Discord server. It should respond with a support card
     

package/resources/guides/daily-digest-bot-with-chat-sdk-and-workflow-sdk.md

@@ -0,0 +1,306 @@
+# Build a daily digest bot with Chat SDK and Workflow SDK
+
+**Author:** Anshuman Bhardwaj
+
+---
+
+Build a daily digest bot that gathers GitHub activity, summarizes it with a model, and posts to Slack on a schedule without running it inline in a cron handler, where a single slow source or a failing channel can take down the whole run. A cron route starts a single durable workflow that fans out a step per channel, so each fetches, summarizes, and posts on its own, and retries independently.
+
+This guide builds the bot with [Chat SDK](https://chat-sdk.dev) and [Workflow SDK](https://workflow-sdk.dev). Every credential is brokered at runtime: Slack and GitHub authenticate through [Vercel Connect](https://vercel.com/connect), and the model authenticates with your project's [OpenID Connect (OIDC) token](https://vercel.com/docs/oidc). There are no API keys or client secrets to set.
+
+Deploy the template now, or read on for a deeper look at how it all works.
+
+## Quick start with an AI coding agent
+
+If you are working with an AI coding agent, hand it the project and this prompt:
+
+### Vercel Plugin
+
+Turn your agent into a Vercel expert with this [plugin](https://vercel.com/docs/agent-resources/vercel-plugin). It gives your coding agent current knowledge of the Vercel products this template uses, including Vercel Connect, Vercel Workflows, Vercel Cron, AI Gateway, and Chat SDK. The plugin is optional; it is not required to use this template or for this guide.
+
+`npx plugins add vercel/vercel-plugin`
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+*   Node.js 20+
+    
+*   [pnpm](https://pnpm.io/) (or npm/yarn)
+    
+*   A Vercel team and project with Vercel Connect enabled, plus permission to create connectors and link them to projects
+    
+*   The [Vercel CLI](https://vercel.com/docs/cli) is installed
+    
+*   A Slack workspace where you can install apps
+    
+*   A GitHub account where you can install apps
+    
+
+## Create the project
+
+Create a new [Next.js](https://nextjs.org/docs) app with `create-next-app` :
+
+`pnpm create next-app@latest scheduled-digest-bot --yes cd scheduled-digest-bot`
+
+Then install the Chat SDK, Vercel Connect, and Workflow SDK packages:
+
+`pnpm add chat @chat-adapter/slack @chat-adapter/state-redis ai workflow @vercel/connect zod`
+
+Wrap your Next.js config in `withWorkflow`:
+
+`import { withWorkflow } from "workflow/next"; import type { NextConfig } from "next"; const nextConfig: NextConfig = { serverExternalPackages: [ "@chat-adapter/slack", "@chat-adapter/state-redis", "@redis/client", "@slack/socket-mode", "@slack/web-api", "redis", ], }; export default withWorkflow(nextConfig);`
+
+## Configure credentials
+
+Your agent uses Redis for thread subscriptions and distributed locking. Provision [Upstash Redis](https://vercel.com/marketplace/upstash) and connect it to your project with the Vercel CLI:
+
+`vercel link vercel integration add upstash`
+
+`vercel integration add` installs the Upstash integration if it isn’t already, provisions a database, connects it to your project, and pulls its connection environment variables into `.env.local`. Follow the prompts to pick the Redis product and a plan.
+
+Use the [Vercel CLI](https://vercel.com/docs/cli) to link the project and pull [environment variables](https://vercel.com/docs/environment-variables):
+
+`vercel env pull`
+
+AI SDK uses `VERCEL_OIDC_TOKEN` to authenticate with the Vercel AI Gateway with [OIDC authentication](https://vercel.com/docs/ai-gateway/authentication-and-byok/authentication#oidc-token).
+
+`VERCEL_OIDC_TOKEN=...`
+
+### Create and link the Slack connector
+
+Create the Slack connector in Vercel Connect before you wire the bot locally. Vercel Connect creates and manages the Slack app, so you do not need to create a Slack app at [`api.slack.com`](http://api.slack.com) or copy a long-lived Slack bot token.
+
+1.  Open the Connect page in your Vercel team dashboard.
+    
+2.  Choose **Create Connector**.
+    
+3.  Select **Slack** as the provider.
+    
+4.  Select the Slack workspace and name the connector, for example `digest-bot`.
+    
+5.  Keep triggers enabled if this project should receive Slack events.
+    
+6.  Keep the default scopes selected.
+    
+7.  Create the connector and install it in the Slack workspace.
+    
+8.  In the connector settings, link it to the Vercel project and select the environments where it should be available.
+    
+
+Copy the Slack connector id and store it in `.env.local` file as `CONNECTOR_SLACK`, for example:
+
+`CONNECTOR_SLACK=slack/digest-bot`
+
+Also, add the following environment variables:
+
+`CRON_SECRET="replace-with-a-long-random-string" # e.g. "openssl rand --base64 32" DIGEST_CHANNEL_ID="slack:SLACK_CHANNEL_ID"`
+
+### Create and link the GitHub connector
+
+Create the GitHub connector in Vercel Connect and install it on the repositories you want included in the digest.
+
+1.  Open the Connect page in your Vercel team dashboard.
+    
+2.  Choose **Create Connector**.
+    
+3.  Select **GitHub** as the provider.
+    
+4.  Select the GitHub account or organization to connect.
+    
+5.  Install the connector on all repositories the digest should read, or select a smaller repository allowlist.
+    
+6.  Create the connector.
+    
+7.  In the connector settings, link it to the Vercel project and select the environments where it should be available.
+    
+
+Copy the GitHub connector id and store it in `.env.local` file as `CONNECTOR_GITHUB`, for example:
+
+`CONNECTOR_GITHUB=github/digest-github`
+
+The digest requests an app-scoped token from Vercel Connect:
+
+`import { getToken } from "@vercel/connect"; export async function getGitHubToken() { const connector = process.env.CONNECTOR_GITHUB; if (!connector) { throw new Error("CONNECTOR_GITHUB is required."); } return getToken(connector, { subject: { type: "app" } }); }`
+
+The connector installation determines which repositories the token can access. If a repository is missing from the digest, check the connector installation and project/environment link before changing code.
+
+## Create the Chat SDK bot
+
+`lib/bot.ts` centralizes the Chat SDK instance. It requests short-lived Slack tokens from Vercel Connect and configures Redis state so proactive posts and webhook handling share the same bot.
+
+`import { createSlackAdapter } from "@chat-adapter/slack"; import { createRedisState } from "@chat-adapter/state-redis"; import { getToken } from "@vercel/connect"; import { Chat } from "chat"; let bot: Chat | null = null; function getSlackBotToken() { const connector = process.env.CONNECTOR_SLACK; if (!connector) { throw new Error( "CONNECTOR_SLACK is required. Use the Vercel Connect connector id, such as slack/acme-slack.", ); } return getToken(connector, { subject: { type: "app" } }); } function verifyConnectForwardedSlackRequest() { return true; } export function getBot() { if (!bot) { bot = new Chat({ userName: process.env.BOT_USER_NAME ?? "digest-bot", adapters: { slack: createSlackAdapter({ botToken: getSlackBotToken, webhookVerifier: verifyConnectForwardedSlackRequest, }), }, state: createRedisState(), dedupeTtlMs: 600_000, }).registerSingleton(); } return bot; }`
+
+## Define digest schemas and types
+
+`lib/digest/types.ts` keeps the workflow input, source contract, and model output schema in one place. The same schema validates the cron input and constrains the AI SDK response.
+
+`import { z } from "zod"; export const DigestConfigSchema = z.object({ tone: z.enum(["terse", "detailed"]).default("terse"), maxSections: z.number().int().positive().max(8).default(4), include: z .array(z.string()) .default(["github-repositories", "github-issues"]), }); export const DigestInputSchema = z.object({ channelId: z.string().min(1), lookbackHours: z.number().int().positive().max(168).default(24), detailsUrl: z.url().optional(), config: DigestConfigSchema.default({ tone: "terse", maxSections: 4, include: ["github-repositories", "github-issues"], }), }); export const DigestChannelIdSchema = z.string().min(1); export type DigestConfig = z.infer<typeof DigestConfigSchema>; export type DigestInput = z.infer<typeof DigestInputSchema>; export type GatherActivity = (input: DigestInput) => Promise<unknown>; export const DigestSchema = z.object({ headline: z.string().min(1), sections: z .array( z.object({ label: z.string().min(1), body: z.string().min(1), }), ) .min(1), }); export type Digest = z.infer<typeof DigestSchema>;`
+
+## Enroll the digest channel
+
+`lib/digest/enrollment.ts` turns the single `DIGEST_CHANNEL_ID` environment variable into the workflow input. Keep schedule-independent choices, like lookback window and tone, in code so the environment stays small.
+
+`import { DigestChannelIdSchema, type DigestConfig, type DigestInput, } from "./types"; const DIGEST_LOOKBACK_HOURS = 24; const DIGEST_DETAILS_URL = "https://vercel.com"; const DIGEST_CONFIG: DigestConfig = { tone: "terse", maxSections: 4, include: ["github-repositories", "github-issues"], }; export async function loadDigestChannel(): Promise<DigestInput | null> { const raw = process.env.DIGEST_CHANNEL_ID; if (!raw) { return null; } const channelId = DigestChannelIdSchema.parse(raw); return { channelId, lookbackHours: DIGEST_LOOKBACK_HOURS, detailsUrl: DIGEST_DETAILS_URL, config: DIGEST_CONFIG, }; }`
+
+## Start the workflow from cron
+
+Keep the cron route thin. It should verify the secret `CRON_SECRET`), load the single configured channel, start the workflow, and return the run id.
+
+``import { start } from "workflow/api"; import { loadDigestChannel } from "@/lib/digest/enrollment"; import { runDailyDigest } from "@/lib/digest/workflow"; export async function GET(request: Request) { const auth = request.headers.get("authorization"); if (!process.env.CRON_SECRET || auth !== `Bearer ${process.env.CRON_SECRET}`) { return new Response("Unauthorized", { status: 401 }); } const channel = await loadDigestChannel(); if (!channel) { return Response.json({ started: false, reason: "DIGEST_CHANNEL_ID is not set" }); } const run = await start(runDailyDigest, [channel]); return Response.json({ started: true, runId: run.runId }); }``
+
+### Scheduling the cron route
+
+`vercel.json` tells Vercel Cron to call the digest route every day. The route still checks `CRON_SECRET`, so only authorized cron requests can start a workflow.
+
+`{ "crons": [ { "path": "/api/cron/digest", "schedule": "0 8 * * *" } ] }`
+
+Add the `CRON_SECRET` environment variable to your Vercel project before deploying the application.
+
+## Create GitHub digest workflow
+
+Use one workflow to orchestrate the work, but keep expensive or failure-prone operations in separate steps. This makes the workflow retries and run inspection more useful.
+
+`import { fetchGitHubActivity, generateDigest, postDigest } from "./step"; import type { DigestInput } from "./types"; export async function runDailyDigest(channel: DigestInput) { "use workflow"; try { const activity = await fetchGitHubActivity(channel); const digest = await generateDigest(channel, activity); await postDigest(channel, digest); return { posted: 1, failed: 0, channelId: channel.channelId }; } catch (error) { return { posted: 0, failed: 1, channelId: channel.channelId, error: error instanceof Error ? error.message : String(error), }; } }`
+
+`import { generateText, Output } from "ai"; import { postDigestCard } from "./card"; import { buildPrompt } from "./prompt"; import { gatherProjectActivity } from "./sources"; import { DigestSchema, type Digest, type DigestInput } from "./types"; export async function fetchGitHubActivity(input: DigestInput) { "use step"; return gatherProjectActivity(input); } export async function generateDigest(input: DigestInput, activity: unknown) { "use step"; const { output } = await generateText({ model: process.env.DIGEST_MODEL ?? "anthropic/claude-haiku-4.5", output: Output.object({ schema: DigestSchema, name: "daily_digest", description: "A concise channel digest with headline and sections.", }), prompt: buildPrompt(activity, input.config), }); return output; } export async function postDigest(input: DigestInput, digest: Digest) { "use step"; return postDigestCard(input, digest); }`
+
+### Fetch GitHub issues with Search API
+
+`lib/digest/sources.ts` owns the GitHub data contract. It gets a token from Vercel Connect, discovers connector-visible repositories, counts open issues, and returns a precomputed activity payload for the model.
+
+Use the REST repository endpoints to discover connector-visible repositories. Then use batched GitHub GraphQL queries for issue counts and recent issue nodes.
+
+> Avoid the GitHub Search API for per-repository issue counts. Its quota is much lower, and a scheduled digest can exhaust it quickly when it searches once per repository.
+
+Here’s the API request flow:
+
+*   Fetch up to a bounded number of active repositories.
+    
+*   Count public and private repositories in code.
+    
+*   Query GraphQL in batches for `issues(states: OPEN) { totalCount }`.
+    
+*   Fetch recent issue nodes only for the repositories shown in the digest. Keep recent issue nodes capped, for example 10 per repository.
+    
+
+The digest payload should give the model precomputed totals, not ask it to infer them. Build the payload in a complete helper function:
+
+`type RepositorySummary = { name: string; visibility: "public" | "private"; }; type RecentIssue = { repository: string; title: string; url: string; createdAt: string; }; type IssueReport = { repository: RepositorySummary; openIssueCount: number; recentlyOpenedIssues: RecentIssue[]; }; function buildDigestActivity( repositories: RepositorySummary[], issueReports: IssueReport[], maxProcessed: number, ) { const publicRepositories = repositories.filter( (repository) => repository.visibility === "public", ); const privateRepositories = repositories.filter( (repository) => repository.visibility === "private", ); const recentlyOpened = issueReports .flatMap((report) => report.recentlyOpenedIssues) .sort((left, right) => right.createdAt.localeCompare(left.createdAt)); const openInPublicRepositories = sumOpenIssues(issueReports, "public"); const openInPrivateRepositories = sumOpenIssues(issueReports, "private"); return { repositories: { total: repositories.length, public: publicRepositories.length, private: privateRepositories.length, processed: Math.min(repositories.length, maxProcessed), maxProcessed, }, issues: { totalOpen: openInPublicRepositories + openInPrivateRepositories, openInPublicRepositories, openInPrivateRepositories, recentlyOpenedInLookback: recentlyOpened.length, recentlyOpened, byRepository: issueReports.map((report) => ({ repository: report.repository.name, visibility: report.repository.visibility, openIssueCount: report.openIssueCount, recentlyOpenedInLookback: report.recentlyOpenedIssues.length, })), }, }; } function sumOpenIssues( issueReports: IssueReport[], visibility: RepositorySummary["visibility"], ) { return issueReports .filter((report) => report.repository.visibility === visibility) .reduce((sum, report) => sum + report.openIssueCount, 0); }`
+
+This keeps the prompt focused on writing the digest rather than doing arithmetic over raw issue lists. It also makes the posted summary easier to verify when you inspect a workflow run.
+
+The source file should also throw `RetryableError` for transient GitHub failures and `FatalError` for bad configuration, so workflow retries only the failures that can recover.
+
+### Build the digest prompt
+
+`lib/digest/prompt.ts` turns the structured GitHub activity into model instructions. Keep totals and source data in the activity object, then use the prompt only to control tone and output priorities.
+
+``import type { DigestConfig } from "./types"; export function buildPrompt(activity: unknown, config: DigestConfig) { return [ `Write a ${config.tone} daily GitHub issues digest.`, `Return at most ${config.maxSections} sections.`, `Only include these source areas: ${config.include.join(", ")}.`, "Include the total number of public repositories and private repositories.", "Include the total number of open issues in public repositories and private repositories.", "If repository totals may be limited by the fetch cap, call that out briefly.", "Highlight newly opened issues, affected repositories, owners, labels, and notable themes.", "If there are no recently opened issues, still summarize the repository and open issue totals.", "Use clear labels and concise bodies.", "Return a headline and sections that match the requested schema.", JSON.stringify(activity, null, 2), ].join("\n\n"); }``
+
+## Post a Chat SDK Card
+
+Create the Slack message card in the `lib/digest/card.tsx` :
+
+``import { Actions, Card, CardText, LinkButton, Section } from "chat"; import { getBot } from "@/lib/bot"; import type { Digest, DigestInput } from "./types"; export async function postDigestCard(input: DigestInput, digest: Digest) { const channel = getBot().channel(input.channelId); await channel.post( Card({ title: digest.headline, children: [ ...digest.sections.map((section) => Section([CardText(`**${section.label}** ${section.body}`)]), ), Actions([ LinkButton({ url: input.detailsUrl ?? "https://vercel.com", label: "View details", }), ]), ], }), ); return { posted: true as const, channelId: input.channelId }; }``
+
+## Run the application locally
+
+To trigger the cron route, start the app:
+
+`pnpm dev`
+
+In another terminal, run the following curl command to trigger the cron job:
+
+`curl -H "Authorization: Bearer $CRON_SECRET" \ http://localhost:3000/api/cron/digest`
+
+To inspect workflow runs include the steps timeline and retries during development, run the following command:
+
+`pnpm exec workflow web`
+
+You now have a daily digest bot with Chat SDK, Workflow SDK, and Vercel Connect. These primitives are extensible for more comprehensible use cases like a PR review bot or an incident watchlist to help you navigate public reports on GitHub.
+
+## Troubleshooting
+
+Each item below lists a symptom, its cause, and the fix.
+
+### The cron route returns unauthorized
+
+Make sure `CRON_SECRET` is set in the environment where the cron job runs, such as production. Vercel Cron sends `Authorization: Bearer $CRON_SECRET`, and the route fails closed when the variable is missing or the header does not match.
+
+Symptom: A Vercel Cron run or manual request gets `401 Unauthorized`.
+
+Cause: `CRON_SECRET` is missing from the environment where the route runs, or the request does not include `Authorization: Bearer $CRON_SECRET`.
+
+Fix: Set `CRON_SECRET` in production and any preview environment where the cron route should run. For local tests, pull the environment with `vercel env pull` or set the variable in the shell before calling the route.
+
+### The Slack digest does not post
+
+Symptom: The workflow runs, but no message appears in Slack.
+
+Cause: The Slack app is not in the configured channel, `DIGEST_CHANNEL_ID` is not in Chat SDK channel id format, or `CONNECTOR_SLACK` is missing from the environment.
+
+Fix: Invite the Slack app to the channel, set `DIGEST_CHANNEL_ID` to a value such as `slack:C123ABC`, and confirm the Slack connector is linked to the Vercel project environment.
+
+### GitHub repositories are missing
+
+Symptom: The digest includes fewer repositories than expected.
+
+Cause: The GitHub connector is installed on a limited repository allowlist, or the connector is not linked to the environment running the workflow.
+
+Fix: Update the GitHub connector installation to include the repositories you want, then confirm `CONNECTOR_GITHUB` is available in the same Vercel environment as the workflow.
+
+### GitHub API rate limit reached
+
+Check that issue counts use GraphQL batching, not GitHub Search API calls. Search API limits are easier to hit and should not be used once per repository.
+
+Symptom: The `fetchGitHubActivity` step fails with a rate limit error.
+
+Cause: GitHub rate limits can still apply to connector tokens, especially if the workflow queries too many repositories or uses the Search API for counts.
+
+Fix: Keep repository fetching bounded, use GraphQL batching for issue counts, and avoid per-repository GitHub Search API calls. The template marks rate limits as `RetryableError` so workflow can retry after a delay.
+
+### Slack signing secret error
+
+When Slack events are routed through Vercel Connect, Connect verifies the event before forwarding it. The Slack adapter still expects a `webhookVerifier`, so provide one that delegates trust to Connect for that route. If you receive events directly from Slack, use Slack's signing secret instead.
+
+Symptom: The Slack webhook route fails with a signing secret error.
+
+Cause: The Slack adapter requires a webhook verifier, but Vercel Connect has already verified Connect-forwarded Slack events before they reach the app.
+
+Fix: For Connect-forwarded Slack events, use a verifier that delegates trust to Connect for that route. If events come directly from Slack, configure verification with Slack's signing secret instead.
+
+### Invalid JSX element: must be a Card element
+
+Use the Chat SDK function-call Card API in workflow steps instead of JSX if the generated workflow route does not recognize the JSX Card shape at runtime.
+
+Symptom: The Slack post step fails with `Invalid JSX element: must be a Card element`.
+
+Cause: The workflow route may not recognize a JSX Card shape at runtime.
+
+Fix: Use the Chat SDK function-call Card API in `lib/digest/card.tsx`, as shown above.
+
+### Local Connect token requests fail
+
+Symptom: GitHub or Slack token requests work in production but fail locally.
+
+Cause: The local `VERCEL_OIDC_TOKEN` written by `vercel env pull` has expired, or the local project is linked to the wrong Vercel project.
+
+Fix: Run `vercel link` to confirm the project, then run `vercel env pull` again.
+
+## Related resources
+
+*   [Workflow SDK documentation](https://workflow-sdk.dev)
+    
+*   [Chat SDK cards](https://chat-sdk.dev/docs/cards)
+    
+
+*   [Vercel Connect](https://vercel.com/docs/connect) and [Vercel Connect CLI](https://vercel.com/docs/cli/connect)
+    
+*   [Vercel AI Gateway](https://vercel.com/docs/ai-gateway)
+    
+*   [Vercel OIDC](https://vercel.com/docs/oidc)
+
+---
+
+[View full KB sitemap](/kb/sitemap.md)

package/resources/guides/how-to-build-a-slack-bot-with-next-js-and-redis.md

@@ -45,7 +45,7 @@ Select your workspace and paste the following manifest:
 
 `display_information: name: My Bot description: A bot built with Chat SDK features: bot_user: display_name: My Bot always_online: true oauth_config: scopes: bot: - app_mentions:read - channels:history - channels:read - chat:write - groups:history - groups:read - im:history - im:read - mpim:history - mpim:read - reactions:read - reactions:write - users:read settings: event_subscriptions: request_url: https://your-domain.com/api/webhooks/slack bot_events: - app_mention - message.channels - message.groups - message.im - message.mpim interactivity: is_enabled: true request_url: https://your-domain.com/api/webhooks/slack org_deploy_enabled: false socket_mode_enabled: false token_rotation_enabled: false`
 
-Replace [`https://your-domain.com/api/webhooks/slack`](https://your-domain.com/api/webhooks/slack) with your deployed webhook URL, then click **Create**.
+Replace `https://your-domain.com/api/webhooks/slack` with your deployed webhook URL, then click **Create**.
 
 After creating the app:
 

package/resources/guides/liveblocks-chat-sdk-ai-sdk.md

@@ -43,8 +43,6 @@ Before continuing, make sure you have a React app with Liveblocks Comments up an
 
 Install the Liveblocks adapter, Chat SDK, AI SDK, and other related packages:
 
-`npm install @liveblocks/chat-sdk-adapter @liveblocks/node chat @chat-adapter/state-redis ai zod`
-
 The `chat` package is the Chat SDK core. `@liveblocks/chat-sdk-adapter` is the Liveblocks platform adapter. `ai` is the AI SDK, which includes `ToolLoopAgent`. `zod` is used to define tool input schemas. `@chat-adapter/state-redis` is the [Redis state adapter,](https://chat-sdk.dev/adapters/official/redis) which handles thread subscriptions and distributed locking.
 
 ### 3\. Create a Liveblocks project

package/resources/guides/ship-a-github-code-review-bot-with-hono-and-redis.md

@@ -45,7 +45,7 @@ The `chat` package is the Chat SDK core. The `@chat-adapter/github` and `@chat-a
 
 1.  Go to your repository **Settings**, then **Webhooks**, then **Add webhook**
     
-2.  Set **Payload URL** to [`https://your-domain.com/api/webhooks/github`](https://your-domain.com/api/webhooks/github)
+2.  Set **Payload URL** to `https://your-domain.com/api/webhooks/github`
     
 3.  Set **Content type** to `application/json`