Bot API guide

Bot API reference

Every endpoint a bot can talk to: path, parameters, body and response. The structure is generated from the backend’s OpenAPI document; the prose is written by hand.

31 endpoints, generated from the backend’s OpenAPI document.

Back to the docs

Identity

Confirm which bot the token belongs to.

GET/api/bot/v1/users/@me

Returns the bot the token belongs to.

Use it as the first call after connecting; an invalid token answers 401.

Responses

200BotMeDto

Example request

curl -X GET 'https://api.talkith.com/api/bot/v1/users/@me' \
  -H 'Authorization: Bot <token>'

Servers and channels

Installed servers, channels, the emoji catalogue and voice state.

GET/api/bot/v1/servers

Servers the bot is installed in.

Only installed servers appear; installation is performed by a user from the portal.

Responses

200BotServerDto[]

Example request

curl -X GET 'https://api.talkith.com/api/bot/v1/servers' \
  -H 'Authorization: Bot <token>'

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

Channels in a server.

Channels the bot cannot see are omitted — channel permission overrides apply here too.

Parameters

serverId	`string<uuid>`	path	required

Responses

200BotChannelDto[]

Example request

curl -X GET 'https://api.talkith.com/api/bot/v1/servers/<serverId>/channels' \
  -H 'Authorization: Bot <token>'

GET/api/bot/v1/servers/{serverId}/emojis

The server’s custom emoji catalogue.

The `customEmojiId` used when reacting comes from this list.

Parameters

serverId	`string<uuid>`	path	required

Responses

200CustomEmojiDto[]

Example request

curl -X GET 'https://api.talkith.com/api/bot/v1/servers/<serverId>/emojis' \
  -H 'Authorization: Bot <token>'

Messages

Reading, sending, editing, deleting and the typing indicator.

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

Reads channel messages, paginated.

Page backwards with `before`; `limit` defaults to 50.

Parameters

channelId	`string<uuid>`	path	required
before	`string<uuid>`	query	optional
limit	`integer<int32>`	query	default: 50

Responses

200MessagePageDto

Example request

curl -X GET 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages' \
  -H 'Authorization: Bot <token>'

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

Sends a message to a channel.

To attach files, open an upload session first and pass the returned keys in `attachments`.

Parameters

channelId	`string<uuid>`	path	required

Request body `CreateBotMessageRequest`

content	`string`	required
replyToMessageId	`string<uuid>?`	optional
attachments	`MessageAttachmentDraftRequest[]?`	optional

Responses

200MessageDto

Example request

curl -X POST 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"content":"<string>"}'

DELETE/api/bot/v1/channels/{channelId}/messages/{messageId}

Deletes a message.

Fine for its own message; deleting someone else’s needs the ManageMessages permission.

Parameters

channelId	`string<uuid>`	path	required
messageId	`string<uuid>`	path	required

Responses

200no body

Example request

curl -X DELETE 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>' \
  -H 'Authorization: Bot <token>'

GET/api/bot/v1/channels/{channelId}/messages/{messageId}

Fetches a single message.

Parameters

channelId	`string<uuid>`	path	required
messageId	`string<uuid>`	path	required

Responses

200MessageDto

Example request

curl -X GET 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>' \
  -H 'Authorization: Bot <token>'

PATCH/api/bot/v1/channels/{channelId}/messages/{messageId}

Edits the bot’s own message.

Only messages the bot wrote can be edited; anything else answers 403.

Parameters

channelId	`string<uuid>`	path	required
messageId	`string<uuid>`	path	required

Request body `EditMessageRequest`

content	`string`	required
suppressLinkPreview	`boolean`	optional

Responses

200MessageDto

Example request

curl -X PATCH 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"content":"<string>"}'

GET/api/bot/v1/channels/{channelId}/messages/{messageId}/context

Fetches the messages around one message.

For building context behind a notification or reply; size the window with `before` and `after`.

Parameters

channelId	`string<uuid>`	path	required
messageId	`string<uuid>`	path	required
before	`integer<int32>`	query	default: 25
after	`integer<int32>`	query	default: 25

Responses

200MessageContextDto

Example request

curl -X GET 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/context' \
  -H 'Authorization: Bot <token>'

