Discord

The io.b3os/discord pack: 8 actions with call snippets, fixture outputs, connection setup and error codes, generated from version 1.0.0.

io.b3os/discord 1.0.0 · messaging, community · MIT

Post, read, edit, react to and delete messages, start threads, and list a server's channels with your own Discord bot's token (API v10). The bot must be in the server with permission for each channel (View Channel, Send Messages, Read Message History, Add Reactions, Manage Messages to delete others' messages). Reading message content needs the Message Content intent enabled for the bot.

Every call's result carries upstream_status and timing: validate_ms, inject_ms, render_ms, upstream_ms, map_ms and total_ms. upstream is the service's time; the others are B3OS's own (call actions). The snippets below show no timing values, because a fixture records none.

Connection

bot, type api_key: Discord bot token.

The token of your own bot from the Discord Developer Portal (Applications, Bot, Reset Token). It is sent as Authorization: Bot <token>.

How to get one: discord.com.

The credential is sent only to discord.com.

Store the credential once as a vault connection for this pack and key, then name its id in a call's connections. Leave the key out and B3OS uses the project's newest connection for the pack and key without a subject (connections).

Hosts it reaches: discord.com.

Actions

Action	Effect	MCP tool	Title
`get-bot-user`	read	`discord__get-bot-user`	Get bot user
`send-message`	write	`discord__send-message`	Send message
`get-messages`	read	`discord__get-messages`	Get messages
`edit-message`	write	`discord__edit-message`	Edit message
`delete-message`	irreversible	`discord__delete-message`	Delete message
`add-reaction`	write	`discord__add-reaction`	Add reaction
`create-thread`	write	`discord__create-thread`	Start thread from message
`list-guild-channels`	read	`discord__list-guild-channels`	List server channels

`get-bot-user`

Get bot user. The bot's own user: id, username and display name. A cheap way to check the token.

Ref io.b3os/discord/get-bot-user@1.0.0 · effect read · connection bot · MCP tool discord__get-bot-user

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/discord/get-bot-user@1",      "input": {},      "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/discord/get-bot-user@1",  input: {},  connections: { bot: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },});console.log(result.output);

python
from b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/discord/get-bot-user@1",    "input": {},    "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},})print(result["output"])

json
{  "method": "tools/call",  "params": {"name": "discord__get-bot-user", "arguments": {}}}

Expose the pack as tools with --packs discord on the local server or ?packs=discord on the remote URL, and the agent calls discord__get-bot-user with the action's input. The tool uses your newest connection for each key without a subject. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: Get bot user (documented response shape, example values). From the bundle's fixtures/get-bot-user.json, not a live call.

json
{  "id": "1193000000000000001",  "username": "deploybot",  "global_name": "Deploy Bot",  "bot": true}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404	no	built from the service's response
`connection_unauthorized`	401	no	Discord rejected the bot token.
`forbidden`	403	no	built from the service's response
`rate_limited`	429	yes	built from the service's response
`invalid_request`	400	no	built from the service's response

`send-message`

Send message. Post a message (up to 2,000 characters of Discord Markdown) in a text channel or thread, optionally as a reply. Mentions in the text do not ping anyone unless allow_mentions is true. Returns the message id. Not idempotent.

Ref io.b3os/discord/send-message@1.0.0 · effect write · connection bot · MCP tool discord__send-message

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Idempotency-Key: 7c1e2f6a-1d43-4a8e-b2a5-3f0c9d5e8b11" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/discord/send-message@1",      "input": {        "channel_id": "1192000000000000001",        "content": "Deploy finished: **v2.4.0** is live."      },      "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/discord/send-message@1",  input: {    channel_id: "1192000000000000001",    content: "Deploy finished: **v2.4.0** is live.",  },  connections: { bot: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },}, { idempotencyKey: crypto.randomUUID() });console.log(result.output);

python
import uuidfrom b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/discord/send-message@1",    "input": {        "channel_id": "1192000000000000001",        "content": "Deploy finished: **v2.4.0** is live.",    },    "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},}, idempotency_key=str(uuid.uuid4()))print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "discord__send-message",    "arguments": {      "channel_id": "1192000000000000001",      "content": "Deploy finished: **v2.4.0** is live."    }  }}

