Build self-hosted bots for Verdant.

Install

The SDK is published as @verdant/bot. Use it from a small process that you own: local Node, Bun, a VPS, a worker, or any host that can make HTTPS requests.

npm install @verdant/bot
# or
bun add @verdant/bot
# or
pnpm add @verdant/bot

Create a bot inside Verdant, mint a bot token, scope it to the server/feed/channel it needs, then pass the token through an environment variable.

Quickstart

This posts one feed announcement. The card uses format() so dynamic values are escaped, while selected variables can still be styled.

import { VerdantBot, card, channel, format } from "@verdant/bot";

const bot = new VerdantBot({
  token: process.env.VERDANT_BOT_TOKEN!,
});

const release = {
  version: "0.0.252",
  title: "Desktop updater polish",
};

await bot.feeds.postAnnouncement(
  process.env.VERDANT_FEED_ID!,
  card()
    .title(format("Client {version} released", release, {
      version: { color: "success", weight: "bold" },
    }))
    .description(format("{title} is live.", release, {
      title: { color: "info" },
    }))
    .accent("success")
    .button("Discuss release", channel(process.env.VERDANT_CHANNEL_ID!)),
  { idempotencyKey: `release-${release.version}` },
);

Examples

Webhook variables

Webhook payloads are just data. Pull out the fields you want, then map them into the builder. Keep static copy readable and pass dynamic values through format().

import { card, format } from "@verdant/bot";

export function releaseCard(payload: GitHubReleasePayload) {
  const values = {
    version: payload.release.tag_name,
    name: payload.release.name,
    author: payload.release.author.login,
    sha: payload.release.target_commitish.slice(0, 8),
  };

  return card()
    .title(format("Client {version} released", values, {
      version: { color: "success", weight: "bold" },
    }))
    .description(format("{name} by {author}", values, {
      name: { color: "info" },
      author: { color: "muted" },
    }))
    .accent("success")
    .table({
      columns: ["Field", "Value"],
      rows: [
        ["Version", format("{version}", values, { version: { color: "success", weight: "bold" } })],
        ["Commit", format("{sha}", values, { sha: { color: "info" } })],
        ["Author", format("{author}", values, { author: { color: "muted" } })],
      ],
    });

Channel cards

Feed announcements are good for long-lived posts. Text-channel cards are better for discussion, rankings, status updates, and short automation notices.

await bot.channels.postCard(
  process.env.VERDANT_CHANNEL_ID!,
  card()
    .title("Weekly ranking", { color: "purple", weight: "bold" })
    .accent("purple")
    .ranking("Top contributors", [
      { label: "Josh", value: 1280, detail: "12 commits" },
      { label: "Release Bot", value: 940, detail: "6 automations" },
    ]),
  { idempotencyKey: "rankings-week-2026-18" },
);

Images

Upload images through Verdant first, then place the returned CDN URL in the card.

const image = await bot.uploads.image(
  await Bun.file("release-badge.png").arrayBuffer(),
  { filename: "release-badge.png", contentType: "image/png" },
);

await bot.feeds.postAnnouncement(
  process.env.VERDANT_FEED_ID!,
  card()
    .title("Release badge")
    .image(image.url, "Release badge")
    .text("The image is served from Verdant's CDN."),
);

Gateway

Simple scheduled bots can use REST only. Connect to the bot gateway when your bot needs to appear online or react to events it is allowed to receive.

const ws = new WebSocket("wss://api.verdant.chat/bot-gateway");

ws.onopen = () => {
  ws.send(JSON.stringify({
    op: "IDENTIFY",
    d: {
      token: process.env.VERDANT_BOT_TOKEN,
      intents: ["FEEDS", "MESSAGES"],
      serverIds: [process.env.VERDANT_SERVER_ID],
    },
  }));
};

ws.onmessage = (event) => {
  const frame = JSON.parse(event.data);
  if (frame.op === "READY") console.log("bot online");
  if (frame.op === "DISPATCH") console.log(frame.t, frame.d);
};

setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ op: "PING", d: {} }));
  }
}, 25_000);

Component Reference

Helpers

Styles

card()
  .accent("success")
  .title("Release passed", { color: "success" })
  .text("Custom brand color", { color: "#7c3aed" });

Publishing your bot

1. Create a bot in Verdant and keep its token in a secret store.
2. Run your bot process anywhere that can reach https://api.verdant.chat.
3. Use REST for posting cards and the gateway only when your bot needs live events.
4. Use idempotency keys for webhooks, scheduled posts, and retryable jobs.