Create Channel - elizaOS

Endpoint

POST /agents/{agentId}/channels

Creates a new communication channel for an agent. Channels organize conversations by platform, topic, or use case (e.g., Discord, Telegram, Web, Support).

Request

Path Parameters

agentId

string

required

Unique identifier (UUID) of the agent

Headers

Content-Type

string

required

Must be application/json

Authorization

string

Bearer token for authentication (if required)

Body Parameters

name

string

required

Name of the channel

type

string

required

Channel type: discord, telegram, twitter, direct, web, or custom

config

object

Channel-specific configuration settings

config.platformId

string

Platform-specific channel identifier (e.g., Discord channel ID)

config.webhookUrl

string

Webhook URL for receiving messages

config.token

string

Authentication token for the platform

config.autoReply

boolean

Whether to automatically reply to messages

metadata

object

Additional metadata for the channel

enabled

boolean

default:"true"

Whether the channel is enabled

Response

success

boolean

required

Indicates if the channel was created successfully

data

object

required

Created channel details

data.channelId

string

required

Unique identifier for the channel (UUID)

data.name

string

required

Name of the channel

data.type

string

required

Channel type

data.agentId

string

required

Agent ID associated with the channel

data.enabled

boolean

Whether the channel is enabled

data.createdAt

number

Unix timestamp when the channel was created

Examples

Create Web Channel

curl -X POST http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000/channels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website Chat",
    "type": "web",
    "config": {
      "autoReply": true
    }
  }'

Create Discord Channel

curl -X POST http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Discord Support",
    "type": "discord",
    "config": {
      "platformId": "123456789012345678",
      "token": "DISCORD_BOT_TOKEN",
      "autoReply": true
    },
    "metadata": {
      "guild": "My Server",
      "purpose": "customer-support"
    }
  }'

Create Telegram Channel

curl -X POST http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000/channels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Telegram Bot",
    "type": "telegram",
    "config": {
      "token": "TELEGRAM_BOT_TOKEN",
      "autoReply": true
    }
  }'

Create Custom Channel

curl -X POST http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000/channels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Workspace",
    "type": "slack",
    "config": {
      "webhookUrl": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
      "token": "SLACK_BOT_TOKEN",
      "autoReply": false
    },
    "enabled": true
  }'

Response Example

Success Response

{
  "success": true,
  "data": {
    "channelId": "channel-770e8400-e29b-41d4-a716-446655440020",
    "name": "Website Chat",
    "type": "web",
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "enabled": true,
    "createdAt": 1709683200000
  }
}

Code Examples

JavaScript/Node.js

const agentId = "550e8400-e29b-41d4-a716-446655440000";

const createChannel = async (name, type, config = {}) => {
  const response = await fetch(
    `http://localhost:3000/agents/${agentId}/channels`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name,
        type,
        config,
        enabled: true
      })
    }
  );
  
  const { success, data } = await response.json();
  
  if (success) {
    console.log(`Channel created: ${data.channelId}`);
    return data;
  }
};

// Create a web channel
await createChannel('Website Chat', 'web', {
  autoReply: true
});

// Create a Discord channel
await createChannel('Discord Support', 'discord', {
  platformId: '123456789012345678',
  token: process.env.DISCORD_BOT_TOKEN,
  autoReply: true
});

Python

import requests
import os

agent_id = "550e8400-e29b-41d4-a716-446655440000"

def create_channel(name: str, channel_type: str, config: dict = None):
    response = requests.post(
        f'http://localhost:3000/agents/{agent_id}/channels',
        json={
            'name': name,
            'type': channel_type,
            'config': config or {},
            'enabled': True
        }
    )
    
    data = response.json()
    
    if data['success']:
        print(f"Channel created: {data['data']['channelId']}")
        return data['data']

# Create a web channel
create_channel('Website Chat', 'web', {
    'autoReply': True
})

# Create a Discord channel
create_channel('Discord Support', 'discord', {
    'platformId': '123456789012345678',
    'token': os.getenv('DISCORD_BOT_TOKEN'),
    'autoReply': True
})

TypeScript

interface ChannelConfig {
  platformId?: string;
  webhookUrl?: string;
  token?: string;
  autoReply?: boolean;
  [key: string]: any;
}