Expose the pack as tools with --packs discord on the local server or ?packs=discord on the remote URL, and the agent calls discord__send-message with the action's input. The tool uses your newest connection for each key without a subject. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: Send message (documented response shape, example values). From the bundle's fixtures/send-message.json, not a live call.

json
{  "id": "1194000000000000001",  "channel_id": "1192000000000000001",  "author": "deploybot",  "author_id": "1193000000000000001",  "content": "Deploy finished: **v2.4.0** is live.",  "timestamp": "2026-10-26T08:00:00.000000+00:00",  "edited_timestamp": null,  "attachments": [],  "thread_id": null}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404	no	built from the service's response
`connection_unauthorized`	401	no	Discord rejected the bot token.
`forbidden`	403	no	built from the service's response
`rate_limited`	429	yes	built from the service's response
`invalid_request`	400	no	built from the service's response

`get-messages`

Get messages. Recent messages in a channel, newest first (up to 100), or those before or after a message id for paging. Content is empty unless the bot has the Message Content intent.

Ref io.b3os/discord/get-messages@1.0.0 · effect read · connection bot · MCP tool discord__get-messages

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/discord/get-messages@1",      "input": {"channel_id": "1192000000000000001", "limit": 2},      "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/discord/get-messages@1",  input: { channel_id: "1192000000000000001", limit: 2 },  connections: { bot: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },});console.log(result.output);

python
from b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/discord/get-messages@1",    "input": {"channel_id": "1192000000000000001", "limit": 2},    "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},})print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "discord__get-messages",    "arguments": {"channel_id": "1192000000000000001", "limit": 2}  }}

Expose the pack as tools with --packs discord on the local server or ?packs=discord on the remote URL, and the agent calls discord__get-messages with the action's input. The tool uses your newest connection for each key without a subject. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: Get messages (documented response shape, example values). From the bundle's fixtures/get-messages.json, not a live call.

json
{  "messages": [    {      "id": "1194000000000000002",      "channel_id": "1192000000000000001",      "author": "mona",      "author_id": "1193000000000000002",      "content": "Rolling back.",      "timestamp": "2026-10-26T08:00:00.000000+00:00",      "edited_timestamp": null,      "attachments": [],      "thread_id": null    },    {      "id": "1194000000000000001",      "channel_id": "1192000000000000001",      "author": "deploybot",      "author_id": "1193000000000000001",      "content": "Deploy finished: **v2.4.0** is live.",      "timestamp": "2026-10-26T08:00:00.000000+00:00",      "edited_timestamp": null,      "attachments": [],      "thread_id": "1195000000000000001"    }  ]}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404	no	built from the service's response
`connection_unauthorized`	401	no	Discord rejected the bot token.
`forbidden`	403	no	built from the service's response
`rate_limited`	429	yes	built from the service's response
`invalid_request`	400	no	built from the service's response

`edit-message`

Edit message. Replace the text of a message the bot posted.

Ref io.b3os/discord/edit-message@1.0.0 · effect write · connection bot · MCP tool discord__edit-message

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Idempotency-Key: 7c1e2f6a-1d43-4a8e-b2a5-3f0c9d5e8b11" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/discord/edit-message@1",      "input": {        "channel_id": "1192000000000000001",        "message_id": "1194000000000000001",        "content": "Deploy finished: **v2.4.1** is live."      },      "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/discord/edit-message@1",  input: {    channel_id: "1192000000000000001",    message_id: "1194000000000000001",    content: "Deploy finished: **v2.4.1** is live.",  },  connections: { bot: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },}, { idempotencyKey: crypto.randomUUID() });console.log(result.output);

python
import uuidfrom b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/discord/edit-message@1",    "input": {        "channel_id": "1192000000000000001",        "message_id": "1194000000000000001",        "content": "Deploy finished: **v2.4.1** is live.",    },    "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},}, idempotency_key=str(uuid.uuid4()))print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "discord__edit-message",    "arguments": {      "channel_id": "1192000000000000001",      "message_id": "1194000000000000001",      "content": "Deploy finished: **v2.4.1** is live."    }  }}

