Channel tokens
A channel token lets one talker read and write in its conversations, over REST and over the gateway; this page lists everything it can call. A conversation talker's token names exactly one conversation. A staff talker's integration-wide token names none and reaches every conversation channel of your integration, present and future; see Talkers.
Channel tokens are minted by your backend when it opens a conversation, admits a talker, creates a staff talker or renews a token, and handed to that person's front end. Send one as:
Authorization: Bearer <channel token>
A token that is malformed, expired, revoked, or names a talker no longer admitted to its channel (including because the conversation closed) is treated as no credential at all: routes answer 401 with {"message": "401: Unauthorized", "code": 0}.
REST routes
In the table, {channel_id} must be the channel the token was minted for, or, with an integration-wide token, any conversation channel of your integration. Any other channel id (the internal and logging channels included) answers 403, code 50001, Missing Access.
| Route | What it does |
|---|---|
GET /channels/{channel_id} | The conversation's channel object (name, topic and the rest). |
GET /channels/{channel_id}/messages | History, newest first. Query: limit (1 to 100, default 50) and one of before, after or around (a message id). |
GET /channels/{channel_id}/messages/{message_id} | One message. |
POST /channels/{channel_id}/messages | Sends a message as the talker. See the rules below. |
PATCH /channels/{channel_id}/messages/{message_id} | Edits one of the talker's own messages. Editing anyone else's answers 403, code 50013, Cannot edit a message authored by another user. |
DELETE /channels/{channel_id}/messages/{message_id} | Deletes one of the talker's own messages (204). Deleting anyone else's answers 403, code 50013, Missing Permissions. |
POST /channels/{channel_id}/typing | Shows the talker as typing (204). Everyone in the channel receives TYPING_START. |
Every other route answers 403, code 50001, Missing Access, whatever the channel: members, guilds, users, reactions, threads, pins, invites and so on.
Sending messages
contentis required and may be up to 4000 characters. Longer answers400Invalid Form Body oncontent:Must be 4000 or fewer in length. An empty message answersCannot send an empty message.embedsare dropped: only bots may send embeds, and a talker is not a bot. Links in the content may still unfurl into an embed afterwards, delivered asMESSAGE_UPDATE.- Attachments are refused with
403, code 50013,Missing Permissions. A talker holds only View Channel, Send Messages, Read Message History and Embed Links in its channel. message_referenceworks for replies to messages in the same channel.- Reactions are not available to talkers.
curl -s -X POST https://discord.community/api/v9/channels/1290000000000000001/messages \
-H "Authorization: Bearer $TALKER_TOKEN" -H "Content-Type: application/json" \
-d '{"content": "Is there a tracking number?"}'
The answer is the Discord message object. Its author is the talker as a user object.
Gateway
Connect to:
wss://gateway.discord.community/?v=9&encoding=json
- The server sends HELLO (op 10) with
heartbeat_intervalin milliseconds. - Send IDENTIFY (op 2).
tokenis the bare channel token, withoutBearer.intentsis ignored for channel tokens; send0.
{
"op": 2,
"d": {
"token": "<channel token>",
"intents": 0,
"properties": { "os": "web", "browser": "acme-chat", "device": "acme-chat" }
}
}
- The server answers READY (op 0,
tREADY):
{
"v": 9,
"user": { "id": "1290000000000000050", "username": "Dana", "global_name": "Dana", "discriminator": "0", "avatar": null, "bot": false },
"session_id": "1290000000000000777",
"resume_gateway_url": "wss://gateway.discord.community",
"channel": { "id": "1290000000000000001", "type": 0, "guild_id": "1287654321098765500", "name": "order-4471", "topic": "Customer asks where order 4471 is. Priority: normal." },
"channels": [ { "id": "1290000000000000001", "type": 0, "guild_id": "1287654321098765500", "name": "order-4471", "topic": "Customer asks where order 4471 is. Priority: normal." } ],
"guilds": [],
"private_channels": [],
"relationships": [],
"application": { "id": "1287654321098765432" }
}
user is the talker, channel is the full channel object of the conversation, channels lists every channel the token reaches, and application.id is your integration id. For a staff talker's integration-wide token, channel is null and channels lists every live conversation of your integration. guilds, private_channels and relationships are always empty. Nothing else follows READY: no GUILD_CREATE, no READY_SUPPLEMENTAL.
- Send HEARTBEAT (op 1) every
heartbeat_intervalmilliseconds, with the last sequence number you received asd(ornullbefore the first dispatch). The server answers HEARTBEAT_ACK (op 11).
- Receive dispatches (op 0) for the conversation:
| Event | When |
|---|---|
MESSAGE_CREATE | A message was sent, by anyone. |
MESSAGE_UPDATE | A message was edited, or a link in it unfurled. |
MESSAGE_DELETE | A message was deleted. |
TYPING_START | Someone is typing. |
CHANNEL_UPDATE | The channel's name or topic changed. |
CHANNEL_DELETE | The conversation was closed. A per-conversation token no longer works; close the socket and end the chat in your UI. A staff talker keeps its socket and drops that conversation. |
CHANNEL_CREATE | Staff talkers only: a new conversation opened. Its channel object is the payload. |
Events are addressed to the talker, and channel_id on each event says which conversation it belongs to. A staff talker's socket carries every conversation; a conversation talker admitted to several conversations at once also receives all of them on each socket, so keep one external_id per chat if you want strictly one channel per socket for end users.
RESUME (op 6) works with a channel token exactly as on Discord's gateway: after a disconnect, connect to the resume_gateway_url from READY and send op 6 with the same token, the session_id from READY and the last sequence number you received. The server replays every event you missed and then sends RESUMED. If the session has expired (it is kept for a few minutes after the socket drops) or the sequence is too old, you receive op 9 Invalid Session with d: false: open a new connection, IDENTIFY again, and fetch GET /channels/{channel_id}/messages?after=<last message id> to fill the gap. A token only resumes the session it identified. An invalid or expired token on IDENTIFY or RESUME closes with 4004. At most 10 sessions may be open for one talker at a time; the eleventh closes with 4009.
When you remove the talker from the conversation or revoke it, its sessions are disconnected, and reconnecting with the old token fails.
Minimal JavaScript client
// Runs in the end user's browser. `token` came from your backend.
function connectChat(token, onMessage, onClosed) {
const ws = new WebSocket("wss://gateway.discord.community/?v=9&encoding=json");
let seq = null;
let timer = null;
ws.onmessage = (ev) => {
const msg = JSON.parse(ev.data);
if (msg.s != null) seq = msg.s;
if (msg.op === 10) {
// HELLO: start heartbeating, then identify.
timer = setInterval(() => ws.send(JSON.stringify({ op: 1, d: seq })), msg.d.heartbeat_interval);
ws.send(JSON.stringify({
op: 2,
d: { token, intents: 0, properties: { os: "web", browser: "acme-chat", device: "acme-chat" } },
}));
return;
}
if (msg.op !== 0) return; // 11 is HEARTBEAT_ACK
switch (msg.t) {
case "READY":
console.log("chatting in #" + msg.d.channel.name + " as " + msg.d.user.username);
break;
case "MESSAGE_CREATE":
onMessage(msg.d);
break;
case "CHANNEL_DELETE":
onClosed();
ws.close();
break;
}
};
ws.onclose = () => clearInterval(timer);
return ws;
}
// Sending goes over REST, not the socket.
async function send(token, channelId, content) {
const res = await fetch(`https://discord.community/api/v9/channels/${channelId}/messages`, {
method: "POST",
headers: { "Authorization": "Bearer " + token, "Content-Type": "application/json" },
body: JSON.stringify({ content }),
});
if (res.status === 429) {
const { retry_after } = await res.json();
await new Promise((r) => setTimeout(r, retry_after * 1000));
return send(token, channelId, content);
}
return res.json();
}
Rate limits
Channel tokens share Discord's standard per-route rate limits, counted per talker. Every answer carries the usual X-RateLimit-* headers, and a 429 carries retry_after in seconds.