Bots and agents

There is no bot API. A bot is a user with a token, and it uses the same REST and WebSocket endpoints a person’s browser does. That is the whole design: if the app can do it, an agent can do it.

Creating one

Workspace settings, then Bots. You get a slk_ token, shown once.

curl -X POST http://localhost:3000/api/workspaces/$WS/bots \
  -H "authorization: Bearer $YOUR_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"name":"deploy-bot"}'
# => { "token": "slk_..." }

Using it

The token goes in Authorization: Bearer on REST calls, and in the hello frame on the WebSocket.

# join a channel
curl -X POST http://localhost:3000/api/channels/$CHANNEL/join \
  -H "authorization: Bearer slk_..."

# post
curl -X POST http://localhost:3000/api/channels/$CHANNEL/messages \
  -H "authorization: Bearer slk_..." \
  -H 'content-type: application/json' \
  -d '{"id":"'$(ulid)'","content":"deploy finished"}'

Note the client-supplied id. Messages carry a ULID minted by the sender, which doubles as an idempotency key: retrying a send after a flaky network cannot produce a duplicate.

With the SDK

@slick/sdk is a typed client for both REST and the WebSocket.

import { SlickClient } from "@slick/sdk";

const client = new SlickClient({
  url: process.env.SLICK_URL!,
  token: process.env.SLICK_TOKEN!,
});

await client.connect();
client.on("message.created", async (message) => {
  if (message.content.includes("ping")) {
    await client.sendMessage(message.channelId, "pong");
  }
});

packages/sdk/examples/echo-bot.ts is the smallest complete version of this.

Adding a bot to channels

An admin can add a bot to any public channel from the Bots tab, without joining it themselves. For private channels, a member adds the bot the same way they would add a person.

Encrypted channels

A bot is another device with no channel key, so it cannot read an encrypted channel. It will say so rather than sitting silent. Giving bots a device identity and sealing them channel keys is a deliberate design decision, not an oversight: it widens who can read plaintext, and that should be a choice someone makes on purpose.