Sblurp

Bot tokens

A bot token lets a program act as a bot member. The program can run anywhere and be written in any language.

Make a bot

  1. Open Community settings, then Bots.
  2. Enter a username, a display name and an optional bio.
  3. Make the bot. Copy the token now. It is shown once; the server keeps only a hash.

Usernames are 2 to 32 of a-z, 0-9, _, . and -. Only admins and the owner can make bots.

Tokens start with sbb_. If a token leaks, click New token on the same tab. The old token stops working at once.

Call the API

Send the token as a Bearer token on every call:

curl https://chat.example.com/sblurp.v1.ChatService/SendMessage \
  -H 'Authorization: Bearer sbb_...' \
  -H 'Content-Type: application/json' \
  -d '{"channelId": "CHANNEL_ID", "text": "Hello from a bot"}'

Get channel ids from GetState. Every call is in the API reference.

Listen for messages

A bot that answers needs the live event stream:

  1. Call ServerService.GetState. Keep me.id and seq.
  2. Call ServerService.Subscribe with afterSeq set to that seq.
  3. For each event, keep its seq if it is not 0.
  4. On messageCreated, check the text. A mention of the bot is <@BOT_ID>.
  5. Reply with ChatService.SendMessage. Pass the message's threadRootId to reply in its thread.
  6. If the stream ends, subscribe again with the last seq. On resync, go back to step 1.

Skip messages the bot wrote itself.

The example bot

The server repository has a bot of about 150 lines in Go: server/cmd/example-bot. Mention it with help, roll d20, roll 2d6 or time. Copy it to start your own.

cd server
SBLURP_BOT_TOKEN=sbb_... go run ./cmd/example-bot -url https://chat.example.com

Or pass -token-file with a file that holds the token.

Rate limits

The server may limit bots with -bot-rate (messages per second) and -bot-burst. By default bots have no limit. A bot that sends too fast gets resource_exhausted.

Remove a bot

Delete it on the Bots tab. Its token stops working and it leaves the member list. Its old messages stay, and its username becomes free again.

View this page as Markdown · Glossary · API schema.json · openapi.json