# 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](/docs/chat/talkers).

Channel tokens are minted by your backend when it [opens a conversation](/docs/chat/conversations), [admits a talker, creates a staff talker or renews a token](/docs/chat/talkers), 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

- `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.

```sh
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`.

```json
{
  "op": 2,
  "d": {
    "token": "<channel token>",
    "intents": 0,
    "properties": { "os": "web", "browser": "acme-chat", "device": "acme-chat" }
  }
}
```

3. The server answers **READY** (op 0, `t` `READY`):

```json
{
  "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`.

4. 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).

5. 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

```js
// 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.
