Channels¶

A channel is where a conversation happens, in text or in voice. A guild owns text, voice, category and link channels. Outside a guild, a channel is a direct message, a group direct message, or the personal notes channel.

Messages defines message content, and Guild channels defines guild-scoped listing, creation and reordering. Private channels defines opening, listing and closing direct messages. Calls defines ringing and ending a private call.

All routes on this page require authentication. Routes marked user-only reject a valid Bot <token> credential with 403 ACCESS_DENIED (an invalid one with 401 UNAUTHORIZED); every other route also accepts a bot token. Error bodies follow Errors.

Channel object¶

The guild channel object below is the shape TEBHOS uses in Gateway events (Channel Create, Channel Update), in the Ready payload, and in the response of Modify channel.

Structure¶

locked and is_private are TEBHOS additions.

Example¶

{
  "id": "1501314428688998182",
  "type": 0,
  "guild_id": "1501314428688990000",
  "name": "general",
  "topic": "Anything goes",
  "position": 3,
  "parent_id": "1501314428688991111",
  "bitrate": 0,
  "user_limit": 0,
  "voice_connection_limit": null,
  "rtc_region": null,
  "rate_limit_per_user": 0,
  "last_message_id": "1501320000000000000",
  "last_pin_timestamp": null,
  "permission_overwrites": [],
  "nsfw": false,
  "locked": false,
  "is_private": false
}

Private channel object¶

A direct message, group direct message, or personal notes channel is returned by Private channels routes and by Modify channel on a group direct message. Its main fields are id, type ("DM" or "GROUP_DM"), channel_type (1 or 3), name, owner_id?, icon?, recipients (each {id, name, image_url}), last_message_id?, last_pin_timestamp and nicks?. Private channels documents it in full.

Channel types¶

Permission overwrite object¶

A permission overwrite changes the effective guild permissions for one role or one member in one channel. allow and deny are decimal strings because a permission mask exceeds the range a JSON number preserves. Permissions defines the individual flags.

Structure¶

One identifier addresses one overwrite, so storing an overwrite for an identifier that already has one replaces it. On write, every bit outside the defined permission set is discarded, and an overwrite whose allow and deny share a bit is rejected with 400 BAD_REQUEST.

Example¶

{
  "id": "1501314428688990000",
  "type": 0,
  "allow": "3072",
  "deny": "0"
}

Permission overwrite types¶

Channel slowmode state object¶

Structure¶

Example¶

{
  "rate_limit_per_user": 10,
  "retry_after_ms": 0,
  "next_send_allowed_at": null,
  "can_bypass": false
}

RTC region object¶

An RTC region names one voice routing target the deployment operates. Its identifier is the value a guild voice channel stores in rtc_region.

Structure¶

Example¶

{
  "id": "eu-central",
  "name": "Frankfurt",
  "emoji": ""
}

Get channel¶

GET /channels/{channel_id}

Returns a guild channel visible to the caller. Requires VIEW_CHANNEL. Accepts bot tokens.

A channel that does not exist, a guild the caller is not a member of, and a private channel all return 404 NOT_FOUND. A member without VIEW_CHANNEL receives 403 FORBIDDEN. Use Private channels to read direct messages.

Path parameters¶

Response body¶

Rate limit¶

100 requests per 10 seconds for each user and channel, on the channel:read bucket.

curl https://tebhos.com/api/v1/channels/1501314428688998182 \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN"

Get channel slowmode state¶

GET /channels/{channel_id}/slowmode

Returns the caller's channel slowmode state object for a guild channel. Requires VIEW_CHANNEL. Accepts bot tokens. A private channel returns 404 NOT_FOUND.

Rate limit¶

100 requests per 10 seconds for each user and channel, on the channel:read bucket.

List RTC regions¶

GET /channels/{channel_id}/rtc-regions

Returns the RTC region objects the caller can select, in ascending name order. User-only. Requires VIEW_CHANNEL.

Only regions available to the caller in the channel's guild are returned; some regions can be restricted by the operator (for example to premium accounts or specific guilds). The array can be empty.

Rate limit¶

100 requests per 10 seconds for each user and channel, on the channel:read bucket.

Modify channel¶

