Serve Actions

When running discli serve, you send JSON objects (one per line) to stdin. Every action must include an "action" field. An optional "req_id" field will be echoed back in the response for correlation.

General request format:

{"action": "<action_name>", "req_id": "optional-correlation-id", ...fields}

General response format:

{"event": "response", "status": "ok", "req_id": "1", ...result_fields}

On error, the response contains an "error" field instead of "ok":

{"event": "response", "error": "Channel not found: 999", "req_id": "1"}

Messaging

send

Send a message to a channel.

Request:

{"action": "send", "channel_id": "123456", "content": "Hello!", "req_id": "1"}

Response:

{"event": "response", "ok": true, "message_id": "789", "req_id": "1"}

Field	Required	Type	Description
`channel_id`	yes	string	Target channel ID
`content`	no	string	Message text
`embed`	no	object	Embed object (see Embeds)
`components`	no	array	Message components (see Components)
`files`	no	string[]	Local file paths to attach
`req_id`	no	string	Correlation ID

reply

Reply to a specific message.

Request:

{"action": "reply", "channel_id": "123456", "message_id": "111", "content": "Got it!", "req_id": "2"}

Response:

{"event": "response", "ok": true, "message_id": "222", "req_id": "2"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel containing the message
`message_id`	yes	string	Message to reply to
`content`	no	string	Reply text
`embed`	no	object	Embed object (see Embeds)
`components`	no	array	Message components (see Components)
`files`	no	string[]	Local file paths to attach
`req_id`	no	string	Correlation ID

edit

Edit an existing message (must be authored by the bot).

Request:

{"action": "edit", "channel_id": "123456", "message_id": "789", "content": "Updated text", "req_id": "3"}

Response:

{"event": "response", "ok": true, "req_id": "3"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel containing the message
`message_id`	yes	string	Message to edit
`content`	no	string	New message content
`req_id`	no	string	Correlation ID

delete

Delete a message.

Request:

{"action": "delete", "channel_id": "123456", "message_id": "789", "req_id": "4"}

Response:

{"event": "response", "ok": true, "req_id": "4"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel containing the message
`message_id`	yes	string	Message to delete
`req_id`	no	string	Correlation ID

message_pin

Pin a message in a channel.

Request:

{"action": "message_pin", "channel_id": "123456", "message_id": "789", "req_id": "5"}

Response:

{"event": "response", "ok": true, "req_id": "5"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel containing the message
`message_id`	yes	string	Message to pin
`req_id`	no	string	Correlation ID

message_unpin

Unpin a message in a channel.

Request:

{"action": "message_unpin", "channel_id": "123456", "message_id": "789", "req_id": "6"}

Response:

{"event": "response", "ok": true, "req_id": "6"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel containing the message
`message_id`	yes	string	Message to unpin
`req_id`	no	string	Correlation ID

message_bulk_delete

Delete multiple messages at once.

Request:

{"action": "message_bulk_delete", "channel_id": "123456", "message_ids": ["789", "790"], "req_id": "7"}

Response:

{"event": "response", "ok": true, "req_id": "7"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel containing the messages
`message_ids`	yes	string[]	Message IDs to delete
`req_id`	no	string	Correlation ID

Embeds in send / reply

The embed field in send and reply accepts an object with the following structure:

{
  "action": "send",
  "channel_id": "123456",
  "content": "Check this out",
  "embed": {
    "title": "My Embed",
    "description": "A description",
    "color": "5865F2",
    "footer": "Footer text",
    "image": "https://example.com/image.png",
    "thumbnail": "https://example.com/thumb.png",
    "author": {"name": "Author Name", "icon_url": "https://example.com/icon.png"},
    "fields": [{"name": "Field", "value": "Value", "inline": true}]
  }
}

Field	Required	Type	Description
`title`	no	string	Embed title
`description`	no	string	Embed description
`color`	no	string	Hex color (e.g. `5865F2`)
`footer`	no	string	Footer text
`image`	no	string	Image URL
`thumbnail`	no	string	Thumbnail URL
`author`	no	object	Author with `name` and optional `icon_url`
`fields`	no	array	List of `{"name", "value", "inline"}` objects

Components in send / reply

The components field in send and reply accepts an array of action rows. Each action row is an array of component objects.

{
  "action": "send",
  "channel_id": "123456",
  "content": "Pick an option",
  "components": [
    [{"type": "button", "label": "OK", "style": "primary", "custom_id": "ok"}],
    [{"type": "select", "custom_id": "pick", "placeholder": "Choose...", "options": [{"label": "A", "value": "a"}]}],
    [{"type": "user_select", "custom_id": "user", "placeholder": "Pick user..."}],
    [{"type": "role_select", "custom_id": "role", "placeholder": "Pick role..."}],
    [{"type": "channel_select", "custom_id": "ch", "placeholder": "Pick channel..."}]
  ]
}

Supported component types:

Type	Fields	Description
`button`	`label`, `style`, `custom_id`	Button. Styles: `primary`, `secondary`, `success`, `danger`
`select`	`custom_id`, `placeholder`, `options`	String select menu. Options: `[{"label", "value"}]`
`user_select`	`custom_id`, `placeholder`	User select menu
`role_select`	`custom_id`, `placeholder`	Role select menu
`channel_select`	`custom_id`, `placeholder`	Channel select menu

Streaming

Streaming lets you send a response that updates in real-time (e.g., token-by-token LLM output). The flow is: stream_start to create a placeholder message, stream_chunk to append text, and stream_end to finalize. The message is flushed to Discord every 1.5 seconds during streaming.

stream_start

Start a streaming message. Creates a placeholder message ("...") in the channel.

Request:

{"action": "stream_start", "channel_id": "123456", "req_id": "10"}

Response:

{"event": "response", "stream_id": "a1b2c3d4", "message_id": "789", "req_id": "10"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel to send in
`reply_to`	no	string	Message ID to reply to
`interaction_token`	no	string	Interaction token to respond to a slash command
`req_id`	no	string	Correlation ID

stream_chunk

Append text to an active stream. Content is buffered and flushed periodically.

Request:

{"action": "stream_chunk", "stream_id": "a1b2c3d4", "content": "Hello ", "req_id": "11"}

Response:

{"event": "response", "ok": true, "req_id": "11"}

Field	Required	Type	Description
`stream_id`	yes	string	Stream ID from `stream_start`
`content`	no	string	Text to append
`req_id`	no	string	Correlation ID

stream_end

Finalize a streaming message. Performs a final edit with the complete content. If the content exceeds 2000 characters, overflow is split into follow-up messages.

Request:

{"action": "stream_end", "stream_id": "a1b2c3d4", "req_id": "12"}

Response:

{"event": "response", "ok": true, "message_id": "789", "req_id": "12"}

Field	Required	Type	Description
`stream_id`	yes	string	Stream ID from `stream_start`
`req_id`	no	string	Correlation ID

Interactions

interaction_followup

Send a follow-up response to a deferred slash command interaction.

Request:

{"action": "interaction_followup", "interaction_token": "uuid-token", "content": "Done!", "req_id": "20"}

Response:

{"event": "response", "ok": true, "req_id": "20"}

Field	Required	Type	Description
`interaction_token`	yes	string	Token from the `slash_command` event
`content`	no	string	Follow-up message text
`req_id`	no	string	Correlation ID

interaction_respond

Send an immediate response to an interaction. Use this instead of interaction_followup when the interaction has not been deferred.

Request:

{"action": "interaction_respond", "interaction_token": "uuid-token", "content": "Done!", "ephemeral": true, "req_id": "21"}

Response:

{"event": "response", "ok": true, "req_id": "21"}

Field	Required	Type	Description
`interaction_token`	yes	string	Token from the interaction event
`content`	no	string	Response message text
`embed`	no	object	Embed object
`components`	no	array	Message components
`ephemeral`	no	boolean	Only visible to the invoking user (default: false)
`req_id`	no	string	Correlation ID

interaction_edit

Edit the original interaction response message.

Request:

{"action": "interaction_edit", "interaction_token": "uuid-token", "content": "Updated!", "req_id": "22"}

Response:

{"event": "response", "ok": true, "req_id": "22"}

Field	Required	Type	Description
`interaction_token`	yes	string	Token from the interaction event
`content`	no	string	New message content
`embed`	no	object	New embed object
`components`	no	array	New message components
`req_id`	no	string	Correlation ID

modal_send

Open a modal form in response to an interaction.

Request:

{
  "action": "modal_send",
  "interaction_token": "uuid-token",
  "custom_id": "feedback-form",
  "title": "Feedback",
  "fields": [
    {"custom_id": "name", "label": "Name", "style": "short", "required": true},
    {"custom_id": "message", "label": "Message", "style": "long", "placeholder": "Your feedback..."}
  ],
  "req_id": "23"
}

Response:

{"event": "response", "ok": true, "req_id": "23"}

Field	Required	Type	Description
`interaction_token`	yes	string	Token from the interaction event
`custom_id`	yes	string	Unique identifier for the modal
`title`	yes	string	Modal title
`fields`	yes	array	List of text input fields
`req_id`	no	string	Correlation ID

Field object:

Field	Required	Type	Description
`custom_id`	yes	string	Unique identifier for the field
`label`	yes	string	Field label
`style`	yes	string	`short` (single line) or `long` (paragraph)
`required`	no	boolean	Whether the field is required (default: true)
`placeholder`	no	string	Placeholder text
`value`	no	string	Pre-filled value

Typing / Presence

typing_start

Start showing a typing indicator in a channel. The indicator persists until typing_stop is sent or the bot sends a message.

Request:

{"action": "typing_start", "channel_id": "123456", "req_id": "30"}

Response:

{"event": "response", "ok": true, "req_id": "30"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`req_id`	no	string	Correlation ID

typing_stop

Stop the typing indicator in a channel.

Request:

{"action": "typing_stop", "channel_id": "123456", "req_id": "31"}

Response:

{"event": "response", "ok": true, "req_id": "31"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`req_id`	no	string	Correlation ID

presence

Set the bot’s online status and activity.

Request:

{"action": "presence", "status": "dnd", "activity_type": "watching", "activity_text": "the logs", "req_id": "32"}

Response:

{"event": "response", "ok": true, "req_id": "32"}

Field	Required	Type	Description
`status`	no	string	`online`, `idle`, `dnd`, or `invisible` (default: `online`)
`activity_type`	no	string	`playing`, `watching`, `listening`, or `competing`
`activity_text`	no	string	Activity display text
`req_id`	no	string	Correlation ID

Reactions

reaction_add

Add a reaction to a message.

Request:

{"action": "reaction_add", "channel_id": "123456", "message_id": "789", "emoji": "thumbsup", "req_id": "40"}

Response:

{"event": "response", "ok": true, "req_id": "40"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel containing the message
`message_id`	yes	string	Message to react to
`emoji`	yes	string	Emoji character or custom emoji string
`req_id`	no	string	Correlation ID

reaction_remove

Remove the bot’s reaction from a message.

Request:

{"action": "reaction_remove", "channel_id": "123456", "message_id": "789", "emoji": "thumbsup", "req_id": "41"}

Response:

{"event": "response", "ok": true, "req_id": "41"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel containing the message
`message_id`	yes	string	Message to remove reaction from
`emoji`	yes	string	Emoji character or custom emoji string
`req_id`	no	string	Correlation ID

reaction_users

List users who reacted with a specific emoji.

Request:

{"action": "reaction_users", "channel_id": "123456", "message_id": "789", "emoji": "thumbsup", "limit": 100, "req_id": "42"}

Response:

{
  "event": "response",
  "ok": true,
  "users": [
    {"id": "111", "name": "alice"}
  ],
  "req_id": "42"
}

Field	Required	Type	Description
`channel_id`	yes	string	Channel containing the message
`message_id`	yes	string	Message ID
`emoji`	yes	string	Emoji character or custom emoji string
`limit`	no	integer	Max users to return (default: 100)
`req_id`	no	string	Correlation ID

Threads

thread_create

Create a new thread, optionally from an existing message.

Request:

{"action": "thread_create", "channel_id": "123456", "name": "Discussion", "message_id": "789", "req_id": "50"}

Response:

{"event": "response", "ok": true, "thread_id": "999", "thread_name": "Discussion", "req_id": "50"}

Field	Required	Type	Description
`channel_id`	yes	string	Parent channel ID
`name`	yes	string	Thread name
`message_id`	no	string	Message to create thread from (omit for standalone thread)
`auto_archive_duration`	no	integer	Auto-archive after N minutes (default: 1440)
`content`	no	string	Initial message to send in the thread
`req_id`	no	string	Correlation ID

thread_send

Send a message to an existing thread.

Request:

{"action": "thread_send", "thread_id": "999", "content": "Hello thread!", "req_id": "51"}

Response:

{"event": "response", "ok": true, "message_id": "1000", "req_id": "51"}

Field	Required	Type	Description
`thread_id`	yes	string	Thread ID
`content`	no	string	Message text
`files`	no	string[]	Local file paths to attach
`req_id`	no	string	Correlation ID

thread_list

List active threads in a channel.

Request:

{"action": "thread_list", "channel_id": "123456", "req_id": "52"}

Response:

{
  "event": "response",
  "ok": true,
  "threads": [
    {"id": "999", "name": "Discussion", "message_count": 5, "member_count": 3, "archived": false}
  ],
  "req_id": "52"
}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`req_id`	no	string	Correlation ID

thread_archive

Archive a thread.

Request:

{"action": "thread_archive", "thread_id": "999", "req_id": "53"}

Response:

{"event": "response", "ok": true, "req_id": "53"}

Field	Required	Type	Description
`thread_id`	yes	string	Thread ID
`req_id`	no	string	Correlation ID

thread_rename

Rename a thread.

Request:

{"action": "thread_rename", "thread_id": "999", "name": "New Name", "req_id": "54"}

Response:

{"event": "response", "ok": true, "req_id": "54"}

Field	Required	Type	Description
`thread_id`	yes	string	Thread ID
`name`	yes	string	New thread name
`req_id`	no	string	Correlation ID

thread_add_member

Add a member to a thread.

Request:

{"action": "thread_add_member", "thread_id": "999", "member_id": "111", "req_id": "55"}

Response:

{"event": "response", "ok": true, "req_id": "55"}

Field	Required	Type	Description
`thread_id`	yes	string	Thread ID
`member_id`	yes	string	Member user ID
`req_id`	no	string	Correlation ID

thread_remove_member

Remove a member from a thread.

Request:

{"action": "thread_remove_member", "thread_id": "999", "member_id": "111", "req_id": "56"}

Response:

{"event": "response", "ok": true, "req_id": "56"}

Field	Required	Type	Description
`thread_id`	yes	string	Thread ID
`member_id`	yes	string	Member user ID
`req_id`	no	string	Correlation ID

Polls

poll_send

Create a poll in a channel.

Request:

{
  "action": "poll_send",
  "channel_id": "123456",
  "question": "Favorite AI?",
  "answers": ["Claude", "Gemini", "ChatGPT"],
  "duration_hours": 24,
  "multiple": false,
  "req_id": "60"
}

Answers can also be objects with emoji:

{
  "action": "poll_send",
  "channel_id": "123456",
  "question": "Vote!",
  "answers": [{"text": "Yes", "emoji": "white_check_mark"}, {"text": "No", "emoji": "x"}],
  "req_id": "61"
}

Response:

{"event": "response", "ok": true, "message_id": "789", "req_id": "60"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`question`	yes	string	Poll question
`answers`	yes	array	List of answer strings or `{"text": "...", "emoji": "..."}` objects (min 2)
`duration_hours`	no	integer	Duration in hours (default: 24)
`multiple`	no	boolean	Allow multiple selections (default: false)
`content`	no	string	Optional message text alongside the poll
`req_id`	no	string	Correlation ID

poll_results

View the results of a poll.

Request:

{"action": "poll_results", "channel_id": "123456", "message_id": "789", "req_id": "62"}

Response:

{
  "event": "response",
  "ok": true,
  "question": "Favorite AI?",
  "answers": [
    {"text": "Claude", "votes": 10},
    {"text": "Gemini", "votes": 5},
    {"text": "ChatGPT", "votes": 3}
  ],
  "req_id": "62"
}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`message_id`	yes	string	Message ID of the poll
`req_id`	no	string	Correlation ID

poll_end

End a poll early.

Request:

{"action": "poll_end", "channel_id": "123456", "message_id": "789", "req_id": "63"}

Response:

{"event": "response", "ok": true, "req_id": "63"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`message_id`	yes	string	Message ID of the poll
`req_id`	no	string	Correlation ID

Channels

channel_list

List channels across all servers or a specific server.

Request:

{"action": "channel_list", "guild_id": "123456", "req_id": "70"}

Response:

{
  "event": "response",
  "ok": true,
  "channels": [
    {"id": "111", "name": "general", "type": "text", "server": "My Server", "server_id": "123456"}
  ],
  "req_id": "70"
}

Field	Required	Type	Description
`guild_id`	no	string	Server ID (omit for all servers)
`req_id`	no	string	Correlation ID

channel_create

Create a channel in a server.

Request:

{"action": "channel_create", "guild_id": "123456", "name": "new-channel", "type": "text", "req_id": "71"}

Response:

{"event": "response", "ok": true, "channel_id": "222", "name": "new-channel", "req_id": "71"}

Field	Required	Type	Description
`guild_id`	yes	string	Server ID
`name`	yes	string	Channel name
`type`	no	string	`text`, `voice`, `category`, or `forum` (default: `text`)
`req_id`	no	string	Correlation ID

channel_info

Get details about a channel.

Request:

{"action": "channel_info", "channel_id": "123456", "req_id": "72"}

Response:

{
  "event": "response",
  "ok": true,
  "id": "123456",
  "name": "general",
  "type": "text",
  "server": "My Server",
  "server_id": "789",
  "topic": "General discussion",
  "created_at": "2024-01-01T00:00:00+00:00",
  "req_id": "72"
}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`req_id`	no	string	Correlation ID

channel_edit

Edit channel settings.

Request:

{"action": "channel_edit", "channel_id": "123456", "name": "new-name", "topic": "New topic", "slowmode": 5, "nsfw": false, "req_id": "73"}

Response:

{"event": "response", "ok": true, "req_id": "73"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`name`	no	string	New channel name
`topic`	no	string	New channel topic
`slowmode`	no	integer	Slowmode delay in seconds (0 to disable)
`nsfw`	no	boolean	NSFW setting
`req_id`	no	string	Correlation ID

channel_set_permissions

Set permission overwrites for a channel.

Request:

{"action": "channel_set_permissions", "channel_id": "123456", "target_id": "222", "target_type": "role", "allow": "send_messages,read_messages", "deny": "manage_messages", "req_id": "74"}

Response:

{"event": "response", "ok": true, "req_id": "74"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`target_id`	yes	string	Role or member ID
`target_type`	no	string	`role` or `member` (default: `role`)
`allow`	no	string	Comma-separated permissions to allow
`deny`	no	string	Comma-separated permissions to deny
`req_id`	no	string	Correlation ID

forum_post

Create a forum post in a forum channel.

Request:

{"action": "forum_post", "channel_id": "123456", "title": "My Post", "content": "Post body", "req_id": "75"}

Response:

{"event": "response", "ok": true, "thread_id": "999", "req_id": "75"}

Field	Required	Type	Description
`channel_id`	yes	string	Forum channel ID
`title`	yes	string	Post title
`content`	yes	string	Post body content
`files`	no	string[]	Local file paths to attach
`req_id`	no	string	Correlation ID

Members

member_list

List members of a server.

Request:

{"action": "member_list", "guild_id": "123456", "limit": 50, "req_id": "80"}

Response:

{
  "event": "response",
  "ok": true,
  "members": [
    {"id": "111", "name": "alice", "nick": null, "bot": false}
  ],
  "req_id": "80"
}

Field	Required	Type	Description
`guild_id`	yes	string	Server ID
`limit`	no	integer	Max members to return (default: 50)
`req_id`	no	string	Correlation ID

member_info

Get details about a specific member.

Request:

{"action": "member_info", "guild_id": "123456", "member_id": "111", "req_id": "81"}

Response:

{
  "event": "response",
  "ok": true,
  "id": "111",
  "name": "alice",
  "nick": null,
  "bot": false,
  "roles": [{"id": "222", "name": "Admin"}],
  "joined_at": "2024-01-01T00:00:00+00:00",
  "req_id": "81"
}

Field	Required	Type	Description
`guild_id`	yes	string	Server ID
`member_id`	yes	string	Member user ID
`req_id`	no	string	Correlation ID

member_timeout

Timeout a member, preventing them from sending messages or joining voice.

Request:

{"action": "member_timeout", "guild_id": "123456", "member_id": "111", "duration": 300, "reason": "Spamming", "req_id": "82"}

Response:

{"event": "response", "ok": true, "req_id": "82"}

Field	Required	Type	Description
`guild_id`	yes	string	Server ID
`member_id`	yes	string	Member user ID
`duration`	yes	integer	Timeout duration in seconds (0 to remove timeout)
`reason`	no	string	Reason for timeout
`req_id`	no	string	Correlation ID

Roles

role_list

List roles in a server.

Request:

{"action": "role_list", "guild_id": "123456", "req_id": "90"}

Response:

{
  "event": "response",
  "ok": true,
  "roles": [
    {"id": "222", "name": "Admin", "color": "#ff0000", "members": 3}
  ],
  "req_id": "90"
}

Field	Required	Type	Description
`guild_id`	yes	string	Server ID
`req_id`	no	string	Correlation ID

role_assign

Assign a role to a member.

Request:

{"action": "role_assign", "guild_id": "123456", "member_id": "111", "role_id": "222", "req_id": "91"}

Response:

{"event": "response", "ok": true, "member": "alice", "role": "Admin", "req_id": "91"}

Field	Required	Type	Description
`guild_id`	yes	string	Server ID
`member_id`	yes	string	Member user ID
`role_id`	yes	string	Role ID to assign
`req_id`	no	string	Correlation ID

role_remove

Remove a role from a member.

Request:

{"action": "role_remove", "guild_id": "123456", "member_id": "111", "role_id": "222", "req_id": "92"}

Response:

{"event": "response", "ok": true, "member": "alice", "role": "Admin", "req_id": "92"}

Field	Required	Type	Description
`guild_id`	yes	string	Server ID
`member_id`	yes	string	Member user ID
`role_id`	yes	string	Role ID to remove
`req_id`	no	string	Correlation ID

role_edit

Edit a role’s settings.

Request:

{"action": "role_edit", "guild_id": "123456", "role_id": "222", "name": "Moderator", "color": "00ff00", "hoist": true, "mentionable": false, "req_id": "93"}

Response:

{"event": "response", "ok": true, "req_id": "93"}

Field	Required	Type	Description
`guild_id`	yes	string	Server ID
`role_id`	yes	string	Role ID
`name`	no	string	New role name
`color`	no	string	Hex color (e.g. `00ff00`)
`hoist`	no	boolean	Display role separately in sidebar
`mentionable`	no	boolean	Whether the role can be @-mentioned
`req_id`	no	string	Correlation ID

DMs

dm_send

Send a direct message to a user.

Request:

{"action": "dm_send", "user_id": "111", "content": "Hello!", "req_id": "100"}

Response:

{"event": "response", "ok": true, "message_id": "222", "recipient": "alice", "req_id": "100"}

Field	Required	Type	Description
`user_id`	yes	string	Recipient user ID
`content`	no	string	Message text
`req_id`	no	string	Correlation ID

Queries

message_list

List recent messages in a channel.

Request:

{"action": "message_list", "channel_id": "123456", "limit": 20, "req_id": "110"}

Response:

{
  "event": "response",
  "ok": true,
  "messages": [
    {
      "id": "789",
      "author": "alice",
      "author_id": "111",
      "content": "Hello!",
      "timestamp": "2024-01-01T12:00:00+00:00",
      "attachments": []
    }
  ],
  "req_id": "110"
}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`limit`	no	integer	Max messages (default: 20)
`req_id`	no	string	Correlation ID

message_get

Fetch a single message by ID.

Request:

{"action": "message_get", "channel_id": "123456", "message_id": "789", "req_id": "111"}

Response:

{
  "event": "response",
  "ok": true,
  "id": "789",
  "author": "alice",
  "author_id": "111",
  "content": "Hello!",
  "timestamp": "2024-01-01T12:00:00+00:00",
  "attachments": [],
  "embeds": [],
  "reply_to": null,
  "req_id": "111"
}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`message_id`	yes	string	Message ID
`req_id`	no	string	Correlation ID

message_search

Search messages in a channel by content.

Request:

{"action": "message_search", "channel_id": "123456", "query": "hello", "limit": 100, "author": "alice", "req_id": "112"}

Response:

{
  "event": "response",
  "ok": true,
  "messages": [
    {"id": "789", "author": "alice", "content": "Hello world!", "timestamp": "2024-01-01T12:00:00+00:00"}
  ],
  "req_id": "112"
}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`query`	no	string	Case-insensitive search string
`limit`	no	integer	Messages to scan (default: 100)
`author`	no	string	Filter by author name
`req_id`	no	string	Correlation ID

Server

server_list

List all servers the bot is in.

Request:

{"action": "server_list", "req_id": "120"}

Response:

{
  "event": "response",
  "ok": true,
  "servers": [
    {"id": "123456", "name": "My Server", "member_count": 42}
  ],
  "req_id": "120"
}

Field	Required	Type	Description
`req_id`	no	string	Correlation ID

server_info

Get details about a specific server.

Request:

{"action": "server_info", "guild_id": "123456", "req_id": "121"}

Response:

{
  "event": "response",
  "ok": true,
  "id": "123456",
  "name": "My Server",
  "owner": "alice",
  "member_count": 42,
  "channel_count": 10,
  "role_count": 5,
  "created_at": "2024-01-01T00:00:00+00:00",
  "req_id": "121"
}

Field	Required	Type	Description
`guild_id`	yes	string	Server ID
`req_id`	no	string	Correlation ID

Webhooks

webhook_list

List webhooks for a channel.

Request:

{"action": "webhook_list", "channel_id": "123456", "req_id": "130"}

Response:

{
  "event": "response",
  "ok": true,
  "webhooks": [
    {"id": "555", "name": "My Hook", "channel_id": "123456"}
  ],
  "req_id": "130"
}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`req_id`	no	string	Correlation ID

webhook_create

Create a webhook for a channel.

Request:

{"action": "webhook_create", "channel_id": "123456", "name": "My Hook", "req_id": "131"}

Response:

{"event": "response", "ok": true, "webhook_id": "555", "name": "My Hook", "req_id": "131"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`name`	yes	string	Webhook name
`req_id`	no	string	Correlation ID

webhook_delete

Delete a webhook.

Request:

{"action": "webhook_delete", "channel_id": "123456", "webhook_id": "555", "req_id": "132"}

Response:

{"event": "response", "ok": true, "req_id": "132"}

Field	Required	Type	Description
`channel_id`	yes	string	Channel ID
`webhook_id`	yes	string	Webhook ID
`req_id`	no	string	Correlation ID

Events

event_list

List scheduled events for a server.

Request:

{"action": "event_list", "guild_id": "123456", "req_id": "140"}

Response:

{
  "event": "response",
  "ok": true,
  "events": [
    {"id": "777", "name": "Game Night", "start_time": "2026-04-01T20:00:00+00:00", "status": "scheduled"}
  ],
  "req_id": "140"
}

Field	Required	Type	Description
`guild_id`	yes	string	Server ID
`req_id`	no	string	Correlation ID

event_create

Create a scheduled event.

Request:

{
  "action": "event_create",
  "guild_id": "123456",
  "name": "Game Night",
  "start_time": "2026-04-01T20:00:00+00:00",
  "end_time": "2026-04-01T23:00:00+00:00",
  "description": "Weekly game night!",
  "channel_id": "789",
  "req_id": "141"
}

Response:

{"event": "response", "ok": true, "event_id": "777", "req_id": "141"}

Field	Required	Type	Description
`guild_id`	yes	string	Server ID
`name`	yes	string	Event name
`start_time`	yes	string	Start time (ISO 8601)
`end_time`	no	string	End time (ISO 8601)
`description`	no	string	Event description
`channel_id`	no	string	Voice/stage channel ID
`location`	no	string	External location
`req_id`	no	string	Correlation ID

Last updated: March 22, 2026

9 min read

Edit this page