Expose the pack as tools with --packs discord on the local server or ?packs=discord on the remote URL, and the agent calls discord__edit-message with the action's input. The tool uses your newest connection for each key without a subject. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: Edit message (documented response shape, example values). From the bundle's fixtures/edit-message.json, not a live call.

json
{  "id": "1194000000000000001",  "channel_id": "1192000000000000001",  "author": "deploybot",  "author_id": "1193000000000000001",  "content": "Deploy finished: **v2.4.1** is live.",  "timestamp": "2026-10-26T08:00:00.000000+00:00",  "edited_timestamp": "2026-10-26T08:05:00.000000+00:00",  "attachments": [],  "thread_id": null}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404	no	built from the service's response
`connection_unauthorized`	401	no	Discord rejected the bot token.
`forbidden`	403	no	built from the service's response
`rate_limited`	429	yes	built from the service's response
`invalid_request`	400	no	built from the service's response

`delete-message`

Delete message. Delete a message. The bot can delete its own messages; others' need Manage Messages. Cannot be undone.

Ref io.b3os/discord/delete-message@1.0.0 · effect irreversible · connection bot · MCP tool discord__delete-message

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Idempotency-Key: 7c1e2f6a-1d43-4a8e-b2a5-3f0c9d5e8b11" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/discord/delete-message@1",      "input": {        "channel_id": "1192000000000000001",        "message_id": "1194000000000000001"      },      "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/discord/delete-message@1",  input: {    channel_id: "1192000000000000001",    message_id: "1194000000000000001",  },  connections: { bot: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },}, { idempotencyKey: crypto.randomUUID() });console.log(result.output);

python
import uuidfrom b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/discord/delete-message@1",    "input": {        "channel_id": "1192000000000000001",        "message_id": "1194000000000000001",    },    "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},}, idempotency_key=str(uuid.uuid4()))print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "discord__delete-message",    "arguments": {      "channel_id": "1192000000000000001",      "message_id": "1194000000000000001"    }  }}

Expose the pack as tools with --packs discord on the local server or ?packs=discord on the remote URL, and the agent calls discord__delete-message with the action's input. The tool uses your newest connection for each key without a subject. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: Delete message (documented response shape, example values). From the bundle's fixtures/delete-message.json, not a live call.

json
{"deleted": true, "message_id": "1194000000000000001"}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404	no	built from the service's response
`connection_unauthorized`	401	no	Discord rejected the bot token.
`forbidden`	403	no	built from the service's response
`rate_limited`	429	yes	built from the service's response
`invalid_request`	400	no	built from the service's response

`add-reaction`

Add reaction. React to a message with a Unicode emoji (for example a check mark) or a custom server emoji written name:id.

Ref io.b3os/discord/add-reaction@1.0.0 · effect write · connection bot · MCP tool discord__add-reaction

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Idempotency-Key: 7c1e2f6a-1d43-4a8e-b2a5-3f0c9d5e8b11" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/discord/add-reaction@1",      "input": {        "channel_id": "1192000000000000001",        "message_id": "1194000000000000001",        "emoji": "✅"      },      "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/discord/add-reaction@1",  input: {    channel_id: "1192000000000000001",    message_id: "1194000000000000001",    emoji: "✅",  },  connections: { bot: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },}, { idempotencyKey: crypto.randomUUID() });console.log(result.output);

python
import uuidfrom b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/discord/add-reaction@1",    "input": {        "channel_id": "1192000000000000001",        "message_id": "1194000000000000001",        "emoji": "✅",    },    "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},}, idempotency_key=str(uuid.uuid4()))print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "discord__add-reaction",    "arguments": {      "channel_id": "1192000000000000001",      "message_id": "1194000000000000001",      "emoji": "✅"    }  }}

Expose the pack as tools with --packs discord on the local server or ?packs=discord on the remote URL, and the agent calls discord__add-reaction with the action's input. The tool uses your newest connection for each key without a subject. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: Add reaction (documented response shape, example values). From the bundle's fixtures/add-reaction.json, not a live call.