PATCH /channels/{channel_id}

Modifies a guild channel or a group direct message. User-only.

The stored channel type selects the behaviour: a group direct message follows the group direct message body, a one-to-one direct message returns 403 FORBIDDEN, and every guild channel follows the guild channel body.

Rate limit¶

20 requests per 10 seconds for each user and channel, on the channel:update bucket.

Guild channel body¶

Requires VIEW_CHANNEL and MANAGE_CHANNELS in that channel. Supplying permission_overwrites also requires MANAGE_ROLES. Supplying rtc_region on a voice channel also requires UPDATE_RTC_REGION.

Every field is optional, and an omitted field keeps its current value.

position is rejected with 400 BAD_REQUEST; reorder channels through Guild channels. nsfw, nsfw_override, content_warning_level and content_warning_text are accepted and ignored.

A caller who is not the guild owner and lacks ADMINISTRATOR cannot allow a permission bit they do not hold in that channel, and cannot remove a deny for such a bit; the request fails with 403 FORBIDDEN.

A non-empty rtc_region that the caller cannot select returns 400 INVALID_OR_RESTRICTED_RTC_REGION.

Bitrate limits¶

The accepted voice bitrate depends on the caller and the guild:

The effective ceiling is the larger of the caller's and the guild's. The lowest accepted bitrate is 8000 (8 kbps); a lower value returns 400 INVALID_FORM_BODY. A value below 1000 is read as kbps and multiplied by 1000 before it is checked and stored. A value above the ceiling returns 403 BITRATE_REQUIRES_UPGRADE, or 400 BITRATE_EXCEEDS_LIMIT when the ceiling is already 384 kbps. A request that repeats the channel's current bitrate is not checked against the ceiling, so renaming a channel whose bitrate is above the caller's ceiling still succeeds.

The stored and returned unit is always bits per second. Channels saved before this rule with a kbps value (for example 64) are returned as bits per second (64000).

Response¶

200 with the updated channel object (plus the compatibility keys and a message string).

Side effects¶

Emits Channel Update with the full channel object to the guild, and writes a CHANNEL_UPDATE guild audit log entry. When a category's overwrites change, every child channel whose overwrites exactly matched the category's previous overwrites receives the new overwrites and its own Channel Update. Changing rtc_region moves the channel's active voice connections to the new region, and changing overwrites re-evaluates voice permissions of connected members.

Group direct message body¶

The caller must be a current recipient; otherwise the request returns 403 FORBIDDEN.

The group icon is not set through this route; use Upload group direct message icon.

Response¶

200 with the private channel object. A request that changes nothing returns the current object.

Side effects¶

A name change creates a CHANNEL_NAME_CHANGE (4) system message delivered with Message Create. Every recipient receives the updated channel in a DM_CHANNEL_UPDATED Dispatch.

Toggle channel lock¶

PATCH /channels/{channel_id}/lock

Toggles the locked state of a guild channel. User-only. Requires VIEW_CHANNEL and MANAGE_CHANNELS. There is no body; each call flips the current value.

While a channel is locked, Create message returns 403 FORBIDDEN for every caller, including administrators.

Response¶

200 with a JSON body containing a message string. Emits Channel Update to the guild.

Delete channel¶

DELETE /channels/{channel_id}

Deletes a guild channel. User-only. Requires VIEW_CHANNEL and MANAGE_CHANNELS.

Private channels are not deleted through this route: close a direct message with Private channels, and leave a group direct message with Remove group direct message recipient using your own user ID. A private channel returns 404 NOT_FOUND.

Response¶

200 with a JSON body containing a message string.

Side effects¶

Emits Channel Delete with {id, type, guild_id} to the guild and writes a CHANNEL_DELETE guild audit log entry. When the deleted channel was the guild's system, rules or AFK channel, TEBHOS clears that guild setting and emits Guild Update.

Rate limit¶

20 requests per 10 seconds for each user and channel, on the channel:delete bucket.

Upload group direct message icon¶

Setting a group icon is a two-step upload. Any current recipient can change the icon.

Request an icon upload URL¶

POST /channels/{channel_id}/icon/upload-url

