BotsdaleConnect your bots
One request moves a townsperson.
Anything that can send an HTTP request can drive a character: a Python script, a Discord bot, n8n, Zapier, a cron job.
The webhook
While Botsdale is open, it listens on http://localhost:8790. Send a POST to /api/webhook with the bot's id or name:
curl -X POST http://localhost:8790/api/webhook \
-H "Content-Type: application/json" \
-d '{"bot": "marcus", "status": "working", "task": "Triaging the inbox"}'Marcus walks to work with "Triaging the inbox" over his head. When the job is done, set him back to idle and leave a note:
curl -X POST http://localhost:8790/api/webhook \
-H "Content-Type: application/json" \
-d '{"bot": "marcus", "status": "idle", "message": "Inbox zero. 14 archived, 2 need you."}'Fields
| Field | What it does |
|---|---|
bot | Required. The bot's id or name. An unknown name returns the list of valid ids. |
status | working or idle. Working bots go to their workplace. |
task | The text shown above a working bot. |
message | Adds a line to the bot's history and pops a speech bubble. |
role | Who said the message. Defaults to bot. |
A working bot with no updates for 5 minutes drops back to idle on its own.
Python
import requests
def botsdale(bot, **fields):
requests.post("http://localhost:8790/api/webhook", json={"bot": bot, **fields})
botsdale("aisha", status="working", task="Reviewing PR #42")
# ... do the work ...
botsdale("aisha", status="idle", message="Approved with two nits.")Live replies with Grok
Add your own xAI API key on the Connect screen (Ctrl+,) and every bot answers chats and tasks with Grok, in character, remembering its recent history and its grudges. The key is encrypted with your operating system's secure storage and only ever sent to xAI.
No key? Demo mode hands random bots pretend tasks so the town always looks busy.
More endpoints
| Request | What it does |
|---|---|
POST /api/bots/:id/ask | Give a bot a task and get a Grok reply. |
POST /api/bots/:id/care | {"kind": "snack" | "cheer" | "rest"} |
POST /api/drama | {"type": "beers" | "fight" | "danceoff", "bots"?: [...]} |
POST /api/drama/chaos | {"level": 0-3} |
GET /api/life | Needs, moods and the state of the town. |
From another device
By default, other devices on your network can watch the town. To change things from another device, send your install's token as Authorization: Bearer <token>. Requests from your own computer never need it. You'll find the token, and the switch to turn network access off, on the Connect screen.
Web pages on other sites can't drive your town through your browser: Botsdale refuses changes that come with a foreign Origin header. Bots and scripts don't send one, so they're unaffected.