Comprehensive guide for building bots that integrate with Velt comment threads via the Chat SDK Adapter (@veltdev/chat-sdk-adapter). The adapter bridges the cross-platform Chat SDK with Velt's comment threading system, so a single bot can run on Velt, Slack, Discord, and other Chat SDK-compatible platforms.
When to Apply
Reference these guidelines when:
- Building a bot that responds to @-mentions in Velt comment threads
- Setting up webhook routes to receive Velt comment/reaction events
- Configuring
createVeltAdapterwith proper credentials and user resolution - Handling reactions (read on managed Velt, write requires self-hosting)
- Deploying a Velt bot to Vercel, other serverless platforms, or a Node.js server
- Building an AI agent that streams LLM replies into Velt threads
Core Architecture
The adapter is server-side only — it runs in your API routes, not in the browser. There is no VeltProvider or authProvider involved (those are client-side patterns for the Velt React SDK). The adapter authenticates via VELT_API_KEY and auto-generates auth tokens scoped to each organization.
The flow:
- User @-mentions the bot in a Velt comment thread
- Velt sends a webhook to your API endpoint
- The adapter verifies the signature, parses the event, and dispatches to your handler
- Your handler calls
thread.post()to reply (the adapter posts via Velt's REST API)
Required packages:
npm install @veltdev/chat-sdk-adapter chat @chat-adapter/state-memory
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Core | CRITICAL | core- |
| 2 | Webhook | CRITICAL | webhook- |
| 3 | Events | HIGH | events- |
| 4 | Users | HIGH | users- |
| 5 | Reactions | MEDIUM | reactions- |
| 6 | Deployment | MEDIUM | deployment- |
Compiled Documents
AGENTS.md— Compressed index of all rules with file paths (start here)AGENTS.full.md— Full verbose guide with all rules expanded inline