API Migration Guide

Guide for migrating from old agent-specific APIs to the new centralized messaging system

This guide helps you migrate from the old agent-specific API endpoints to the new centralized messaging system in elizaOS.

Major Changes

1. Message Submission Endpoint

The most significant change is the migration of the message submission endpoint:

Old: /api/agents/{agentId}/message (Removed)
New: /api/messaging/submit

2. Audio Endpoints

Audio-related endpoints have been reorganized:

Old: /api/agents/{agentId}/audio/...
New: /api/audio/{agentId}/...

Message Submission Migration

Before (Incorrect)

const response = await fetch("/api/agents/{agentId}/message", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    senderId: "user123",
    roomId: "room456",
    text: "Hello agent!",
    source: "api",
  }),
});

After (Correct)

const response = await fetch("/api/messaging/submit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel_id: "room456",
    server_id: "00000000-0000-0000-0000-000000000000",
    author_id: "user123",
    content: "Hello agent!",
    source_type: "user_message",
    raw_message: { text: "Hello agent!" },
  }),
});

Key Differences

Request Payload Structure

The new API uses a different payload structure:

Old Field	New Field	Notes
`senderId`	`author_id`	UUID of the message author
`roomId`	`channel_id`	UUID of the channel/room
`text`	`content`	Message content
`source`	`source_type`	Message source identifier
N/A	`server_id`	Required: Use central server ID
N/A	`raw_message`	Original message structure

Central Server ID

The new system uses a central message bus. Always use this server ID:

server_id: "00000000-0000-0000-0000-000000000000";

WebSocket Migration

The real-time communication has also been updated:

Old: Raw WebSocket connection
New: Socket.IO client

Socket.IO Connection Example

import { io } from "socket.io-client";

const socket = io("http://localhost:3000", {
  auth: {
    token: "your-auth-token",
  },
});

// Join a channel
socket.emit("join_channel", { channelId: "room456" });

// Listen for messages
socket.on("new_message", (message) => {
  console.log("New message:", message);
});

Benefits of New Architecture

Multi-Agent Support: Messages are routed through a central system, enabling better multi-agent coordination
Better Message Routing: Centralized routing allows for more sophisticated message handling
Consistent State Management: All agents share a consistent view of conversations
Improved Scalability: The architecture supports horizontal scaling

Migration Checklist

Follow these steps to migrate your integration:

✅ Update all API endpoints from agent-specific to centralized endpoints
✅ Modify request payloads to match the new structure
✅ Update audio endpoint paths
✅ Migrate WebSocket connections to Socket.IO
✅ Test message submission with the new endpoint
✅ Verify real-time message delivery
✅ Test audio transcription/generation if used

Testing Your Migration

1. Test Message Submission

async function testMessageSubmission() {
  const testMessage = {
    channel_id: "your-channel-id",
    server_id: "00000000-0000-0000-0000-000000000000",
    author_id: "test-user-id",
    content: "Test message from migration",
    source_type: "api_test",
    raw_message: { text: "Test message from migration" },
  };

  try {
    const response = await fetch("http://localhost:3000/api/messaging/submit", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": "your-api-key", // if authentication is enabled
      },
      body: JSON.stringify(testMessage),
    });

    const result = await response.json();
    console.log("Message sent successfully:", result);
  } catch (error) {
    console.error("Failed to send message:", error);
  }
}

2. Test Socket.IO Connection

function testSocketConnection() {
  const socket = io("http://localhost:3000");

  socket.on("connect", () => {
    console.log("Connected to Socket.IO server");
    socket.emit("join_channel", { channelId: "your-channel-id" });
  });

  socket.on("new_message", (message) => {
    console.log("Received message:", message);
  });

  socket.on("error", (error) => {
    console.error("Socket error:", error);
  });
}