interface CreateChannelRequest {
  name: string;
  type: string;
  config?: ChannelConfig;
  metadata?: Record<string, any>;
  enabled?: boolean;
}

interface CreateChannelResponse {
  success: boolean;
  data: {
    channelId: string;
    name: string;
    type: string;
    agentId: string;
    enabled: boolean;
    createdAt: number;
  };
}

const createChannel = async (
  agentId: string,
  request: CreateChannelRequest
): Promise<CreateChannelResponse> => {
  const response = await fetch(
    `http://localhost:3000/agents/${agentId}/channels`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(request)
    }
  );
  
  return await response.json();
};

// Usage
const channel = await createChannel(
  "550e8400-e29b-41d4-a716-446655440000",
  {
    name: "Website Chat",
    type: "web",
    config: {
      autoReply: true
    },
    enabled: true
  }
);

Error Responses

400 Bad Request

{
  "success": false,
  "error": "Channel name and type are required"
}

404 Not Found

{
  "success": false,
  "error": "Agent not found"
}

409 Conflict

{
  "success": false,
  "error": "Channel with this name already exists"
}

500 Internal Server Error

{
  "success": false,
  "error": "Failed to create channel"
}

Channel Types

Built-in Types

discord - Discord server integration
telegram - Telegram bot integration
twitter - Twitter/X integration
web - Web-based chat interface
direct - Direct API communication

Custom Types

You can create custom channel types for your specific integrations:

await createChannel('Slack Support', 'slack', {
  webhookUrl: 'https://hooks.slack.com/...',
  token: 'xoxb-...',
  autoReply: true
});

Managing Channels

List All Channels

const channels = await fetch(
  `http://localhost:3000/agents/${agentId}/channels`
).then(r => r.json());

console.log(`Found ${channels.data.length} channels`);

Update Channel

await fetch(
  `http://localhost:3000/agents/${agentId}/channels/${channelId}`,
  {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      enabled: false
    })
  }
);

Delete Channel

await fetch(
  `http://localhost:3000/agents/${agentId}/channels/${channelId}`,
  {
    method: 'DELETE'
  }
);

Best Practices

Secure Token Storage

Never hardcode tokens in configuration. Use environment variables:

const config = {
  token: process.env.DISCORD_BOT_TOKEN,
  platformId: process.env.DISCORD_CHANNEL_ID
};

Test Channels First

Create test channels before production:

await createChannel('Test Channel', 'discord', {
  platformId: TEST_CHANNEL_ID,
  token: process.env.DISCORD_BOT_TOKEN,
  autoReply: false  // Manual testing
});

Use Metadata

Store additional context in metadata:

{
  name: "Support Channel",
  type: "discord",
  metadata: {
    team: "customer-support",
    region: "US-East",
    priority: "high"
  }
}

Next Steps

Send Message

Send messages through the channel

Get Messages

Retrieve channel message history

Sessions

Manage conversation sessions

Overview

Agents

Messaging

​Endpoint

​Request

​Path Parameters

​Headers

​Body Parameters

​Response

​Examples

​Create Web Channel

​Create Discord Channel

​Create Telegram Channel

​Create Custom Channel

​Response Example

​Success Response

​Code Examples

​JavaScript/Node.js

​Python

​TypeScript

​Error Responses

​400 Bad Request

​404 Not Found

​409 Conflict

​500 Internal Server Error

​Channel Types

​Built-in Types

​Custom Types

​Managing Channels

​List All Channels

​Update Channel

​Delete Channel

​Best Practices

​Secure Token Storage

​Test Channels First

​Use Metadata

​Next Steps

Send Message

Get Messages

Sessions

Build docs developers (and LLMs) love

Endpoint

Request

Path Parameters

Headers

Body Parameters

Response

Examples

Create Web Channel

Create Discord Channel

Create Telegram Channel

Create Custom Channel

Response Example

Success Response

Code Examples

JavaScript/Node.js

Python

TypeScript

Error Responses

400 Bad Request

404 Not Found

409 Conflict

500 Internal Server Error

Channel Types

Built-in Types

Custom Types

Managing Channels

List All Channels

Update Channel

Delete Channel

Best Practices

Secure Token Storage

Test Channels First

Use Metadata

Next Steps