> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Discord

> Test a Discord bot against REST API v10 for channels, messages, replies, threads, reactions, pins, members and direct messages.

The Discord replica implements 25 REST API v10 endpoints. Your agent acts as a bot in one community server. Its role and each channel's permission overwrites decide what it can read and send. Its key is `discord`.

## Connect

| Variable | Value |
| - | - |
| `DISCORD_API_URL` | Base URL ending in `/api/v10`. Append paths such as `/users/@me`. |
| `DISCORD_BOT_TOKEN` | Fake bot token. Send `Authorization: Bot <token>`. |

```ts TypeScript theme={null}
const discord = (path: string, init: RequestInit = {}) => fetch(`${process.env.DISCORD_API_URL}${path}`, { ...init, headers: { Authorization: `Bot ${process.env.DISCORD_BOT_TOKEN}`, 'Content-Type': 'application/json' } }).then(r => r.json());
const [guild] = await discord('/users/@me/guilds');
const help = (await discord(`/guilds/${guild.id}/channels`)).find((c: any) => c.name === 'help');
const [latest] = await discord(`/channels/${help.id}/messages?limit=1`);
await discord(`/channels/${help.id}/messages`, { method: 'POST', body: JSON.stringify({ content: 'Looking into it now.', message_reference: { message_id: latest.id } }) });
```

This is what `ancha connect discord --lang ts` prints. It uses REST requests; the replica does not provide Gateway events.

## Endpoints

| Method | Path | Support |
| - | - | - |
| `GET` | `/api/v10/users/@me` | partial |
| `GET` | `/api/v10/users/@me/guilds` | partial |
| `POST` | `/api/v10/users/@me/channels` | partial: a DM with a member of the guild |
| `GET` | `/api/v10/users/{user_id}` | partial |
| `GET` | `/api/v10/guilds/{guild_id}` | partial: `with_counts` |
| `GET` | `/api/v10/guilds/{guild_id}/channels` | partial |
| `GET` | `/api/v10/guilds/{guild_id}/members` | partial: `limit` and `after`, by user ID |
| `GET` | `/api/v10/guilds/{guild_id}/members/{user_id}` | partial |
| `GET` | `/api/v10/guilds/{guild_id}/roles` | partial |
| `GET` | `/api/v10/guilds/{guild_id}/threads/active` | partial |
| `GET` | `/api/v10/channels/{channel_id}` | partial: Missing Access where the bot may not view the channel |
| `GET` | `/api/v10/channels/{channel_id}/messages` | partial: newest first; `before`, `after` or `around`; nothing without Read Message History |
| `POST` | `/api/v10/channels/{channel_id}/messages` | partial: content, embeds and replies (`message_reference`), checked against the bot’s role and the channel’s overwrites; attachments, components and polls are gaps |
| `GET` | `/api/v10/channels/{channel_id}/messages/{message_id}` | partial |
| `PATCH` | `/api/v10/channels/{channel_id}/messages/{message_id}` | partial: the bot’s own messages |
| `DELETE` | `/api/v10/channels/{channel_id}/messages/{message_id}` | partial: the bot’s own, or any with Manage Messages |
| `PUT` | `/api/v10/channels/{channel_id}/messages/{message_id}/reactions/{emoji}/@me` | partial: Unicode emoji |
| `DELETE` | `/api/v10/channels/{channel_id}/messages/{message_id}/reactions/{emoji}/@me` | partial |
| `GET` | `/api/v10/channels/{channel_id}/messages/{message_id}/reactions/{emoji}` | partial |
| `POST` | `/api/v10/channels/{channel_id}/messages/{message_id}/threads` | partial: the thread takes the message’s ID |
| `POST` | `/api/v10/channels/{channel_id}/threads` | partial: public threads |
| `GET` | `/api/v10/channels/{channel_id}/pins` | partial |
| `PUT` | `/api/v10/channels/{channel_id}/pins/{message_id}` | partial: needs Manage Messages |
| `DELETE` | `/api/v10/channels/{channel_id}/pins/{message_id}` | partial |
| `POST` | `/api/v10/channels/{channel_id}/typing` | partial |

Run `ancha twins coverage discord` for the endpoint notes. Calls outside the coverage return Discord's error shape with `x-ancha-gap: 1`.

## Starter data

The `discord-starter` dataset is **Acme Community**. The bot is `acme_assistant`, shown as **Acme Assistant**. Ten people belong to the server, with Acme Staff and Beta testers roles.

| Channel | Starting conversation |
| - | - |
| `#announcements` | Ellen's October product update, with reactions. The bot cannot post here. |
| `#general` | Dispatch Dan and Megan discuss CSV exports for fleet reports. |
| `#help` | Lucy asks about Okta SSO and Laura replies. Erin asks where to find last month's CSV export. |
| `#feature-requests` | Nora requests dark mode, with votes and a thread from Ellen. Carla requests scheduled reports. |
| `#beta-scheduled-reports` | A pinned welcome from Ellen. The bot can view this restricted channel. |
| `#staff` | Mike notes that Erin also asked about the export in `#help`. The bot can view it. |
| `#moderators` | A staff-only reminder. The bot cannot view this channel. |

The channels sit under the info, community and acme-team categories. `ancha sandbox configuration --tools discord --json` prints their permissions, messages and threads.

## Checks

Discord has no state checks. Use [trace checks](https://docs.ancha.io/concepts/checks.md#trace-patterns), for example `{ called: "POST /api/v10/channels/*/messages" }` or `{ not_called: "DELETE /api/v10/channels/*/messages/*" }`.

## Limits

* REST only: no Gateway events, slash commands, webhooks or voice.
* Attachments, components and polls are coverage gaps.
* Sending and reading follow the bot's permissions. Editing is limited to the bot's own messages; deleting someone else's message and pinning need Manage Messages.
* Reactions use Unicode emoji. New threads are public.


## Related topics

- [Tools](https://docs.ancha.io/tools/overview.md)
- [Introduction](https://docs.ancha.io/index.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)
- [Changelog](https://docs.ancha.io/changelog.md)
- [ancha connect](https://docs.ancha.io/cli/connect.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.