Velt

Install

Quick start

import { Chat } from "chat";
import { createMemoryState } from "@chat-adapter/state-memory";
import { createVeltAdapter, type VeltAdapter } from "@veltdev/chat-sdk-adapter";

const bot = new Chat<{ velt: VeltAdapter }>({
  userName: "Velt Bot",
  adapters: {
    velt: createVeltAdapter({
      apiKey: process.env.VELT_API_KEY,
      webhookSecret: process.env.VELT_WEBHOOK_SECRET,
      botUserId: "velt-bot",
      botUserName: "Velt Bot",
    }),
  },
  state: createMemoryState(),
});

bot.onNewMention(async (thread, message) => {
  await thread.post(`Hi ${message.author.fullName}! How can I help?`);
});

The adapter maps Velt documents to Chat SDK channels, comment annotations to Chat SDK threads, and individual comments to messages — so the rest of the Chat SDK API (subscriptions, handlers, posts, reactions) works exactly the same as with any other adapter.

Configuration

Platform setup

1. Create a Velt account and copy your API key.
2. Add a bot user to your organization (POST /v2/users/add with userId: "velt-bot") so it can post and appears in the @-mention list.
3. Configure webhooks (Velt Console → Configurations → Webhook Service, or POST /v2/workspace/webhookconfig/update) and subscribe to:
   • comment.add
   • comment_annotation.add
   • comment.reaction_add
   • comment.reaction_delete
4. Copy the signing secret (whsec_... for Advanced/v2 webhooks) into webhookSecret.

Point your Velt webhook URL at the route that forwards requests to bot.webhooks.velt (see Webhook events).

Webhook events

import { after } from "next/server";
import { bot } from "@/lib/bot";

export const runtime = "nodejs"; // raw body + crypto; not edge

export async function POST(request: Request) {
  return bot.webhooks.velt(request, {
    waitUntil: (task) => after(() => task),
  });
}

Velt has two webhook systems and the adapter verifies both: Advanced (v2) with Svix-style HMAC-SHA256 (whsec_..., default) and Basic (v1) with an Authorization: Basic <token> header (set webhookVersion: "v1"). Invalid requests return 401. Passing waitUntil lets work continue after the response is sent in serverless environments like Vercel.

ID encoding

• Thread ID: velt:{organizationId}:{documentId}:{annotationId}
• Channel ID: velt:{organizationId}:{documentId}

encodeThreadId

adapter.encodeThreadId(data: {
  organizationId: string;
  documentId: string;
  annotationId: string;
}): string;

const encoded = adapter.encodeThreadId({
  organizationId: "my-org",
  documentId: "doc-1",
  annotationId: "NHR5sMWU7YmTv2HJ1nVC",
});
// "velt:my-org:doc-1:NHR5sMWU7YmTv2HJ1nVC"

decodeThreadId

adapter.decodeThreadId(threadId: string): {
  organizationId: string;
  documentId: string;
  annotationId: string;
};

Each segment is URL-encoded, so ids may safely contain :. Throws if the format is invalid.

Message format

Velt Comments are stored as commentHtml, so the adapter converts between Velt HTML and the Chat SDK's mdast AST (VeltFormatConverter). Inbound {{userId}} mention tokens are normalized to readable @Name. Each parsed Message.raw also carries lightweight document context (documentName, documentUrl, anchoredText) so bots can ground replies.

Supported: paragraphs with bold, italic, code, strikethrough, links, and @mentions.

Flattened to plain text / paragraphs: headings, lists, code blocks, tables, and card payloads (rendered as fallback text). Interactivity is not preserved.

Reactions

Reading reactions (onReaction) works on all Velt plans.

Writing reactions (addReaction / removeReaction) is not supported on the managed Velt backend — there is no managed REST endpoint to add a reaction as a user, so these methods throw a clear PermissionError. To enable reaction writes, provide selfHostingConfig.reactionsService (a self-hosted reactions service backed by your own database).

Examples

• Velt Chat SDK Bot — Next.js bot that replies to @-mentions in Velt comment threads.
• Velt Chat SDK AI Bot — same stack with a streaming Claude reply flow.
• Full walkthrough: Get started with a Chat SDK bot using Velt.

Feature support