OAuth 2.0 API

Getting started

Webhooks & events

Instead of polling, have the bot POST its events — IMs, invites, payments, dialogs — to your HTTPS endpoint as they happen. Needs the bots:callbacks scope.

Register a URL

curl -X POST "https://api.lifebots.cloud/api/v1/bots/$BOT_ID/callbacks" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/YOUR_BOT_ID/YOUR_LONG_RANDOM_SECRET",
    "events": "instant_message,group_invite"
  }'

events is a comma-separated list, or all. Posting the same URL again adds events to it. Manage them with List and Remove.

How delivery works

Request	`POST` with a JSON body, `User-Agent: LifeBots-CallbackHandler/1.0`
Your reply	Any 2xx within 10 seconds (30 for `group_invite`). Reply first, then do slow work.
Retries	None. A failed delivery is not sent again.
Failing URLs	A URL that fails for 24 hours in a row is removed automatically.
Bot offline	No events while the bot is logged out.

Requests are not signed. Put a long random secret in the URL, check it on every request, and use one URL per bot — most payloads name the bot but don't include its UUID.

Fields in every event

Field	Description
`action`	Event name. Use it to route the payload.
`bot_name`	Name of the bot that saw the event.
`channel`	LifeBots hosting channel of the bot.
`cid`	Unique id for this delivery. Use it to ignore duplicates.

Events

`instant_message`	Instant message received
`chat_message`	Local chat heard
`group_message`	Group chat message
`group_invite`	Group invite received
`balance_changed`	L$ balance changed
`script_dialog`	Script dialog shown
`online_status`	Bot status changed
`teleport_status`	Teleport progress
`offer_teleport`	Teleport offer received
`offer_friendship`	Friendship offer received
`offer_inventory`	Inventory offer received
`start_typing`	Someone started typing

all also delivers extra events (such as group_notice, region_restart, sit, autopilot_completed and avatar_tracker_update) that may change without notice. offer_friendship_accepted and offer_friendship_declined can be subscribed to but are not sent at the moment.

instant_message