json
{"reacted": true}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404	no	built from the service's response
`connection_unauthorized`	401	no	Discord rejected the bot token.
`forbidden`	403	no	built from the service's response
`rate_limited`	429	yes	built from the service's response
`invalid_request`	400	no	built from the service's response

`create-thread`

Start thread from message. Start a public thread from an existing message, with a name and an auto-archive time (1 hour to 1 week of inactivity). Returns the thread id, which send-message accepts as a channel.

Ref io.b3os/discord/create-thread@1.0.0 · effect write · connection bot · MCP tool discord__create-thread

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Idempotency-Key: 7c1e2f6a-1d43-4a8e-b2a5-3f0c9d5e8b11" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/discord/create-thread@1",      "input": {        "channel_id": "1192000000000000001",        "message_id": "1194000000000000001",        "name": "v2.4.0 follow-up"      },      "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/discord/create-thread@1",  input: {    channel_id: "1192000000000000001",    message_id: "1194000000000000001",    name: "v2.4.0 follow-up",  },  connections: { bot: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },}, { idempotencyKey: crypto.randomUUID() });console.log(result.output);

python
import uuidfrom b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/discord/create-thread@1",    "input": {        "channel_id": "1192000000000000001",        "message_id": "1194000000000000001",        "name": "v2.4.0 follow-up",    },    "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},}, idempotency_key=str(uuid.uuid4()))print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "discord__create-thread",    "arguments": {      "channel_id": "1192000000000000001",      "message_id": "1194000000000000001",      "name": "v2.4.0 follow-up"    }  }}

Expose the pack as tools with --packs discord on the local server or ?packs=discord on the remote URL, and the agent calls discord__create-thread with the action's input. The tool uses your newest connection for each key without a subject. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: Start thread from message (documented response shape, example values). From the bundle's fixtures/create-thread.json, not a live call.

json
{  "id": "1195000000000000001",  "name": "v2.4.0 follow-up",  "parent_id": "1192000000000000001"}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404	no	built from the service's response
`connection_unauthorized`	401	no	Discord rejected the bot token.
`forbidden`	403	no	built from the service's response
`rate_limited`	429	yes	built from the service's response
`invalid_request`	400	no	built from the service's response

`list-guild-channels`

List server channels. The channels of a server (guild): id, name, type (0 text, 2 voice, 4 category, 5 announcement, 15 forum), parent category and position. Threads are not included.

Ref io.b3os/discord/list-guild-channels@1.0.0 · effect read · connection bot · MCP tool discord__list-guild-channels

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/discord/list-guild-channels@1",      "input": {"guild_id": "1191000000000000001"},      "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/discord/list-guild-channels@1",  input: { guild_id: "1191000000000000001" },  connections: { bot: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },});console.log(result.output);

python
from b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/discord/list-guild-channels@1",    "input": {"guild_id": "1191000000000000001"},    "connections": {"bot": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},})print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "discord__list-guild-channels",    "arguments": {"guild_id": "1191000000000000001"}  }}

Expose the pack as tools with --packs discord on the local server or ?packs=discord on the remote URL, and the agent calls discord__list-guild-channels with the action's input. The tool uses your newest connection for each key without a subject. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: List server channels (documented response shape, example values). From the bundle's fixtures/list-guild-channels.json, not a live call.

json
{  "channels": [    {      "id": "1192000000000000000",      "name": "Engineering",      "type": 4,      "parent_id": null,      "position": 0,      "topic": null    },    {      "id": "1192000000000000001",      "name": "deploys",      "type": 0,      "parent_id": "1192000000000000000",      "position": 1,      "topic": "Release train"    }  ]}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404	no	built from the service's response
`connection_unauthorized`	401	no	Discord rejected the bot token.
`forbidden`	403	no	built from the service's response
`rate_limited`	429	yes	built from the service's response
`invalid_request`	400	no	built from the service's response

Was this page helpful?

Previous DEX Screener

Next Finnhub