Build on Echoed

Introduction

Echoed has three ways to build on it:

• Bots — accounts that join servers and act through the Bot API and real-time events: moderation, anti-raid, levels, music, forum helpers, anything a member could do.
• Webhooks — a URL that posts into one channel. No account, no socket; ideal for CI, alerts and feeds. See Webhooks.
• Apps — "Login with Echoed" through OAuth2, and games that people play inside a DM or a server's game lounge.

Quick Start (bots)

1. Create a bot in Settings → Developer → Bot Profile
2. Copy its Bot API Key (starts with zbot_)
3. Submit it for review. Until it is approved, add it to your own test server with a development invite token
4. Call the API with the X-Bot-Token header, and connect to the socket to receive events

The fastest way to learn the API is to read a real bot: see Example Bots.

Authentication

All Bot API requests carry your bot's API key. X-Bot-Token is the usual header; X-Bot-API-Key and Authorization: Bot <key> are accepted too, checked in that order.

X-Bot-Token: zbot_your_api_key_here
Content-Type: application/json

A bot must pass review before it can use the API. Until then every call answers 403 with "type": "bot_not_approved" — except in servers that added it with a development invite token. Changing the bot's name, description or avatar sends it back to the review queue automatically.

A few endpoints are marked user login. Those are called by a person (the bot's owner, or a server admin) with their normal Echoed session in Authorization: Bearer <token>, not with the bot key. They are what the Echoed app itself uses, documented so you can script them.

Base URL

All Bot API endpoints are prefixed with:

https://go.echoed.gg/v1/bots

For example, to validate your token: GET https://go.echoed.gg/v1/bots/validate

Rate Limits

The Bot API enforces a per-bot sliding-window rate limit of 120 requests per minute across all endpoints. When the limit is hit, the API returns 429 Too Many Requests with a retryAfter field (seconds) in the response body.

{
  "message": "Rate limited. Please wait.",
  "code": 429,
  "retryAfter": 12
}

Error Handling

The API returns standard HTTP status codes. Error responses include a JSON body with a message field.

{
  "message": "Bot is not a member of this server",
  "success": false
}

Example Bots

Two production bots are open source. Both are TypeScript and use exactly the API on this page. Start from whichever is closer to what you are building.

git clone https://github.com/shaongitbd/memebot
cd memebot
npm install
cp .env.example .env   # set BOT_TOKEN to your zbot_ key
npm run dev

Testing Before Review

Review takes time, and you need somewhere to run your bot meanwhile. A development invite token (edev_…) lets the admin of a server add your unreviewed bot there, after seeing a warning that it has not been reviewed and which permissions it asks for.

• One token per bot. It opens at most 5 servers and expires after 30 days.
• Generating a new one replaces the old one. Servers that already added the bot keep it.
• Approval deletes the token: from then on, admins add the bot from the directory.
• The bot stays hidden from discovery and locked out of every other server until it is approved.

You can do all of this from Settings → Developer → Bot Profile. The endpoints below are what that screen calls. They take a user login: the bot's owner signed in as the bot account, or the receiving server's admin.

{
  "token": "edev_3f9c…",
  "maxServers": 5,
  "usedSlots": 1,
  "approved": false,
  "createdAt": "2026-09-20T10:00:00Z",
  "expiresAt": "2026-10-20T10:00:00Z",
  "expired": false
}

{ "token": "edev_3f9c…" }

{
  "botId": "bot-user-id",
  "name": "Panda Dev",
  "avatar": "https://…",
  "description": "…",
  "developer": "…",
  "requestedPermissions": 4352,   // send_messages + add_reactions
  "reviewState": "pending",
  "approved": false,
  "slotsRemaining": 4
}

{
  "token": "edev_3f9c…",
  "grantedPermissions": 0,
  "acknowledgeRisk": true
}

Bot Profile

{
  "valid": true,
  "bot_id": "67e537d200011f5275d2",
  "message": "Bot API key is valid."
}

{
  "id": "67e537d200011f5275d2",
  "username": "my-awesome-bot",
  "isBot": true,
  "botDescription": "A helpful server bot",
  "botCategory": "utility",
  "isPublic": true,
  "avatarUrl": "https://s3.echoed.gg/..."
}

{
  "botDescription": "Updated bot description",
  "botCategories": ["utility", "moderation"],
  "botSupportServer": "https://echoed.gg/invite/...",
  "botVersion": "1.2.0"
}

{
  "name": "Panda Bot",
  "avatar": "https://cdn.example.com/panda.png"
}

{
  "success": true,
  "name": "Panda Bot",
  "avatar": "https://cdn.example.com/panda.png"
}

Per-Server Customization

A bot can have a different display name in each server it's a member of — the same way a regular user does. Useful for region-specific deployments ("Panda EU" vs "Panda NA"), themed servers, or matching a server's naming convention. The per-server name shadows the global one for messages, member lists, and mentions.

{
  "nickname": "Panda EU"
}

{
  "success": true,
  "nickname": "Panda EU"
}

{
  "success": true,
  "path": "public/servers/server-id/members/bot-id/avatar.png",
  "url": "https://s3.echoed.gg/public/servers/.../avatar.png",
  "timestamp": 1735531200000
}

Member Customization

Admin-style endpoints — the bot edits other members' per-server display data. Useful for moderation bots that implement !nick @user newname style commands. Required permission on the bot: MANAGE_SERVER. The server owner cannot be modified.

Authority is the bot's responsibility. These endpoints check the bot's perm. The command-issuing user's authority should be checked by the bot before calling — for example, gating !nick on the sender holding MANAGE_SERVER.

{
  "nickname": "NewName"
}

{
  "success": true,
  "userId": "target-user-id",
  "nickname": "NewName"
}

{
  "success": true,
  "userId": "target-user-id",
  "path": "public/servers/.../avatar.png",
  "url": "https://s3.echoed.gg/...",
  "timestamp": 1735531200000
}

Voice

Bots can join a voice channel and publish audio (music, TTS, soundboards, etc.). Echoed uses LiveKit as the SFU; the bot endpoint mints an AccessToken so the bot can connect via @livekit/rtc-node (or any LiveKit client SDK) and publish a microphone track.

Bot must hold CONNECT + SPEAK in the target channel (channel-scoped — overrides honored). Returned token is a 24-hour LiveKit AccessToken with canPublishSources: ['microphone']; it cannot be used for video or screen-share.

{
  "success": true,
  "url": "wss://livekit.echoed.gg",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "room": "call-channel-id",
  "callId": "channel-id",
  "identity": "bot-user-id",
  "expiresIn": 86400
}

{ "channelId": "voice-channel-id" }   // or { "channelId": null }

Servers

{
  "count": 2,
  "servers": [
    {
      "serverId": "6894d3d90011f842607c",
      "serverName": "My Server",
      "serverIcon": "",
      "invitedAt": "2026-01-06T13:41:44Z",
      "invitedBy": "user-id"
    }
  ]
}

{
  "id": "6894d3d90011f842607c",
  "name": "My Server",
  "description": "A cool server",
  "ownerId": "user-id",
  "memberCount": 42,
  "channelCount": 8,
  "iconUrl": "",
  "createdAt": "2025-08-07T16:27:05Z"
}

Channels

{
  "channels": [
    {
      "id": "647a23fede03765e0348",
      "name": "general",
      "type": "text",
      "description": "",
      "createdAt": "2026-01-05T11:20:43Z"
    }
  ],
  "total": 8
}

{
  "name": "bot-updates",
  "type": "text",
  "description": "Automated bot announcements",
  "isPrivate": false,
  "isNsfw": false,
  "categoryId": "category-id",
  "position": 0
}

{
  "name": "renamed-channel",
  "description": "Updated description",
  "isPrivate": false,
  "isNsfw": true,
  "slowModeSeconds": 10,
  "categoryId": "new-category-id",
  "position": 2
}

{
  "channelId": "channel-id",
  "categoryId": "category-id",
  "position": 0
}

Channel Permissions

Per-channel overrides for a role or a single member: what a bot needs to lock a channel during a raid, hide a mod-log from members, or build a ticket channel only its opener can see. They work exactly like the override editor in the app.

• The bot needs MANAGE_CHANNELS.
• Every permission the bot changes must be one it holds in that channel itself, unless it is an administrator. A bot cannot hand out rights it was never given.
• target_type is role or user. A role target is a role id from this server, or everyone. A user target must be a member.
• Unknown permission names are rejected, not ignored.

{
  "channelId": "channel-id",
  "permissionOverrides": [
    {
      "targetType": "role",
      "targetId": "everyone",
      "allow": [],
      "deny": ["send_messages", "add_reactions"],
      "allowBits": 0,
      "denyBits": 4352
    }
  ]
}

{
  "allow": [],
  "deny": ["send_messages", "add_reactions"]
}

Permission Names

view_channels manage_channels manage_roles manage_server create_invite kick_members ban_members administrator send_messages read_message_history use_external_emojis add_reactions attach_files embed_links manage_messages connect speak mute_members deafen_members move_members use_voice_activity priority_speaker use_camera screen_share create_tasks create_threads create_events

Use allowBits / denyBits instead of names if you prefer. Bits outside what a channel override can store are rejected.

Categories

{
  "name": "Bot Channels",
  "position": 0
}

{
  "categories": [
    { "categoryId": "id1", "position": 0 },
    { "categoryId": "id2", "position": 1 }
  ]
}

Members

{
  "userId": "user-id",
  "serverId": "server-id",
  "permissions": [
    "VIEW_CHANNELS", "SEND_MESSAGES",
    "READ_MESSAGE_HISTORY", "CONNECT", "SPEAK"
  ]
}

{
  "userId": "user-id",
  "serverId": "server-id",
  "channelId": "channel-id",
  "permissions": [
    "VIEW_CHANNELS", "SEND_MESSAGES",
    "READ_MESSAGE_HISTORY", "MANAGE_MESSAGES"
  ]
}

Moderation

Punitive member actions: kick, ban, unban, and timeout. Each requires the matching permission on the bot. The server owner cannot be targeted.

{ "reason": "Optional reason" }

{ "reason": "Reason for ban" }

Timeout

Timeouts mute a member for a duration: they cannot send messages or join voice. Enforcement is server-side, so clients can't bypass it. Requires MUTE_MEMBERS.

{
  "durationSeconds": 300,
  "reason": "Spamming"
}

{
  "success": true,
  "userId": "user-id",
  "timeoutUntil": "2026-04-28T17:25:00Z",
  "durationSeconds": 300,
  "reason": "Spamming"
}

{
  "active": true,
  "userId": "user-id",
  "timeoutUntil": "2026-04-28T17:25:00Z",
  "reason": "Spamming",
  "setBy": "bot-id"
}

Anti-Raid & Safety

The server-level safety controls, open to bots so an anti-raid detector can close a real door instead of kicking accounts one by one after they arrive. All four endpoints need MANAGE_SERVER — the same permission a person needs to change these settings in the app.

{
  "untilSeconds": 600,
  "reason": "Raid detected: 25 joins in 10 seconds"
}

{
  "success": true,
  "until": "2026-09-27T18:10:00Z",
  "reason": "Raid detected: 25 joins in 10 seconds"
}

{ "level": 2 }

{ "success": true, "level": 2, "previous": 0 }

{
  "userId": "user-id",
  "username": "newcomer",
  "displayName": "Newcomer",
  "avatarUrl": "",
  "hasAvatar": false,
  "accountAgeSeconds": 312,
  "createdAt": "2026-09-27T17:55:00Z"
}

Roles

{
  "name": "Moderator",
  "color": "#FF5733",
  "permissions": ["SEND_MESSAGES", "MANAGE_MESSAGES", "KICK_MEMBERS"],
  "position": 5
}

{
  "name": "Senior Moderator",
  "color": "#9B59B6",
  "permissions": ["MANAGE_MESSAGES", "KICK_MEMBERS", "BAN_MEMBERS"],
  "position": 8,
  "mentionable": true,
  "hoist": true
}

{
  "roles": ["role-id-1", "role-id-2"]
}

Messages

{
  "channelId": "channel-id",
  "content": "Hello from my bot! 🤖",
  "attachmentIds": [],
  "mentions": [],
  "replyToId": "",
  "embeds": []
}

Sending Messages with Attachments

To send a message with file attachments, upload the file first, then reference the returned fileId in your message.

{
  "success": true,
  "fileId": "abc123",
  "path": "channels/server-id/channel-id/abc123.png",
  "url": "https://s3.echoed.gg/files/channels/...",
  "filename": "screenshot.png",
  "size": 184320,
  "contentType": "image/png",
  "width": 1920,
  "height": 1080,
  "blurhash": "U.P,rXfQkCbH"
}

{
  "channelId": "channel-id",
  "content": "Check out this image!",
  "attachmentIds": ["abc123"],
  "mentions": [],
  "replyToId": ""
}

{
  "content": "Edited message content"
}

{
  "embeds": [
    {
      "type": "rich",
      "title": "Now playing",
      "description": "▰▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱▱▱▱▱\n2:14 / 6:42",
      "color": 16763688
    }
  ]
}

{
  "messageIds": ["id1", "id2", "id3"]
}

{
  "success": true,
  "deleted": ["id1", "id3"],
  "count": 2
}

Rich Embeds

Bots can ship up to 10 rich embeds per message — coloured cards with a title, description, fields, thumbnail/image, author and footer. Pass an embeds array on POST /v1/bots/{server_id}/messages/send. content may be empty when at least one embed is present.

Embed Object

Every field is optional except type. Use "rich" for bot-authored cards.

{
  "type": "rich",           // "rich" | "image" | "video" | "gifv" | "article" | "link" | "audio"
  "url": "https://...",      // makes the title clickable
  "title": "Card title",
  "description": "Body copy. Markdown is rendered.",
  "color": 16763688,         // 0xFFC928 — left-bar accent, decimal int
  "timestamp": "2026-04-29T12:00:00Z", // ISO-8601, rendered next to footer
  "author":    { "name": "…", "url": "…", "icon_url": "…" },
  "thumbnail": { "url": "https://…/thumb.png" },
  "image":     { "url": "https://…/banner.png" },
  "fields": [
    { "name": "Field", "value": "Value", "inline": true }
  ],
  "footer": { "text": "Footer copy", "icon_url": "…" }
}

Sub-Objects

{
  "name": "Author or site name",
  "url": "https://…",
  "icon_url": "https://…/avatar.png"
}

{
  "url": "https://…/asset",
  "width": 1280,
  "height": 720
}

{
  "name": "Heading",
  "value": "Body — markdown supported.",
  "inline": false
}

{
  "text": "3 active",
  "icon_url": "https://…/icon.png"
}

Example: Embed-Only Message

Empty content with one rich embed — the canonical pattern for status / list / leaderboard cards.

{
  "channelId": "channel-id",
  "content": "",
  "embeds": [
    {
      "type": "rich",
      "title": "Leaderboard",
      "description": "**1.** alice — 12,400 xp\n**2.** bob — 9,810 xp\n**3.** carol — 7,205 xp",
      "color": 16763688,
      "footer": { "text": "Top 3 of 142" },
      "timestamp": "2026-04-29T12:00:00Z"
    }
  ]
}

Limits & Notes

• Up to 10 embeds per message — extras are silently dropped.
• color is a decimal integer (e.g. 0xFFC928 → 16763688). Omit for the client's default neutral.
• timestamp must be ISO-8601 (UTC). Pass an empty string to suppress.
• Image/thumbnail/video/audio URLs are proxied through Echoed's media CDN — clients receive a signed proxy_url alongside your original url.
• Auto-unfurled link embeds (when users post URLs) use the same shape — your bot can mirror that look by sending a rich embed of type: "rich" with an author block.

Reactions

Bots can add and remove their own reactions on messages. Useful for polls (seed 👍/👎), giveaways (seed 🎉), and reaction-role setup messages.

To listen for reactions added by other users, subscribe to the MESSAGE_REACTION_ADD WebSocket event.

Pinned Messages

Pin and unpin messages in a channel. Both endpoints require MANAGE_MESSAGES in the target channel.

Direct Messages

{
  "username": "target-user",
  "content": "Hey! This is a DM from my bot."
}

{
  "message": "DM sent successfully.",
  "messageId": "message-id",
  "receiverId": "user-id",
  "content": "Hey! This is a DM from my bot."
}

Threads & Forums

A thread channel is a forum: a list of posts, each with a title, an optional category, and a flat conversation of messages. The post's body is its first message; replies are ordinary messages after it. A bot's post is identical to a person's apart from its message type.

Paths take the channel id right after the server id. Reading needs read_threads, opening a post needs create_threads and send_messages, and pin, lock and category changes need manage_threads.

Posts

{
  "posts": [
    {
      "id": "post-id",
      "title": "Patch 1.4 feedback",
      "categoryId": "category-id",
      "authorId": "user-id",
      "rootMessageId": "message-id",
      "isPinned": false, "isLocked": false, "isClosed": false,
      "replyCount": 12,
      "excerpt": "First impressions after a weekend of…",
      "previewImages": [],
      "lastActivityAt": "2026-09-27T16:40:00Z",
      "createdAt": "2026-09-26T09:12:00Z"
    }
  ],
  "total": 48,
  "nextCursor": "opaque-cursor",
  "hasMore": true
}

{
  "title": "Weekly patch notes",
  "content": "Here is what changed this week…",
  "categoryId": "category-id",
  "attachmentIds": [],
  "mentions": [],
  "embeds": []
}

Moderation

Messages

{
  "content": "Fixed in 1.4.1, thanks for the report.",
  "replyToId": "message-id",
  "attachmentIds": [],
  "mentions": [],
  "embeds": []
}

Following & Read State

Categories

Forum categories are per server and shared by all its thread channels. Changing them needs manage_threads.

Tasks

Manage tasks in Task-type channels. Your bot can create, update, and delete tasks for project management and automation.

{
  "channelId": "task-channel-id",
  "title": "Fix login bug",
  "description": "Users can't login with OAuth",
  "assigneeId": "user-id",
  "dueDate": "2026-04-01T00:00:00Z",
  "priority": "high"
}

Calendar Events

Manage events in Calendar-type channels. Create, update, and manage event participants.

{
  "channelId": "calendar-channel-id",
  "title": "Game Night",
  "description": "Weekly gaming session",
  "startTime": "2026-04-01T20:00:00Z",
  "endTime": "2026-04-01T23:00:00Z",
  "location": "Voice Channel #gaming",
  "isAllDay": false
}

Event Participants

{ "userId": "user-id" }

{ "userId": "user-id" }

Search

Audit Logs

Read the server audit log to enrich a mod-log channel, build moderation dashboards, or reconcile bot actions with admin actions.

{
  "logs": [
    {
      "timestamp": "2026-04-28T17:20:00Z",
      "logId": "log-id",
      "actorId": "bot-id",
      "action": "timeout_member",
      "targetType": "member",
      "targetId": "user-id",
      "reason": "Spamming",
      "details": { "durationSeconds": 300 }
    }
  ],
  "count": 1,
  "serverId": "server-id",
  "botId": "bot-id"
}

Directory & Installs

The public bot directory, and the calls a server admin makes to add or remove a bot. The install routes take a user login with MANAGE_SERVER, not a bot key — a bot cannot add itself anywhere. For an "Add to server" button on your own website, use the OAuth2 invite-bot endpoint instead.

{
  "bots": [
    {
      "id": "bot-id",
      "name": "Panda",
      "avatar": "https://…",
      "description": "Levels, moderation, music…",
      "tags": ["moderation", "music"],
      "developer": "…",
      "website": "https://…",
      "official": true,
      "requestedPermissions": 4352
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 37, "totalPages": 2 }
}

{ "botUserId": "bot-id", "grantedPermissions": 4352 }

WebSocket Events

Connect via Socket.IO at https://socket.echoed.gg to receive real-time events. Authenticate with your bot token after connecting; on success the bot is auto-subscribed to every server it's invited to — no separate subscribe step is required.

Connecting

// npm install socket.io-client
import { io } from "socket.io-client";

const socket = io("https://socket.echoed.gg", {
    transports: ["websocket"],
});

socket.on("connect", () => {
    socket.emit("authenticate", {
        botToken: "zbot_your_token_here",
    });
});

socket.on("authenticated", (payload) => {
    console.log("Bot ready, sessionId:", payload.sessionId);
});

# pip install python-socketio[client]
import socketio

sio = socketio.Client()

@sio.on("connect")
def on_connect():
    sio.emit("authenticate", {"botToken": "zbot_your_token_here"})

sio.connect("https://socket.echoed.gg")
sio.wait()

Heartbeat

Send a heartbeat every 30 seconds to keep the connection alive. The token must be included on every heartbeat.

setInterval(() => {
    socket.emit("heartbeat", { botToken: "zbot_your_token_here" });
}, 30000);

Event Types

Each Socket.IO event name is the literal event below (e.g. MESSAGE_CREATE). The payload is the event data directly — not wrapped in a {type, data} envelope. Listen for events by name:

socket.on("MESSAGE_CREATE", (data) => {
    // data.id, data.channelId, data.senderId, data.content, ...
    if (data.senderId === botUserId) return; // ignore own messages
    handleMessage(data);
});

Available Events

MESSAGE_CREATE Payload

{
  "id": "message-id",
  "channelId": "channel-id",
  "serverId": "server-id",
  "senderId": "user-id",
  "content": "Hello everyone!",
  "messageType": "user",
  "attachments": [],
  "mentions": [],
  "replyToId": "",
  "createdAt": "2026-04-28T17:00:00Z",
  "author": {
    "id": "user-id",
    "name": "Username",
    "avatarUrl": "https://...",
    "isBot": false
  }
}

Incoming Webhooks

A webhook is a secret URL that posts into one channel. No bot account, no socket, no review: anything that can make an HTTP request can use one. Good for CI results, deploy notices, monitoring alerts and RSS-style feeds. For anything that needs to read or react, write a bot.

Create one in the app under Server Settings → Webhooks (or Webhooks in a channel's right-click menu) and copy its URL. The URL contains the token, so whoever has it can post as the webhook.

{
  "content": "Deploy finished",
  "username": "CI",
  "avatar_url": "https://example.com/ci.png",
  "embeds": [
    {
      "title": "api v2.14.0",
      "description": "All checks passed in 4m 12s",
      "url": "https://ci.example.com/runs/812",
      "color": 4886754,
      "fields": [{ "name": "Branch", "value": "main", "inline": true }]
    }
  ]
}

{ "success": true, "messageId": "message-id" }

curl -X POST "https://go.echoed.gg/api/webhooks/$ID/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Build #812 passed"}'

Managing Webhooks

These take a user login with MANAGE_SERVER. Every webhook in the response carries its ready-to-use url.

{
  "success": true,
  "webhooks": [
    {
      "webhookId": "webhook-id",
      "channelId": "channel-id",
      "name": "CI",
      "avatar": "https://…",
      "token": "…",
      "creatorId": "user-id",
      "createdAt": "2026-09-27T12:00:00Z",
      "url": "https://go.echoed.gg/api/webhooks/webhook-id/…"
    }
  ]
}

OAuth2

Integrate "Login with Echoed" into your application, access user data, and invite bots to servers using the standard OAuth2 authorization code flow. The same OAuth2 app is also how you publish games.

Panda's dashboard is a working example: a Next.js app that signs people in with Echoed and reads their profile and servers from /oauth2/userinfo. The whole flow is in dashboard/lib/echoed.ts.

Authorization Flow

1. Register an OAuth2 app in Settings → Developer → OAuth2 Apps and add your redirect URIs. The client secret is shown once — copy it then, or regenerate it later from the app
2. Send the user to the authorization URL with your client_id and the scopes you need
3. Echoed shows its consent screen, signing the user in first if needed. On approval it redirects back with an authorization code and your state
4. Exchange the code for an access token (and a refresh token with offline_access)
5. Use the access token to call the OAuth2 API endpoints

If the user denies, or the request is invalid, the redirect carries error and error_description instead of a code. Always check that state matches the one you sent.

https://go.echoed.gg/oauth2/authorize?
  response_type=code&
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  scope=openid profile email servers&
  state=random_csrf_token

This URL forwards to the consent screen on the Echoed web app. Link to it rather than to the consent page directly, so your integration keeps working if that page moves.

POST https://go.echoed.gg/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=authorization_code_from_callback&
redirect_uri=https://yourapp.com/callback&
client_id=your_client_id&
client_secret=your_client_secret

{
  "access_token": "MKquTIm08LMU...",
  "refresh_token": "dR4nG7kP...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

POST https://go.echoed.gg/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=dR4nG7kP...&
client_id=your_client_id&
client_secret=your_client_secret

PKCE (apps without a server)

A single-page or mobile app cannot keep a client secret. Register it with client type Public and use PKCE: generate a random code_verifier, send its SHA-256 as code_challenge with code_challenge_method=S256 on the authorization URL, then send the code_verifier (and no secret) when exchanging the code. plain is accepted but gives no protection — use S256.

const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = base64url(new Uint8Array(
  await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))
));
// authorize: ...&code_challenge=${challenge}&code_challenge_method=S256
// token:     grant_type=authorization_code&code=...&client_id=...&code_verifier=${verifier}

Scopes

Token Lifetimes

OAuth2 Endpoints

{
  "sub": "user-id",
  "name": "Display Name",
  "username": "username",
  "avatar_url": "https://s3.echoed.gg/...",
  "email": "user@example.com",
  "owned_servers": [
    { "id": "server-id", "name": "My Server", "type": "public" }
  ],
  "servers_count": 5
}

{ "bot_id": "bot-user-id" }

token=access_token_value&
token_type_hint=access_token&
client_id=your_client_id&
client_secret=your_client_secret

{
  "active": true,
  "client_id": "your_client_id",
  "username": "username",
  "scope": "openid profile servers",
  "token_type": "Bearer",
  "exp": 1790000000
}

Games

Echoed runs games inside chats. People start one in a DM, or together in a server's game lounge, where the room votes on what to play and anyone not seated can watch. Your game is a web page that Echoed embeds, plus a small backend of yours that talks to Echoed.

You never receive a player's Echoed login. Your backend gets a short-lived session token for one player in one match, and that player's public profile: id, username, display name and avatar.

How a match runs

1. A player launches your game. Echoed opens your embed URL in a sandboxed iframe with a launch token in the URL fragment.
2. Your page sends the launch token to your backend. It is single-use and expires after 3 minutes.
3. Your backend exchanges it using your client credentials, and learns who the player is, which game and match this is, who is seated, and whether this connection is a player or a spectator.
4. You run the game however you like. Everyone launched into the same match gets the same match id, so group connections by it.
5. When the match ends, your backend reports each player's result. Echoed records it on the leaderboards and shows it where the match was played.

Register a Game

1. In Echoed, open Settings → Developer → OAuth2 Apps and create an app with the Games scope ticked. Copy the client secret now: it is shown once. If you lose it, regenerate it from the key button on the app.
2. Press the gamepad button on the app and add a game. One app can publish many games; each gets its own game id.

Visibility. Your games work for you straight away, so you can test them in your own DMs. They appear for everyone else — in the DM picker and in lounge votes — once the app is public and approved in review.

Your Game Page

Echoed loads your embed URL with everything in the fragment:

<embedUrl>#launch=<launchToken>&match=<matchId>[&rematch=1]&theme=<dark|light>

The iframe has sandbox="allow-scripts allow-same-origin allow-forms" and allow="autoplay; fullscreen". The token is in the fragment so it never reaches a server log. Read it from location.hash, send it to your backend, and don't store it: it is useless once exchanged. theme is the player's Echoed light or dark mode — match it if you can.

const params = new URLSearchParams(location.hash.slice(1));
const launchToken = params.get("launch");
const matchId = params.get("match");
document.documentElement.dataset.theme = params.get("theme") || "dark";

// Hand the token to YOUR backend; it does the exchange.
const socket = io("https://games.example.com", { auth: { launchToken, matchId } });

Echoed listens for one message from your page:

Player Counts

Your min and max players decide where your game can be played:

In a lounge the room votes on games whose minimum it meets. If more people want to play than your maximum, the earliest to join are seated and the rest watch (if you support spectators). match.players always holds exactly the seated players, so a 2–4 player game may get 2, 3 or 4 — size the game to it. If someone leaves a game of three or more partway through, decide whether the others play on; report the leaver as loss either way.

Launch Token Exchange

POST https://go.echoed.gg/games/auth/exchange
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

{ "launchToken": "…" }

{
  "sessionToken": "…",
  "expiresIn": 7200,
  "role": "player",
  "player": { "id": "u_1", "username": "siam", "displayName": "Siam", "avatarUrl": "https://…" },
  "game":   { "id": "game_abc", "name": "Chess", "embedUrl": "https://games.example/play?game=chess" },
  "match": {
    "id": "m_123",
    "mode": "multiplayer",
    "context": { "type": "lounge", "id": "…" },
    "players": ["u_1", "u_2"]
  }
}

• role is player or spectator. Stream a spectator the game and refuse their input; Echoed refuses score reports from spectator sessions.
• match.players is the seat order, the same for every connection to the match. Seat 0 is players[0].
• match.mode is solo for a one-player run.
• match.context.type is dm or lounge. You don't have to treat them differently.
• game.id says which of your games was launched. If one backend hosts several, route on it or on game.embedUrl — both come from your registration, so a player can't change them. Never route on anything the page tells you.

The response also carries gameId and a session object, kept for compatibility with the preview API. They hold the same values; use game and match.

Reporting Results

POST https://go.echoed.gg/games/scores
Authorization: Bearer <sessionToken>
Content-Type: application/json

{ "outcome": "win", "score": 0 }

What happens next depends on where the match was played:

• DM — the first report posts a result card into the conversation ("Siam won!", "It's a draw!").
• Solo — the card shows the score, and says so when it is a new best in that chat.
• Lounge — the match ends when a win or draw is reported, or when every seated player has reported. The whole room sees the result together and can share it to a channel or start the next vote. In a game of more than two, report eliminated players as loss when they are knocked out and the winner as win at the end.

Leaderboards

Echoed keeps two for every game, and players see both in the game view: a global board of everyone who has played it, and a board for this chat / this lounge with only the matches played there. Multiplayer games rank by wins; games with a maximum of one player rank by best score. You don't have to do anything to get them — they come from your score reports.

Errors & Limits

Every error is { "error": "…" } with a status code.

Limits: 120 exchanges and 300 score reports per minute from one IP address.

Rules

• Keep the client secret on your server. Exchange and report only from there.
• Referee the game on your server. Echoed trusts your backend's report, so nothing a player's browser says should decide it.
• You get a player's id, username, display name and avatar. Nothing else.
• Serve your page over HTTPS.

Endpoint Reference

The other /games routes (launching, lounge sessions, leaderboards, share cards) are called by the Echoed app on the player's behalf. A game never needs them.