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.

RouteWhat it does
GET /channels/{channel_id}The conversation's channel object (name, topic and the rest).
GET /channels/{channel_id}/messagesHistory, 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}/messagesSends 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}/typingShows 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

  • content is required and may be up to 4000 characters. Longer answers 400 Invalid Form Body on content: Must be 4000 or fewer in length. An empty message answers Cannot send an empty message.
  • embeds are 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 as MESSAGE_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_reference works 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
  1. The server sends HELLO (op 10) with heartbeat_interval in milliseconds.
  2. Send IDENTIFY (op 2). token is the bare channel token, without Bearer. intents is ignored for channel tokens; send 0.
{
  "op": 2,
  "d": {
    "token": "<channel token>",
    "intents": 0,
    "properties": { "os": "web", "browser": "acme-chat", "device": "acme-chat" }
  }
}
  1. The server answers READY (op 0, t READY):
{
  "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.

  1. Send HEARTBEAT (op 1) every heartbeat_interval milliseconds, with the last sequence number you received as d (or null before the first dispatch). The server answers HEARTBEAT_ACK (op 11).
  1. Receive dispatches (op 0) for the conversation:
EventWhen
MESSAGE_CREATEA message was sent, by anyone.
MESSAGE_UPDATEA message was edited, or a link in it unfurled.
MESSAGE_DELETEA message was deleted.
TYPING_STARTSomeone is typing.
CHANNEL_UPDATEThe channel's name or topic changed.
CHANNEL_DELETEThe 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_CREATEStaff 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.