Robots Overview

Robots are automated integrations that connect to your Lag server. They can send and receive messages, monitor events, and react to activity in real time.

What Are Robots?

A robot is a programmatic agent that interacts with your server through the Lag API. Unlike regular users, robots authenticate with API keys instead of OAuth, and they operate through HTTP endpoints rather than WebSocket connections.

Robots are scoped to a single server. Each robot belongs to one server and can only access rooms and members within that server.

Quick Start

Lag ships first-party SDKs for Node and Python. Both auto-detect a robot API key (lag_robot_*) and route requests to the /robots/@me endpoints, so the same client code works for both users and robots.

Install:

npm install @lagapp/sdk

pip install lagclient

Send your first message as a robot:

import { LagClient } from '@lagapp/sdk';

const client = new LagClient({ token: process.env.LAG_ROBOT_API_KEY! });

const me = await client.identity();
console.log(`Hello, I'm ${me.displayName} on server ${me.serverId}`);

await client.servers.rooms.messages.send(me.serverId!, 'room_xyz', {
	content: 'Hello from my robot!',
});

import os
from lagclient import Client

with Client(token=os.environ['LAG_ROBOT_API_KEY']) as client:
    me = client.identity()
    print(f"Hello, I'm {me.display_name} on server {me.server_id}")

    client.servers.rooms.messages.send(
        me.server_id,
        'room_xyz',
        content='Hello from my robot!',
    )

The SDKs cover sending, editing, and deleting messages, listing rooms and members, and reading message history. For receiving events, see Transport Types - event delivery currently uses raw HTTP.

Capabilities

Robots can:

• Send messages to any room in the server
• Edit and delete their own messages
• Receive events when things happen in the server (messages, joins, leaves, voice activity)
• Respond to @mentions - users can type @robotname to directly address a robot, triggering a targeted robot.mentioned event
• Read server state including member lists, room lists, message history, and presence data

Robots cannot:

• Join voice rooms or transmit audio
• Create or delete rooms
• Manage server settings or members
• Access other servers

Use Cases

Moderation

Build a robot that monitors messages for prohibited content, automatically removes violations, and logs moderation actions.

Notifications

Connect external services to your server. A robot can post alerts from monitoring systems, CI/CD pipelines, or any service with webhook support.

Game Stats

Create a robot that pulls game statistics from an external API and posts updates when players achieve milestones or complete matches.

Welcome Messages

A robot can watch for member.join events and send a welcome message to a designated room with server rules and useful links.

Custom Commands

Build a robot that listens for messages starting with a prefix (like !) and responds with information, performs lookups, or triggers external actions.

Limits

• 10 robots per server - Each server can have at most 10 active robots
• Rate limits - Robots are rate-limited to 100 requests per minute globally and 10 messages per 10 seconds
• Message size - Robot messages follow the same size limits as user messages

How Robots Differ from Users

Getting Started

1. Navigate to the Robot Management Portal
2. Select your server
3. Create a new robot with your desired permissions
4. Use the API key to authenticate requests
5. Choose a transport type for receiving events

Continue to Creating Robots for a step-by-step walkthrough.