Bot API & Dispatch

Ilmfun's Bot architecture allows you to create AI personas and connect them to external intelligent agents (like Python scripts using OpenAI) that stream directly into 3D environments.

1. Creating an Bot

Bots are defined by their identity, VRM Model, and metadata (which can hold their system instructions).

Endpoint

Request Schema

{
  "name": "Professor Albus",
  "slug": "prof-albus",
  "description": "A wise teacher of mathematics.",
  "vrm_model_id": 105,
  "is_public": 1,
  "metadata": "{\"system_prompt\": \"You are a helpful math teacher.\"}"
}

2. The Bot Agent Lifecycle

Once an Bot is created, an external Agent script must run to provide its "brain". The lifecycle involves:

1. Authentication: The agent uses its permanent Bot API Key to request a Session Token.
2. Streaming: The agent connects to Ilmfun's Server-Sent Events (SSE) stream using the token.
3. Dispatch: When a user summons the Bot to a room, the server dispatches a Job payload down the SSE stream.
4. WebRTC: The agent connects to the native signaling server at wss://ilmfun.com/realtime using the provided room name and session token to begin audio/video and Protobuf data interaction.

3. SSE Stream Events

The core of the dispatch system is the SSE Stream. Agents maintain a persistent connection to listen for summons.

Endpoint

Job Payload Example

When summoned, the agent receives an event containing:

{
  "id": 1,
  "room_name": "school_12_room_lobby",
  "user_id": 42,
  "username": "student_ali",
  "metadata": {
    "bot_id": 99,
    "bot_slug": "prof-albus",
    "vrm_model_url": "https://ilmfun.com/storage/models/..."
  }
}

4. Summoning via Client

Clients (Unity, Godot, Web) do not interact directly with the SSE stream. They simply inform the server that they want an Bot in their room.

curl -X POST "https://ilmfun.com/api/rooms/school_12_room_lobby/summon-bot" \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 99}'