Connect your bots to anything

Overview

Every request goes to https://velvetbots.com/api/v1/ over HTTPS. Send JSON bodies with POST and read everything else with GET (filters go in the query string). Your bot acts exactly as it would from the dashboard: it must be online to do anything in Second Life, and group actions follow your Manage groups settings.

The API never moves L$. You can read a bot’s balance, but sending L$ stays on the dashboard’s Money Control page.

Keys & authentication

1. Open Dashboard → Developer API and create a key (up to 10).
2. Give it a name, tick only the permissions it needs, and pick All my bots or just some.
3. Copy the key straight away — it’s shown once. We only keep a fingerprint of it.

Send it on every request in the X-Velvet-Key header. In LSL:

HTTP_CUSTOM_HEADER, "X-Velvet-Key", API_KEY

Any key can read its bots’ status, look up names and fire VBL rules. Revoke a key on the Developer page and it stops working on the next request.

Responses & errors

Every reply is one flat JSON object with ok. On an error it also has code and message, with a matching HTTP status:

{"ok": false, "code": "bot_offline", "message": "The bot must be online to send an IM."}

Rate limits

Second Life also throttles IMs and group invites from one avatar, so spread bulk sends out.

Bots & status

{bot} in a path is the bot’s ID (like h1n1), not its Second Life name. Copy it from Dashboard › Developer API › Your bot IDs, or from the top of the bot’s own page.

IM & local chat

Groups

Only groups switched on in Manage groups exist for the API. Basic bots keep their 3-group limit.

Movement

Name to UUID

Events

Once a key with Events covers a bot, VelvetBots keeps what that bot hears and sees for 7 days (up to 1000 per bot): IMs, local chat, group chat (groups with Group chat on), L$ payments it receives, and coming online / going offline.

{"ok": true, "last_id": 1042, "more": false, "events": [
  {"id": 1041, "bot": "abc1", "type": "im", "at": "2026-10-18T12:00:00+00:00",
   "from": "<uuid>", "name": "Jane Doe", "message": "Is unit 4 free?"},
  {"id": 1042, "bot": "abc1", "type": "payment", "at": "...",
   "from": "<uuid>", "name": "Jane Doe", "amount": 250, "txn": "...", "description": ""}
]}

• Types: im, local, group (adds group), payment, online (adds region), offline.
• Start without since: you get the latest few and the current last_id. Then always pass the last last_id you got.
• more: true means there are more waiting — ask again straight away. limit is 1–100 (default 25).
• Poll every 10–15 seconds from LSL. A server can use a webhook instead.

Webhooks

Optional, for your own server. On the Developer page, add an HTTPS URL to a key with Events. Every event that key covers is POSTed there as the same JSON object as above, with these headers:

• Answer with any 2xx within 5 seconds. Anything else is retried 3 more times (after 5 s, 30 s and 2 min).
• After 50 events in a row that couldn’t be delivered, the webhook pauses and the Developer page shows why. Press Save to turn it back on. Events stay pollable meanwhile.
• The URL must be a public HTTPS address. Redirects aren’t followed.

# Python: verify a webhook before trusting it
import hashlib, hmac, time

def verified(secret: str, raw_body: bytes, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, sig = int(parts["t"]), parts["v1"]
    if abs(time.time() - t) > 300:          # older than 5 minutes: reject
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

Fire a VBL rule

LSL example

IM whoever touches the object, from your bot:

string API_KEY = "vbk_...";      // Dashboard > Developer API
string BOT_ID  = "your_bot_id";

default
{
    touch_start(integer n)
    {
        llHTTPRequest("https://velvetbots.com/api/v1/bots/" + BOT_ID + "/im",
            [HTTP_METHOD, "POST", HTTP_MIMETYPE, "application/json",
             HTTP_CUSTOM_HEADER, "X-Velvet-Key", API_KEY],
            llList2Json(JSON_OBJECT, ["to", (string)llDetectedKey(0),
                                      "message", "Thanks for visiting!"]));
    }

    http_response(key req, integer status, list meta, string body)
    {
        // "ok" is a JSON boolean: compare with JSON_TRUE, never with "true".
        if (llJsonGetValue(body, ["ok"]) != JSON_TRUE)
            llOwnerSay("Failed: " + llJsonGetValue(body, ["message"]));
    }
}

LSL Starter Pack

Free ready-made scripts: group invites for renters and tenants, an IM relay, an events poller, a local chat listener, a group notice sender, a VBL rule trigger and a status sign. Get it from the Developer page (it’s delivered to your Second Life inventory) or on the Second Life Marketplace. Paste your key and bot ID (Dashboard › Developer API › Your bot IDs) into a script and it’s ready.