Get or create a direct message channel between users

Get or create DM channel

Ask Perplexity

ElizaOS Documentation

Welcome to elizaos - Your AI Agent Framework

Introduction

Get Eliza up and running in under 5 minutes

Quickstart

Learn how to develop with elizaOS - from simple character modifications to core framework contributions

Development

Core Concepts

Agents

Projects

Architecture Overview

AgentRuntime

Service System

Comprehensive guide to the ElizaOS plugin system architecture and implementation

Plugin Internals

Practical patterns and structures used in the Eliza framework based on real implementations

Real-World Plugin and Project Patterns

A complete guide to creating, developing, and publishing ElizaOS plugins

Plugin Publishing Guide

Creates a new agent from character configuration

Create a new agent

Returns detailed information about a specific agent

Get agent details

List all agents

Update agent

Delete an agent

Start an agent

Stop an agent

Get public UI panels available for this agent from its plugins

Get agent panels

Create a world for an agent

Get all worlds

Update a world

Generate speech audio from text using agent's voice settings

Generate speech from text

Convert text to speech using agent's voice settings

Synthesize speech from text

Transcribe audio

Process an audio message - transcribe and get agent response

Process audio message

Convert a conversation (multiple messages) to speech

Convert conversation to speech

Create server

Create channel

Create central channel

Create a group channel with multiple participants

Create group channel

Send message to channel

Get channel messages

Get channel details

Get basic information for a specific channel (alias for details)

Get channel info

Get channel participants

Update channel

Delete channel

Delete channel message

Delete all channel messages

Delete all messages by a specific user in a channel

Delete all channel messages by user

Add agent to server

Add agent to channel

Remove agent from server

Get server agents

Get server channels

Get central servers

Get all channels for a server from central database

Get central server channels

Process a message from an external platform

Process external message

Ingest messages from external platforms (Discord, Telegram, etc.) into the central
messaging system. This endpoint handles messages from external sources and routes
them to the appropriate agents through the central message bus.


Ingest messages from external platforms

Submit a message to the central messaging bus for agent processing. This is the primary endpoint
for sending messages to agents, replacing the deprecated agent-specific message endpoints.

The message is submitted to a central channel and the appropriate agent(s) will process it
based on the channel and room configuration. This architecture allows for multi-agent
conversations and better message routing.

**Important**: Do not use `/api/agents/{agentId}/message` - that endpoint no longer exists.
All messages should go through this central messaging system.


Submit a message to the central messaging system

Notify the system that an agent has finished processing a message. This is used
to signal completion of agent responses and update the message state.


Mark message processing as complete

Retrieve all memories for a specific agent

Get agent memories

Get room memories

Create a room

Update a memory

Delete all agent memories

Delete all memories for a room

Get room details

Get agent rooms

Update a room

Delete a room

Upload media for agent

Upload media to channel

Get agent logs

Retrieve system logs with optional filtering

Get system logs

Retrieve system logs with optional filtering using POST method

Get system logs (POST)

Delete a specific log entry

Clear system logs

Basic health check

Health check endpoint

Simple ping endpoint to check if server is responsive

Ping health check

Returns the current status of the system with agent count and timestamp

Get system status

Get debug information about active servers (debug endpoint)

Get server debug info

Retrieve local environment variables from .env file

Get local environment variables

Update local environment variables in .env file

Update local environment variables

Stop the server

Socket.IO connection for real-time bidirectional communication. The server uses Socket.IO v4.x for WebSocket transport with automatic fallback.

**Connection URL**: `ws://localhost:3000/socket.io/` (or `wss://` for secure connections)

**Socket.IO Client Connection Example**:
```javascript
import { io } from 'socket.io-client';
const socket = io('http://localhost:3000');
```

**Events**:

### Client to Server Events:
- `join` - Join a room/channel
  ```json
  {
    "roomId": "uuid",
    "agentId": "uuid"
  }
  ```

- `leave` - Leave a room/channel
  ```json
  {
    "roomId": "uuid",
    "agentId": "uuid"
  }
  ```

- `message` - Send a message
  ```json
  {
    "text": "string",
    "roomId": "uuid",
    "userId": "uuid",
    "name": "string"
  }
  ```

- `request-world-state` - Request current state
  ```json
  {
    "roomId": "uuid"
  }
  ```

### Server to Client Events:
- `messageBroadcast` - New message broadcast
  ```json
  {
    "senderId": "uuid",
    "senderName": "string",
    "text": "string",
    "roomId": "uuid",
    "serverId": "uuid",
    "createdAt": "timestamp",
    "source": "string",
    "id": "uuid",
    "thought": "string",
    "actions": ["string"],
    "attachments": []
  }
  ```

- `messageComplete` - Message processing complete
  ```json
  {
    "channelId": "uuid",
    "serverId": "uuid"
  }
  ```

- `world-state` - World state update
  ```json
  {
    "agents": {},
    "users": {},
    "channels": {},
    "messages": {}
  }
  ```

- `logEntry` - Real-time log entry
  ```json
  {
    "level": "number",
    "time": "timestamp",
    "msg": "string",
    "agentId": "uuid",
    "agentName": "string"
  }
  ```

- `error` - Error event
  ```json
  {
    "error": "string",
    "details": {}
  }
  ```


Socket.IO Real-time Connection

Comprehensive guide to the ElizaOS Command Line Interface (CLI) tools and commands

ElizaOS CLI Overview

Initialize a new project, plugin, or agent with an interactive setup process

Create Command

Launch and manage ElizaOS projects and agents in production mode

Start Command

Run ElizaOS projects in development mode with hot reloading and debugging

Development Mode

Configure environment variables and API keys for ElizaOS projects

Environment Configuration

Managing ElizaOS agents through the CLI - list, configure, start, stop, and update agents

Agent Command

Manage ElizaOS plugins within a project - list, add, remove

Plugin Management

Run and manage tests for ElizaOS projects and plugins

Test Command

Update your project's ElizaOS dependencies and CLI to the latest published versions

Update Command

Publish a plugin to npm, create a GitHub repository, and submit to the ElizaOS registry

Agents

Audio

Messaging

Memory

Rooms

Media

Logs

System

WebSocket

Get or create DM channel

Query Parameters

Response