velt-chat-sdk-adapter-best-practices

Create a lazy singleton Chat instance with createVeltAdapter, register an onNewMention handler that calls thread.subscribe() and thread.post(), and expose a POST webhook route. Enable comment.add and comment_annotation.add events in the Velt Console.

Use v2 (Advanced), which is the adapter default. It verifies requests with Svix-style HMAC-SHA256 signatures and rejects events older than 5 minutes, while v1 only checks a Basic Authorization token with no replay protection.

Verification fails on the Edge runtime because it requires Node's crypto module. Set export const runtime = "nodejs" and export const dynamic = "force-dynamic" on the route, and confirm VELT_WEBHOOK_SECRET matches the Velt Console value.

Reading reactions via onReaction works on all managed plans, but writing reactions with addReaction or removeReaction throws a PermissionError on the managed backend. Programmatic reaction writes require configuring selfHostingConfig.reactionsService with a self-hosted data backend.

Feedback loops occur when botUserId does not match the user ID on the bot's posted replies. The adapter filters webhook events whose actionUser.userId equals botUserId, so keep that ID unique and stable across deployments.

Replace createMemoryState() with createRedisState() from @chat-adapter/state-redis. In-memory state loses thread subscriptions on restart, so onSubscribedMessage stops firing for previously subscribed threads.