POST/api/bot/v1/channels/{channelId}/typing

Shows the typing indicator in a channel.

The indicator fades after a few seconds; call again during long work.

Parameters

channelId	`string<uuid>`	path	required

Responses

200no body

Example request

curl -X POST 'https://api.talkith.com/api/bot/v1/channels/<channelId>/typing' \
  -H 'Authorization: Bot <token>'

Reactions

React as the bot, remove someone else’s, or clear them all.

DELETE/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions

Clears every reaction on a message.

Requires ManageReactions or ManageMessages.

Parameters

channelId	`string<uuid>`	path	required
messageId	`string<uuid>`	path	required

Responses

200MessageReactionUpdateDto

Example request

curl -X DELETE 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/reactions' \
  -H 'Authorization: Bot <token>'

GET/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions

Returns the reaction summary for a message.

Parameters

channelId	`string<uuid>`	path	required
messageId	`string<uuid>`	path	required
unicodeEmoji	`string`	query	optional
customEmojiId	`string<uuid>`	query	optional

Responses

200MessageReactionDetailsDto

Example request

curl -X GET 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/reactions' \
  -H 'Authorization: Bot <token>'

GET/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions/details

Returns reactions along with the users who added them.

Parameters

channelId	`string<uuid>`	path	required
messageId	`string<uuid>`	path	required
unicodeEmoji	`string`	query	optional
customEmojiId	`string<uuid>`	query	optional

Responses

200MessageReactionDetailsDto

Example request

curl -X GET 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/reactions/details' \
  -H 'Authorization: Bot <token>'

DELETE/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions/me

Removes the bot’s own reaction.

Parameters

channelId	`string<uuid>`	path	required
messageId	`string<uuid>`	path	required

Request body `ReactionMutationRequest`

unicodeEmoji	`string?`	required
customEmojiId	`string<uuid>?`	required

Responses

200MessageReactionUpdateDto

Example request

curl -X DELETE 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/reactions/me' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"unicodeEmoji":"<string?>","customEmojiId":"<string<uuid>?>"}'

PUT/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions/me

Adds a reaction as the bot.

Send either `unicodeEmoji` or `customEmojiId` in the body, never both.

Parameters

channelId	`string<uuid>`	path	required
messageId	`string<uuid>`	path	required

Request body `ReactionMutationRequest`

unicodeEmoji	`string?`	required
customEmojiId	`string<uuid>?`	required

Responses

200MessageReactionUpdateDto

Example request

curl -X PUT 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/reactions/me' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"unicodeEmoji":"<string?>","customEmojiId":"<string<uuid>?>"}'

DELETE/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions/users/{userId}

Removes another user’s reaction.

Requires the ManageReactions permission.

Parameters

channelId	`string<uuid>`	path	required
messageId	`string<uuid>`	path	required
userId	`string<uuid>`	path	required

Request body `ReactionMutationRequest`

unicodeEmoji	`string?`	required
customEmojiId	`string<uuid>?`	required

Responses

200MessageReactionUpdateDto

Example request

curl -X DELETE 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/reactions/users/<userId>' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"unicodeEmoji":"<string?>","customEmojiId":"<string<uuid>?>"}'

Attachments

Signed upload sessions and time-limited download URLs.

GET/api/bot/v1/channels/{channelId}/messages/{messageId}/attachments/{attachmentId}/access-url

Mints a time-limited download URL for an attachment.

The URL is short lived; mint one when you need it rather than storing it.

Parameters

channelId	`string<uuid>`	path	required
messageId	`string<uuid>`	path	required
attachmentId	`string<uuid>`	path	required

Responses

200MessageAttachmentAccessUrlDto

Example request

curl -X GET 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/attachments/<attachmentId>/access-url' \
  -H 'Authorization: Bot <token>'

POST/api/bot/v1/channels/{channelId}/messages/attachments/upload-session

Opens a signed upload session for an attachment.

Upload the file straight to the returned address, then send the message with `attachments`.

Parameters

channelId	`string<uuid>`	path	required

Request body `CreateMessageAttachmentUploadSessionRequest`

fileName	`string`	required
contentType	`string`	required
size	`integer<int64>`	required

Responses

200MessageAttachmentUploadSessionDto