Returns {upload_url, storage_key, url, expires_in}. PUT the file to upload_url within expires_in seconds (300).

Confirm the icon¶

POST /channels/{channel_id}/icon/confirm

Returns {icon} with the public icon URL. When the icon changed, TEBHOS creates a CHANNEL_ICON_CHANGE (5) system message and sends every recipient a DM_CHANNEL_UPDATED Dispatch. Both routes are user-only and return 403 FORBIDDEN when the caller is not a recipient of the group.

Add group direct message recipient¶

PUT /channels/{channel_id}/recipients/{user_id}

Adds a user to a group direct message and returns 204. User-only.

• The caller must be a current recipient; otherwise 403 FORBIDDEN.
• The channel must be a group direct message; otherwise 400 BAD_REQUEST.
• A group holds at most 50 members including the owner; a full group returns 400 BAD_REQUEST.
• The target's group direct message privacy setting must admit the caller; otherwise 403 MISSING_ACCESS.

Side effects¶

The added user receives Channel Create, every recipient receives Channel Recipient Add with {channel_id, user}, and a RECIPIENT_ADD (1) system message is created.

Rate limit¶

20 requests per 10 seconds for each user and channel, on the channel:update bucket, plus 10 requests per hour for each user on the user:group_dm:recipient:add bucket.

Remove group direct message recipient¶

DELETE /channels/{channel_id}/recipients/{user_id}

Removes a user from a group direct message and returns 204. User-only. The caller must be a current recipient; otherwise 403 FORBIDDEN. Passing your own user ID leaves the group.

Side effects¶

The removed user receives Channel Delete. When recipients remain, they receive Channel Recipient Remove with {channel_id, user} and a RECIPIENT_REMOVE (2) system message is created. Removing the last recipient deletes the channel.

Rate limit¶

20 requests per 10 seconds for each user and channel, on the channel:update bucket.

List channel permission overwrites¶

GET /channels/{channel_id}/permissions

Returns the channel's overwrites. Requires VIEW_CHANNEL and MANAGE_ROLES. Accepts bot tokens.

Each entry has id (a synthetic identifier, not a snowflake), target_type (0 role, 1 member), target_id, channel_id, category_id (null), allow, deny, created_at and updated_at.

Set channel permission overwrite¶

PUT /channels/{channel_id}/permissions/{overwrite_id}

Creates or replaces one permission overwrite on a guild channel or category and returns 204. Requires VIEW_CHANNEL and MANAGE_ROLES in that channel. Accepts bot tokens.

Path parameters¶

JSON body¶

A caller who is not the guild owner and lacks ADMINISTRATOR cannot allow a bit they do not hold in the channel, nor remove a deny for such a bit (403 FORBIDDEN).

Side effects¶

Emits Channel Update with the full channel to the guild. When the target is a category, every child whose overwrites exactly matched the category's previous overwrites receives the new overwrites and its own Channel Update. Voice permissions of connected members are re-evaluated.

Rate limit¶

20 requests per 10 seconds for each user and channel, on the channel:update bucket.

curl -X PUT https://tebhos.com/api/v1/channels/1501314428688998182/permissions/1501314428688990000 \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": 0, "allow": "0", "deny": "1024"}'

Delete channel permission overwrite¶

DELETE /channels/{channel_id}/permissions/{overwrite_id}

Deletes one permission overwrite. Requires VIEW_CHANNEL and MANAGE_ROLES. Accepts bot tokens. Returns 200 with a JSON body containing a message string.

An identifier with no stored overwrite returns 404 NOT_FOUND. The same grant rule as Set channel permission overwrite applies to the removed deny bits. Side effects and rate limit are the same as for setting an overwrite.

Sync channel permissions with category¶

POST /channels/{channel_id}/permissions/sync-category

Replaces the channel's overwrites with an exact copy of its parent category's overwrites. User-only. Requires VIEW_CHANNEL and MANAGE_ROLES. A channel without a parent category returns 400 BAD_REQUEST.

Returns the resulting list in the same shape as List channel permission overwrites and emits Channel Update.

Indicate typing¶

POST /channels/{channel_id}/typing is documented under Messages.

Channel invites¶

Invites for a channel are listed and created under Invites.