DEVELOPERS

Ellchat Bot API

Create a bot in Settings → Developer, copy its token once, and build permission-aware server integrations over HTTPS.

Effective and last updated: 23 August 2026

Authentication

Send Authorization: Bot YOUR_TOKEN with every request. Requests use JSON unless an endpoint says otherwise. A bot can access only servers it has joined and every operation is checked against its server roles and channel overrides.

Built-in automation

Bot owners can configure a log channel, member-event logs, moderation logs, deleted-message logs, and an autorole directly in Settings → Developer. The bot needs Send Messages in its log channel; autoroles also require Manage Roles and correct role hierarchy.

Base URL and versioning

Use your Ellchat deployment origin, for example https://ellchat-beta.wispbyte.org. The current API is beta and uses the /api/bot namespace. Ellchat IDs are opaque strings, timestamps use ISO 8601, list endpoints are bounded or cursor-paginated, and breaking changes will be announced before a stable version is introduced.

Realtime gateway

Hosted bots connect to the Socket.IO /bot namespace with auth: { token: "YOUR_BOT_TOKEN" }. A successful connection immediately marks the bot Online and dispatches READY, message, reaction, poll, presence, channel-activity and server-update events. Send a heartbeat every 25 seconds and call gateway:sync after your bot joins a server or creates channels.

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

const gateway = io("https://your-ellchat.example/bot", {
  transports: ["websocket"],
  auth: { token: process.env.ELLCHAT_BOT_TOKEN }
});

gateway.on("dispatch", event => {
  console.log(event.s, event.t, event.d);
});

setInterval(() => gateway.emit("heartbeat", null, console.log), 25_000);

Endpoints

GET/api/bot/me

Read the authenticated bot identity and server memberships.

GET/api/bot/gateway

Discover the authenticated Socket.IO gateway, heartbeat interval and supported events.

GET/api/bot/servers/{serverId}

Read server identity, badges and resource counts.

GET / POST/api/bot/channels/{channelId}/messages

Read history or send text, replies and up to five buttons.

GET / PATCH / DELETE/api/bot/messages/{messageId}

Read, edit or delete messages. Managing another author's message requires Manage Messages.

PUT / DELETE/api/bot/messages/{messageId}/reactions

Add, replace or remove the bot's reaction.

GET / POST/api/bot/servers/{serverId}/channels

List visible channels or create one with Manage Channels.

GET / PATCH / DELETE/api/bot/channels/{channelId}

Read, edit or delete one channel with channel permission checks.

GET / POST/api/bot/servers/{serverId}/categories

List or create channel categories.

PATCH / DELETE/api/bot/categories/{categoryId}

Rename or delete a category with Manage Channels.

GET/api/bot/interactions

Poll pending button interactions with cursor pagination.

POST/api/bot/interactions/{interactionId}/callback

Reply privately (ephemeral) or post a channel response.

GET / PATCH/api/bot/servers/{serverId}/configuration

Configure event logs and an automatic member role.

GET/api/bot/servers/{serverId}/members

List server members visible to the bot.

GET / PATCH/api/bot/servers/{serverId}/members/{userId}

Read a member or update their server nickname.

GET / POST/api/bot/servers/{serverId}/roles

List or create server roles and permissions.

GET / PATCH / DELETE/api/bot/roles/{roleId}

Read, edit or delete a role within the bot's hierarchy.

GET / POST/api/bot/servers/{serverId}/invites

List active invites or create a limited, expiring invite.

DELETE/api/bot/invites/{code}

Revoke an invite.

GET/api/bot/servers/{serverId}/audit-logs

Read recent moderation and administration events.

POST / PUT/api/bot/servers/{serverId}/members/{userId}/roles

Add roles (POST) or replace the role set (PUT) within the bot's hierarchy.

POST / DELETE/api/bot/servers/{serverId}/members/{userId}/moderation

Time out or untime a member (POST), or kick them (DELETE).

GET / POST / DELETE/api/bot/servers/{serverId}/bans

List bans, ban a member, or unban with the userId query parameter.

Send buttons

curl -X POST "https://your-ellchat.example/api/bot/channels/CHANNEL_ID/messages"   -H "Authorization: Bot YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{"content":"Choose an action","components":[{"type":"button","label":"Open ticket","style":"PRIMARY","customId":"ticket.open"},{"type":"button","label":"Help page","style":"LINK","url":"https://example.com/help"}]}'

Handle interactions

Poll GET /api/bot/interactions. A pending interaction expires after 15 minutes. Acknowledge it by posting {"content":"Ticket opened","ephemeral":true} to its callback endpoint. Ephemeral responses are delivered over Ellchat's authenticated user WebSocket and are visible only to the person who pressed the button.

Permissions and live members

Every mutation checks the bot's actual server roles, channel overrides and role hierarchy. The same realtime server-update stream refreshes member lists for connected people and notifies bot gateways when members, roles, channels or moderation state change.

Errors and limits

Successful responses use 2xx status codes. Errors return JSON with an error.code and human-readable error.message. Handle 401, 403, 404, 409 and 429 explicitly. Bots are subject to rate limits and must back off when a response is 429.

Safety rules

Do not use bots for unsolicited messages, scraping, account automation, surveillance, permission bypasses, or destructive moderation. Bot accounts carry a visible BOT tag, cannot be friended, and cannot receive direct messages.