Example request

curl -X POST 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/attachments/upload-session' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"fileName":"<string>","contentType":"<string>","size":"<integer<int64>>"}'

Voice and WHIP

Join and leave voice channels, and open ingress for music streaming.

DELETE/api/bot/v1/channels/{channelId}/voice/ingress

Closes the WHIP ingress session.

Always call it when the stream ends; a session left open leaves a silent participant behind.

Parameters

channelId	`string<uuid>`	path	required

Responses

200no body

Example request

curl -X DELETE 'https://api.talkith.com/api/bot/v1/channels/<channelId>/voice/ingress' \
  -H 'Authorization: Bot <token>'

POST/api/bot/v1/channels/{channelId}/voice/ingress

Opens an ingress session for a WHIP stream.

Music bots publish stereo Opus through this, connecting as a WebRTC publisher.

Parameters

channelId	`string<uuid>`	path	required

Responses

200BotVoiceIngressResponseDto

Example request

curl -X POST 'https://api.talkith.com/api/bot/v1/channels/<channelId>/voice/ingress' \
  -H 'Authorization: Bot <token>'

POST/api/bot/v1/channels/{channelId}/voice/join

Connects the bot to a voice channel and returns a LiveKit token.

Connect to LiveKit directly with the token; the server is not a relay.

Parameters

channelId	`string<uuid>`	path	required

Responses

200BotVoiceJoinResponseDto

Example request

curl -X POST 'https://api.talkith.com/api/bot/v1/channels/<channelId>/voice/join' \
  -H 'Authorization: Bot <token>'

POST/api/bot/v1/channels/{channelId}/voice/leave

Disconnects the bot from the voice channel.

Parameters

channelId	`string<uuid>`	path	required

Responses

200no body

Example request

curl -X POST 'https://api.talkith.com/api/bot/v1/channels/<channelId>/voice/leave' \
  -H 'Authorization: Bot <token>'

GET/api/bot/v1/servers/{serverId}/voice-state

Current participants of the server’s voice channels.

This is a snapshot; follow changes through the gateway’s VoiceStateChanged event.

Parameters

serverId	`string<uuid>`	path	required

Responses

200ChannelVoiceStateDto[]

Example request

curl -X GET 'https://api.talkith.com/api/bot/v1/servers/<serverId>/voice-state' \
  -H 'Authorization: Bot <token>'

Commands

List slash commands and sync the whole set at once.

GET/api/bot/v1/commands

Slash commands registered by the application.

Responses

200BotCommandDto[]

Example request

curl -X GET 'https://api.talkith.com/api/bot/v1/commands' \
  -H 'Authorization: Bot <token>'

PUT/api/bot/v1/commands

Replaces the whole command list.

Commands you leave out are deleted — this is a full sync, not a merge.

Request body `SyncBotCommandsRequest`

commands	`SyncBotCommandItemDto[]`	required

Responses

200BotCommandDto[]

Example request

curl -X PUT 'https://api.talkith.com/api/bot/v1/commands' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"commands":"<SyncBotCommandItemDto[]>"}'

Interactions

Acknowledge, defer and answer the interaction a command produces.

POST/api/bot/v1/interactions/{interactionId}/ack

Acknowledges the interaction.

A command must be answered quickly after the user runs it, or the interaction expires.

Parameters

interactionId	`string<uuid>`	path	required

Responses

200no body

Example request

curl -X POST 'https://api.talkith.com/api/bot/v1/interactions/<interactionId>/ack' \
  -H 'Authorization: Bot <token>'

POST/api/bot/v1/interactions/{interactionId}/defer

Defers the answer and shows a thinking state.

For slow work, defer first and fill in the response when the work finishes.

Parameters

interactionId	`string<uuid>`	path	required

Responses

200no body

Example request

curl -X POST 'https://api.talkith.com/api/bot/v1/interactions/<interactionId>/defer' \
  -H 'Authorization: Bot <token>'

POST/api/bot/v1/interactions/{interactionId}/follow-ups

Sends an extra message after the response.

Parameters

interactionId	`string<uuid>`	path	required

Request body `CreateBotInteractionResponseRequest`