Someone sent the bot an IM. speaker_type is AGENT for avatars, OBJECT for scripted objects (then speaker_owner is the object's owner).

{
  "action": "instant_message",
  "bot_name": "Helper Bot",
  "channel": "12",
  "cid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41-1790000000000",
  "speaker_type": "AGENT",
  "speaker_name": "Jane Resident",
  "speaker_uuid": "b9e1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "speaker_owner": "",
  "message": "Hi bot!"
}

chat_message

Something was said in local chat near the bot.

{
  "action": "chat_message",
  "bot_name": "Helper Bot",
  "channel": "12",
  "cid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41-1790000000000",
  "speaker_type": "AGENT",
  "speaker_name": "Jane Resident",
  "speaker_uuid": "b9e1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "speaker_owner": "b9e1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "message": "Hello everyone"
}

group_message

A message was posted in a group chat the bot is in.

{
  "action": "group_message",
  "bot_name": "Helper Bot",
  "channel": "12",
  "cid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41-1790000000000",
  "group_name": "My Group",
  "group_uuid": "a1b2c3d4-0000-4000-8000-000000000001",
  "speaker_uuid": "b9e1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "speaker_name": "Jane Resident",
  "is_moderator": false,
  "message": "Hi group"
}

group_invite

The bot was invited to a group. Your endpoint can decide: reply within 30 seconds with {"accept": true} (or the text accept=1) to join, {"accept": false} to decline. Any other reply leaves it to the bot's own settings.

Respond with POST /bots/{bot_id}/groups/invites/respond.

{
  "action": "group_invite",
  "bot_name": "Helper Bot",
  "channel": "12",
  "cid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41-1790000000000",
  "avatar_name": "Jane Resident",
  "avatar_uuid": "b9e1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "group_name": "My Group",
  "group_uuid": "a1b2c3d4-0000-4000-8000-000000000001",
  "session_id": "e9a8b7c6-d5e4-4f3a-8b2c-1d0e9f8a7b6c",
  "system_message": "Jane Resident has invited you to join a group."
}

balance_changed

The bot received or spent L$. Numbers arrive as strings.

The payload's action field is "balance_update", not "balance_changed".

{
  "action": "balance_update",
  "bot_name": "Helper Bot",
  "channel": "12",
  "cid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41-1790000000000",
  "amount": "50",
  "direction": "INCOMING",
  "source": "b9e1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "destination": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41",
  "balance": "1250",
  "trx_type": "PAY",
  "description": "Thanks!",
  "timestamp": "2026-10-02T12:00:00.000Z",
  "transaction": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b"
}

script_dialog

An object showed the bot a dialog menu. buttons is a JSON-encoded string of button labels.

Respond with POST /bots/{bot_id}/dialog/reply.

{
  "action": "script_dialog",
  "bot_name": "Helper Bot",
  "bot_uuid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41",
  "cid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41-1790000000000",
  "chat_channel": "-12345",
  "buttons": "[\"Yes\",\"No\"]",
  "object_name": "Door",
  "object_uuid": "b2f4e0a7-61c3-4d8e-a5f9-3c7e2d1b0a96",
  "owner_name": "Jane Resident",
  "text": "Open the door?"
}

online_status

The bot is CONNECTING, ONLINE, LOGGING_OUT, LOGGED_OUT, or hit LOGIN_ERROR (reason in error). Handy instead of polling after a login.

{
  "action": "online_status",
  "bot_uuid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41",
  "bot_name": "Helper Bot",
  "channel": "12",
  "status": "ONLINE",
  "timestamp": "2026-10-02T12:00:00.000Z",
  "cid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41-1790000000000",
  "region": "Sandbox Island"
}

teleport_status

Progress of a teleport: status is Start, Progress, Finished or Failed. location is the region the bot is in.

{
  "action": "teleport_status",
  "bot_name": "Helper Bot",
  "channel": "12",
  "cid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41-1790000000000",
  "status": "Finished",
  "message": "",
  "flags": [
    "ViaLocation"
  ],
  "location": "Sandbox Island"
}

offer_teleport

Someone offered the bot a teleport.

{
  "action": "offer_teleport",
  "bot_name": "Helper Bot",
  "channel": "12",
  "cid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41-1790000000000",
  "avatar_name": "Jane Resident",
  "avatar_uuid": "b9e1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "slurl": "Sandbox Island/128/128/25",
  "message": "Join me!",
  "session_id": "e9a8b7c6-d5e4-4f3a-8b2c-1d0e9f8a7b6c"
}

offer_friendship

Someone offered the bot friendship.

Respond with POST /bots/{bot_id}/friends/respond.

{
  "action": "offer_friendship",
  "bot_name": "Helper Bot",
  "channel": "12",
  "cid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41-1790000000000",
  "avatar_name": "Jane Resident",
  "avatar_uuid": "b9e1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "message": "Be my friend?",
  "session_id": "e9a8b7c6-d5e4-4f3a-8b2c-1d0e9f8a7b6c"
}

offer_inventory

Someone, or an object, gave the bot an item.

Respond with POST /bots/{bot_id}/inventory/respond.

The session id is in the field session (not session_id). Pass it along with sender_uuid and sender_type when you respond.

{
  "action": "offer_inventory",
  "bot_name": "Helper Bot",
  "channel": "12",
  "cid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41-1790000000000",
  "asset_type": "Notecard",
  "offer_type": "item",
  "folder": "",
  "sender_name": "Jane Resident",
  "sender_uuid": "b9e1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "sender_type": "agent",
  "session": "e9a8b7c6-d5e4-4f3a-8b2c-1d0e9f8a7b6c",
  "message": "Welcome notecard"
}

start_typing

An avatar started typing in an IM to the bot. stop_typing has the same shape.

{
  "action": "start_typing",
  "bot_name": "Helper Bot",
  "channel": "12",
  "cid": "7d1d5c58-2a8f-4c3e-9b11-0a6e5f2c9e41-1790000000000",
  "speaker_name": "Jane Resident",
  "speaker_uuid": "b9e1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e"
}

Putting it together: build an auto-reply bot.