content	`string?`	required
replyToMessageId	`string<uuid>?`	optional
attachments	`MessageAttachmentDraftRequest[]?`	optional
ephemeral	`boolean`	optional

Responses

200MessageDto

Example request

curl -X POST 'https://api.talkith.com/api/bot/v1/interactions/<interactionId>/follow-ups' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"content":"<string?>"}'

PATCH/api/bot/v1/interactions/{interactionId}/response

Updates a response that was already sent.

Parameters

interactionId	`string<uuid>`	path	required

Request body `EditMessageRequest`

content	`string`	required
suppressLinkPreview	`boolean`	optional

Responses

200MessageDto

Example request

curl -X PATCH 'https://api.talkith.com/api/bot/v1/interactions/<interactionId>/response' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"content":"<string>"}'

POST/api/bot/v1/interactions/{interactionId}/response

Sends the response to an interaction.

Parameters

interactionId	`string<uuid>`	path	required

Request body `CreateBotInteractionResponseRequest`

content	`string?`	required
replyToMessageId	`string<uuid>?`	optional
attachments	`MessageAttachmentDraftRequest[]?`	optional
ephemeral	`boolean`	optional

Responses

200MessageDto

Example request

curl -X POST 'https://api.talkith.com/api/bot/v1/interactions/<interactionId>/response' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"content":"<string?>"}'

Schemas

The fields of the bodies endpoints return and expect. This list is generated from the OpenAPI document too.

BotMeDto

applicationId	`string<uuid>`	required
botUserId	`string<uuid>`	required
username	`string`	required
displayName	`string`	required

BotServerDto

id	`string<uuid>`	required
name	`string`	required
memberCount	`integer<int32>`	required

BotChannelDto

id	`string<uuid>`	required
serverId	`string<uuid>`	required
name	`string`	required
type	`string`	required
position	`integer<int32>`	required
topic	`string?`	required

BotCommandDto

id	`string<uuid>`	required
name	`string`	required
description	`string`	required
options	`BotCommandOptionDto[]`	required
createdAt	`string<date-time>`	required

SyncBotCommandsRequest

commands	`SyncBotCommandItemDto[]`	required

ChannelVoiceStateDto

channelId	`string<uuid>`	required
participants	`VoiceParticipantDto[]`	required

CustomEmojiDto

id	`string<uuid>`	required
name	`string`	required
imageUrl	`string`	required
sourceServerId	`string<uuid>`	required
sourceServerName	`string`	required
isExternal	`boolean`	required
isAnimated	`boolean`	required

MessagePageDto

messages	`MessageDto[]`	required
hasMore	`boolean`	required
oldestId	`string<uuid>?`	required

CreateBotMessageRequest

content	`string`	required
replyToMessageId	`string<uuid>?`	optional
attachments	`MessageAttachmentDraftRequest[]?`	optional

MessageDto

id	`string<uuid>`	required
channelId	`string<uuid>`	required
authorId	`string<uuid>`	required
authorUsername	`string`	required
authorDisplayName	`string`	required
authorAvatarUrl	`string?`	required
replyTo	`object`	required
content	`string`	required
attachments	`MessageAttachmentDto[]`	required
linkPreview	`object`	required
reactions	`ReactionSummaryDto[]`	required
poll	`object`	required
forwardedFrom	`object`	required
editedAt	`string<date-time>?`	required
pinnedAt	`string<date-time>?`	required
pinnedByUserId	`string<uuid>?`	required
isDeleted	`boolean`	required
createdAt	`string<date-time>`	required

EditMessageRequest

content	`string`	required
suppressLinkPreview	`boolean`	optional

MessageContextDto

serverId	`string<uuid>`	required
channelId	`string<uuid>`	required
messageId	`string<uuid>`	required
messages	`MessageDto[]`	required
hasOlder	`boolean`	required
hasNewer	`boolean`	required

CreateMessageAttachmentUploadSessionRequest

fileName	`string`	required
contentType	`string`	required
size	`integer<int64>`	required

MessageAttachmentUploadSessionDto

uploadUrl	`string`	required
objectKey	`string`	required
publicUrl	`string`	required
fields	`object`	required
expiresAt	`string<date-time>`	required
maxBytes	`integer<int64>`	required

MessageAttachmentAccessUrlDto

attachmentId	`string<uuid>`	required
url	`string`	required
expiresAt	`string<date-time>`	required

ReactionMutationRequest

unicodeEmoji	`string?`	required
customEmojiId	`string<uuid>?`	required

MessageReactionUpdateDto

channelId	`string<uuid>`	required
messageId	`string<uuid>`	required
reactions	`ReactionSummaryDto[]`	required

MessageReactionDetailsDto

channelId	`string<uuid>`	required
messageId	`string<uuid>`	required
reactions	`ReactionUsersGroupDto[]`	required

BotVoiceJoinResponseDto

token	`string`	required
url	`string`	required
channelId	`string<uuid>`	required
participants	`VoiceParticipantDto[]`	required

BotVoiceIngressResponseDto

ingressId	`string`	required
url	`string`	required
streamKey	`string`	required
channelId	`string<uuid>`	required
participants	`VoiceParticipantDto[]`	required

CreateBotInteractionResponseRequest

content	`string?`	required
replyToMessageId	`string<uuid>?`	optional
attachments	`MessageAttachmentDraftRequest[]?`	optional
ephemeral	`boolean`	optional

Event gateway

REST endpoints run when you start the request; the gateway tells you what happened. The WebSocket opens with HELLO, authenticates with IDENTIFY, and declares which events it wants through intents.

Connection frames

HELLO	from server	Arrives from the server as soon as the socket opens, carrying the heartbeat interval.
IDENTIFY	from bot	Sends the bot token and the list of intents it wants.
READY	from server	Identity accepted; the bot will now receive events.
HEARTBEAT	from bot	Sent on the interval given in HELLO.
HEARTBEAT_ACK	from server	The reply to each heartbeat; its absence means the connection is gone.
DISPATCH	from server	Every event travels inside this envelope, with the event name in a field.

`SERVER_MESSAGES`

Message events in servers where the bot is installed.

MESSAGE_CREATEA new message landed in a channel.
MESSAGE_UPDATEAn existing message was edited.
MESSAGE_DELETEA message was deleted; the body carries identifiers only.

`MESSAGE_REACTIONS`

Reactions added to and removed from messages.

MESSAGE_REACTION_ADDA reaction was added to a message.
MESSAGE_REACTION_REMOVEA reaction was removed.

`SERVER_VOICE`

Joining and leaving voice channels.

VOICE_STATE_UPDATESomeone joined or left a voice channel.

`APPLICATION_COMMANDS`

The interaction produced when a user runs a slash command.

APPLICATION_COMMANDA slash command ran and must be answered through the interaction endpoints.

Identity

Responses

Servers and channels

Responses

Parameters

Responses

Parameters

Responses

Messages

Parameters

Responses

Parameters

Request body CreateBotMessageRequest

Responses

Parameters

Responses

Parameters

Responses

Parameters

Request body EditMessageRequest

Responses

Parameters

Responses

Parameters

Responses

Reactions

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Request body ReactionMutationRequest

Responses

Parameters

Request body ReactionMutationRequest

Responses

Parameters

Request body ReactionMutationRequest

Responses

Attachments

Parameters

Responses

Parameters

Request body CreateMessageAttachmentUploadSessionRequest

Responses

Voice and WHIP

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Commands

Responses

Request body SyncBotCommandsRequest

Responses

Interactions

Parameters

Responses

Parameters

Responses

Parameters

Request body CreateBotInteractionResponseRequest

Responses

Parameters

Request body EditMessageRequest

Responses

Parameters

Request body CreateBotInteractionResponseRequest

Responses

Schemas

Event gateway

Connection frames

SERVER_MESSAGES

Request body `CreateBotMessageRequest`

Request body `EditMessageRequest`

Request body `ReactionMutationRequest`

Request body `ReactionMutationRequest`

Request body `ReactionMutationRequest`

Request body `CreateMessageAttachmentUploadSessionRequest`

Request body `SyncBotCommandsRequest`

Request body `CreateBotInteractionResponseRequest`

Request body `EditMessageRequest`

Request body `CreateBotInteractionResponseRequest`

`SERVER_MESSAGES`

`MESSAGE_REACTIONS`

`SERVER_VOICE`

`APPLICATION_COMMANDS`