# Chat integrations overview A chat integration lets you run a chat surface inside your own product (a support widget, an in-game chat, a marketplace inbox) on the Blisscord backend, while your staff answer from an ordinary Blisscord server. ## What an integration is An integration is an application of a special kind. Creating one gives you three things: - **One reserved server.** You pick a server you own when you create the integration, and it is converted into the integration's server. Everything that happens for this integration happens there. - **A bot account** that belongs to the integration and holds the Administrator permission in that server. Its token is your **secret key**. - **Integration routes** under `/integrations/{id}` for opening and closing conversations, admitting your end users, and reading transcripts. ## The mental model - **A channel is a conversation.** Every text channel in the reserved server, other than the two reserved ones below, is exactly one conversation. Your backend opens a conversation by creating a channel (a description, the channel topic, is required) and closes it by deleting the channel. - **`internal`** is a reserved channel for your own staff. It is never a conversation. - **`logging`** is a reserved channel where Blisscord posts a record of every closed conversation, with a link to its transcript. - **Talkers are your end users.** A talker is not a Blisscord account. You describe one with your own identifier and a display name, admit it to a conversation, and receive a **channel token** for it. Its messages appear in the channel like anyone else's. - **Your staff are ordinary members** of the reserved server. They read and answer conversations in the Blisscord client like any other channel. - **Closing writes a transcript.** When a conversation channel is deleted, from your backend or from the client, every message is copied into a transcript first, and the record is posted in `logging`. Only the integration's bot (and platform staff) may create channels in the reserved server. Nobody may create threads there, and the two reserved channels can be neither deleted nor renamed. ## The two credentials | Credential | Header | Who holds it | What it can do | |---|---|---|---| | Secret key | `Authorization: Bot ` | Your backend only | Everything: manage the integration, open and close conversations, admit and revoke talkers, read transcripts, and use the standard Discord bot routes in the reserved server. | | Channel token | `Authorization: Bearer ` | One end user's front end | Read and write in exactly one conversation, as one talker, until it expires. | The secret key is a bot token. Keep it on your server and never send it to a browser or an app. It is shown once when the integration is created and again only when you reset it. A channel token identifies one talker in one channel. It is safe to hand to that end user's browser or app: it cannot see any other channel, cannot list members, and stops working when it expires, when the talker is removed from the conversation, when you revoke the talker, or when the conversation closes. ## Base URLs | Surface | URL | |---|---| | REST API | `https://discord.community/api/v9` | | Gateway (WebSocket) | `wss://gateway.discord.community` | | These docs | `https://developers.discord.community/docs/chat` | The REST API and the gateway speak Discord's v9 protocol. Every Discord library that lets you set the API base URL and the gateway URL works for the backend side with the secret key. ## Rate limits - The **secret key is not rate limited.** Your backend is the other half of the product and is never throttled. - **Channel tokens** share Discord's standard per-route rate limits, counted per talker. A request over the limit answers `429 Too Many Requests` with a body like the one below; `retry_after` is in seconds (a float), and the `Retry-After` header carries the same wait rounded up to whole seconds. ```json { "message": "You are being rate limited.", "retry_after": 1.25, "global": false, "code": 0 } ``` ## Where to go next - [Getting started](/docs/chat/getting-started): the whole flow with curl, from creating the integration to reading a transcript. - [Integrations](/docs/chat/integrations): reading, editing and deleting the integration, and resetting the key. - [Conversations](/docs/chat/conversations): opening, listing and closing conversation channels. - [Talkers](/docs/chat/talkers): admitting, removing and revoking end users. - [Channel tokens](/docs/chat/channel-tokens): what a talker's front end can call, and the gateway. - [Transcripts](/docs/chat/transcripts): the record of closed conversations. - [Errors](/docs/chat/errors): the error shapes and every code you can meet here. --- # Getting started This page walks through the whole life of a conversation with curl: create the integration, keep the key, open a conversation, hand a talker token to your front end, exchange messages, close the conversation and read its transcript. The examples use these placeholder values. Replace them with your own. | Placeholder | Meaning | |---|---| | `$KEY` | Your secret key (the integration's bot token) | | `1287654321098765432` | The integration id (also its application id) | | `1287654321098765500` | The reserved server (guild) id | | `1290000000000000001` | A conversation channel id | | `$TALKER_TOKEN` | A channel token minted for one talker | | `1290000000000000999` | A transcript id | ```sh export API=https://discord.community/api/v9 export KEY='your-secret-key' ``` Your own staff do not need Blisscord accounts either: give each of them a staff talker (`POST /integrations/@me/talkers`), whose one token reaches every conversation. Tokens expire; renew any of them with `POST /integrations/@me/talkers/{external_id}/token`. Both are described under [Talkers](/docs/chat/talkers). ## 1. Create the integration Integrations are created in the developer portal at `https://developers.discord.community/integrations`. Your account needs chat integration access, which platform staff grant; without it the portal says you do not have access. The portal asks for: 1. A **name** (2 to 100 characters) and a **description** (1 to 400 characters). 2. A **server you own** to convert. Mirrors, student hubs and servers that already belong to an integration cannot be used. 3. A confirmation. Converting the server keeps one text channel (the system channel, or the first text channel) and renames it `internal`, creates `logging`, and deletes every other channel. The messages of each deleted channel are saved as a transcript first. **This cannot be undone**, so use a new, empty server if you can. The portal calls `POST /integrations` with your signed-in session and the body `{"name", "description", "guild_id"}`. The answer is the [integration object](/docs/chat/integrations) plus one extra field, `token`: your secret key. ## 2. Keep the key The secret key is shown once. Store it in your backend's secret store. It is a bot token, sent as `Authorization: Bot `, and it is never rate limited. If you lose it, reset it (see [Integrations](/docs/chat/integrations)); the old key stops working at once. Check that it works. With the secret key, address your own integration as `@me`: ```sh curl -s "$API/integrations/@me" -H "Authorization: Bot $KEY" ``` ```json { "id": "1287654321098765432", "name": "Acme Support", "description": "Customer support chat for acme.example", "icon": null, "guild_id": "1287654321098765500", "guild": { "id": "1287654321098765500", "name": "Acme Support Desk", "icon": null }, "internal_channel_id": "1287654321098765501", "logging_channel_id": "1287654321098765502", "channel_cap": 500, "live_channels": 0, "token_ttl_seconds": 86400, "bot": { "id": "1287654321098765433", "username": "Acme Support", "discriminator": "0", "avatar": null, "bot": true }, "owner_id": "1100000000000000001", "created_at": "2026-09-23T10:00:00.000000+00:00", "docs_url": "https://developers.discord.community/docs/chat" } ``` > Use `@me` with the secret key on every `/integrations/{id}` route. The numeric id is for the portal, where you are signed in as the integration's owner; with the secret key it answers `403` Missing Access. ## 3. Open a conversation Create a channel with a name, a required topic (the description of the conversation, shown to your staff), and the talkers to admit. Each talker gets a channel token in the answer. ```sh curl -s -X POST "$API/integrations/@me/channels" \ -H "Authorization: Bot $KEY" -H "Content-Type: application/json" \ -d '{ "name": "order-4471", "topic": "Customer asks where order 4471 is. Priority: normal.", "talkers": [ { "external_id": "customer-88213", "username": "Dana", "avatar_url": "https://acme.example/avatars/88213.png" } ] }' ``` ```json { "id": "1290000000000000001", "type": 0, "guild_id": "1287654321098765500", "name": "order-4471", "topic": "Customer asks where order 4471 is. Priority: normal.", "position": 2, "talkers": [ { "id": "1290000000000000050", "external_id": "customer-88213", "username": "Dana", "avatar": "5b1c0e8f2a9d4c3e7f6a1b2c3d4e5f60", "user": { "id": "1290000000000000050", "username": "Dana", "global_name": "Dana", "discriminator": "0", "avatar": "5b1c0e8f2a9d4c3e7f6a1b2c3d4e5f60", "bot": false }, "token": "MTI5MDAwMDAwMDAwMDAwMDA1MDoxMjkwMDAwMDAwMDAwMDAwMDAx.AAAAAGj0Wlo.q3Jd...", "expires_at": "2026-09-24T10:05:00.000000+00:00" } ] } ``` The channel object is abbreviated here; it is the full Discord channel object. Your staff now see `#order-4471` in the reserved server. ## 4. Hand the token to your front end Send `talkers[0].token` to Dana's browser or app, for example in the response of your own "start chat" endpoint. Never send the secret key. The token works only in channel `1290000000000000001`, only as Dana, until `expires_at` (24 hours by default). ## 5. Send and receive messages From the front end, with the channel token: ```sh curl -s -X POST "$API/channels/1290000000000000001/messages" \ -H "Authorization: Bearer $TALKER_TOKEN" -H "Content-Type: application/json" \ -d '{"content": "Hi, my order 4471 has not arrived yet."}' ``` Read the history: ```sh curl -s "$API/channels/1290000000000000001/messages?limit=50" \ -H "Authorization: Bearer $TALKER_TOKEN" ``` For live updates the front end connects to the gateway with the same token and receives `MESSAGE_CREATE` for every new message in the channel. See [Channel tokens](/docs/chat/channel-tokens) for the full list of calls and a WebSocket example. Your backend can post into the conversation too, with the secret key, using the ordinary Discord route: ```sh curl -s -X POST "$API/channels/1290000000000000001/messages" \ -H "Authorization: Bot $KEY" -H "Content-Type: application/json" \ -d '{"content": "Thanks Dana, a support agent will be with you shortly."}' ``` Your staff answer from the Blisscord client, and their messages reach Dana the same way. ## 6. Close the conversation ```sh curl -s -X DELETE "$API/integrations/@me/channels/1290000000000000001" \ -H "Authorization: Bot $KEY" ``` The channel is transcribed, deleted, and logged in `logging`. Dana's session receives `CHANNEL_DELETE` and her token stops working. The answer is the transcript: ```json { "id": "1290000000000000999", "channel_id": "1290000000000000001", "channel_name": "order-4471", "topic": "Customer asks where order 4471 is. Priority: normal.", "opened_at": "2026-09-23T10:05:00.000000+00:00", "closed_at": "2026-09-23T10:31:12.000000+00:00", "closed_by": "1287654321098765433", "closed_via": "api", "message_count": 7, "participants": [ { "id": "1290000000000000050", "username": "Dana", "avatar": "5b1c0e8f2a9d4c3e7f6a1b2c3d4e5f60", "kind": "talker" }, { "id": "1287654321098765433", "username": "Acme Support", "avatar": null, "kind": "bot" }, { "id": "1100000000000000007", "username": "sam", "avatar": null, "kind": "user" } ], "log_message_id": "1290000000000001000", "url": "https://discord.community/integrations/transcripts/1290000000000000999?sig=Qm9ndXNTaWduYXR1cmU" } ``` Staff can also close a conversation by deleting the channel in the client; the transcript is written the same way, with `closed_via` set to `client`. ## 7. Read the transcript ```sh curl -s "$API/integrations/@me/transcripts/1290000000000000999" \ -H "Authorization: Bot $KEY" ``` This answers the same object with a `messages` array. List every transcript, newest first, with `GET /integrations/@me/transcripts`. See [Transcripts](/docs/chat/transcripts). --- # Integrations The integration object describes your integration, its reserved server and its limits; these routes read, edit and delete it and reset its secret key. Every route here takes the integration id in the path. With the **secret key** (`Authorization: Bot `) use `@me` or your own integration's id; any other id answers `403` Missing Access. In the developer portal, signed in as the owner (or a team member of the application), the numeric id is used. ## The integration object | Field | Type | Description | |---|---|---| | `id` | snowflake | The integration id, which is also its application id. | | `name` | string | The name, 2 to 100 characters. | | `description` | string | The description, 1 to 400 characters. | | `icon` | ?string | The application icon hash, or `null`. | | `guild_id` | snowflake | The reserved server's id. | | `guild` | ?object | `{id, name, icon}` of the reserved server, or `null` if it cannot be read. | | `internal_channel_id` | ?snowflake | The reserved `internal` channel. | | `logging_channel_id` | ?snowflake | The reserved `logging` channel. | | `channel_cap` | integer | How many conversation channels may be open at once. The two reserved channels do not count. Default 500; only platform staff can change it. | | `live_channels` | integer | How many conversation channels are open now. | | `token_ttl_seconds` | integer | The default lifetime of a channel token minted without `expires_in`. Default 86400 (24 hours); only platform staff can change it, within 60 seconds to 30 days. | | `bot` | ?user | The integration's bot user, a Discord user object. | | `owner_id` | snowflake | The account that owns the integration. | | `created_at` | ISO 8601 timestamp | When the integration was created. | | `docs_url` | string | A link to these docs. | Example: ```json { "id": "1287654321098765432", "name": "Acme Support", "description": "Customer support chat for acme.example", "icon": null, "guild_id": "1287654321098765500", "guild": { "id": "1287654321098765500", "name": "Acme Support Desk", "icon": null }, "internal_channel_id": "1287654321098765501", "logging_channel_id": "1287654321098765502", "channel_cap": 500, "live_channels": 3, "token_ttl_seconds": 86400, "bot": { "id": "1287654321098765433", "username": "Acme Support", "discriminator": "0", "avatar": null, "bot": true }, "owner_id": "1100000000000000001", "created_at": "2026-09-23T10:00:00.000000+00:00", "docs_url": "https://developers.discord.community/docs/chat" } ``` ## Get the integration `GET /integrations/{id}` Answers the integration object. ```sh curl -s https://discord.community/api/v9/integrations/@me -H "Authorization: Bot $KEY" ``` ## Edit the integration `PATCH /integrations/{id}` | Field | Type | Rule | |---|---|---| | `name` | string, optional | 2 to 100 characters after trimming. Error: `Must be between 2 and 100 characters`. | | `description` | string, optional | 1 to 400 characters after trimming. Error: `Must be between 1 and 400 characters`. | Answers the updated integration object. Fields you leave out are unchanged. ```sh curl -s -X PATCH https://discord.community/api/v9/integrations/@me \ -H "Authorization: Bot $KEY" -H "Content-Type: application/json" \ -d '{"description": "Customer support and returns chat for acme.example"}' ``` ## Delete the integration `DELETE /integrations/{id}` Removes the integration. The reserved server loses its integration status and becomes an ordinary server again: it keeps its channels and its members, and the channel and thread restrictions are lifted. The application is deleted the way any application is, which removes its bot from the server. The integration's talkers and transcripts are deleted with it, including the pages the logging links point to, so export any transcript you need first. Answers `204 No Content`. ```sh curl -s -X DELETE https://discord.community/api/v9/integrations/@me -H "Authorization: Bot $KEY" ``` ## Reset the secret key `POST /integrations/{id}/key/reset` Mints a new secret key and invalidates the old one at once. Every gateway session of the bot is disconnected. Answers: ```json { "token": "MTI4NzY1NDMyMTA5ODc2NTQzMw.Gx7aQb.new-secret-key-shown-once" } ``` The new key is shown only in this answer. If you call this with the secret key itself, the key you used stops working as soon as the answer is sent, so store the new one before doing anything else. ```sh curl -s -X POST https://discord.community/api/v9/integrations/@me/key/reset -H "Authorization: Bot $KEY" ``` ## Listing and creating (portal only) `GET /integrations` lists the integrations the signed-in account owns, and `POST /integrations` creates one (`{"name", "description", "guild_id"}`, answering the integration object plus `token`). Both need a signed-in account with chat integration access and are what the developer portal uses; they are not available with the secret key. An account may own at most 25 integrations; the 26th answers `400` with code 30001, `Maximum number of integrations reached`. --- # Conversations A conversation is one text channel in the integration's reserved server; these routes open, list and close them, and the standard Discord channel routes work on them as well. All routes on this page are called by your backend with the secret key (`Authorization: Bot `), addressing the integration as `@me`. ## Rules of the reserved server - Every text channel except `internal` and `logging` is a conversation. - Only the integration's bot (and platform staff) can create channels. Anyone else is refused with `403`, code 50013: `This server is reserved for a chat integration; conversations are opened by the integration`. - Only text channels (type `0`) can be created. Any other type answers `400` Invalid Form Body on `type`: `A chat integration server holds text channels only`. - Every conversation needs a topic, the description of the conversation your staff see. A missing or blank topic answers `400` Invalid Form Body on `topic`: `A description of the conversation is required`. - The number of open conversations is capped by the integration's `channel_cap` (default 500). Opening one more answers `400` with code 30013: `Maximum number of guild channels reached (500)`, with your cap in the parentheses. - Nobody can create a thread in the reserved server. A thread would escape the transcript when its channel closes. Thread creation answers `403`, code 50013, with the same message as above. - `internal` and `logging` cannot be deleted (`403`, code 50013: `This channel is reserved for the chat integration and cannot be deleted`) or renamed (`400` Invalid Form Body on `name`: `This channel is reserved for the chat integration and keeps its name`). They can be neither opened nor closed through the integration routes. ## List open conversations `GET /integrations/{id}/channels` Answers every open conversation as a Discord channel object with one extra field, `talkers`: the talkers admitted to it (see [Talkers](/docs/chat/talkers) for the talker object). Tokens are never listed. ```sh curl -s https://discord.community/api/v9/integrations/@me/channels -H "Authorization: Bot $KEY" ``` ```json [ { "id": "1290000000000000001", "type": 0, "guild_id": "1287654321098765500", "name": "order-4471", "topic": "Customer asks where order 4471 is. Priority: normal.", "position": 2, "talkers": [ { "id": "1290000000000000050", "external_id": "customer-88213", "username": "Dana", "avatar": null, "user": { "id": "1290000000000000050", "username": "Dana", "global_name": "Dana", "discriminator": "0", "avatar": null, "bot": false } } ] } ] ``` ## Open a conversation `POST /integrations/{id}/channels` | Field | Type | Rule | |---|---|---| | `name` | string | Required, 1 to 100 characters after trimming. Error: `Must be between 1 and 100 characters`. | | `topic` | string | Required, the description of the conversation, up to 1024 characters. Errors: `A description of the conversation is required`, `Must be 1024 or fewer in length`. | | `talkers` | array, optional | Up to 25 talkers to admit at once. Error on `talkers`: `At most 25 talkers per request`. | Each entry of `talkers`: | Field | Type | Rule | |---|---|---| | `external_id` | string | Required, 1 to 191 characters. Your own stable identifier for this end user. The same `external_id` always names the same talker in your integration. | | `username` | string | Required, 1 to 80 characters. The display name shown on messages. | | `avatar_url` | string, optional | An `https://` URL of the avatar picture. Blisscord copies the image and serves it from its own CDN; if the image cannot be fetched the talker has no avatar. Leaving it out or passing an empty string leaves the talker with no avatar, even if an earlier admission set one, so pass it every time. | | `expires_in` | integer, optional | Seconds until this talker's token expires, 60 to 2592000 (30 days). Defaults to the integration's `token_ttl_seconds`. | An invalid entry answers `400` Invalid Form Body on `talkers.` with one of `external_id must be between 1 and 191 characters`, `username must be between 1 and 80 characters`, `avatar_url must be an https URL` or `expires_in must be between 60 seconds and 30 days`, and nothing is created. The answer is `201 Created` with the Discord channel object plus `talkers`, each a talker object with two extra fields: | Field | Type | Description | |---|---|---| | `token` | string | The channel token for this talker in this channel. Shown only here. | | `expires_at` | ISO 8601 timestamp | When the token stops working. | ```sh curl -s -X POST https://discord.community/api/v9/integrations/@me/channels \ -H "Authorization: Bot $KEY" -H "Content-Type: application/json" \ -d '{ "name": "order-4471", "topic": "Customer asks where order 4471 is. Priority: normal.", "talkers": [ { "external_id": "customer-88213", "username": "Dana", "expires_in": 7200 } ] }' ``` ```json { "id": "1290000000000000001", "type": 0, "guild_id": "1287654321098765500", "name": "order-4471", "topic": "Customer asks where order 4471 is. Priority: normal.", "position": 2, "talkers": [ { "id": "1290000000000000050", "external_id": "customer-88213", "username": "Dana", "avatar": null, "user": { "id": "1290000000000000050", "username": "Dana", "global_name": "Dana", "discriminator": "0", "avatar": null, "bot": false }, "token": "MTI5MDAwMDAwMDAwMDAwMDA1MDoxMjkwMDAwMDAwMDAwMDAwMDAx.AAAAAGj0dnw.q3Jd...", "expires_at": "2026-09-23T12:05:00.000000+00:00" } ] } ``` If a talker could not be admitted because of a server-side failure, it is left out of `talkers` while the channel is still created; compare the answer with your request and admit the missing talker again with `POST /integrations/{id}/channels/{channel_id}/talkers`. You can also open a conversation with no talkers and admit them later. Everyone who can see the channel, including admitted talkers, receives `CHANNEL_CREATE`. ## Close a conversation `DELETE /integrations/{id}/channels/{channel_id}` Copies every message into a transcript, deletes the channel, and posts the record in `logging`. Everyone who could see the channel, talkers included, receives `CHANNEL_DELETE`, and every channel token for it stops working. The answer is `200 OK` with the transcript object (without `messages`; see [Transcripts](/docs/chat/transcripts)), with `closed_via` set to `api`. ```sh curl -s -X DELETE https://discord.community/api/v9/integrations/@me/channels/1290000000000000001 \ -H "Authorization: Bot $KEY" ``` A `channel_id` that is not an open conversation of this integration (including `internal` and `logging`) answers `404`, code 10003, `Unknown Channel`. A member of the reserved server with Manage Channels (your staff) can also close a conversation by deleting the channel in the client. The transcript is written the same way, with `closed_via` set to `client` and `closed_by` set to that member. ## Standard Discord routes The reserved server is an ordinary Discord guild to your bot, so any Discord library works for the backend side with the secret key. The integration routes above exist because they do several things in one call (admitting talkers, answering with the transcript); these standard routes are equivalent where they overlap. | Route | Notes | |---|---| | `POST /guilds/{guild_id}/channels` | Opens a conversation. The same rules apply: type `0` only, `topic` required, the cap. Answers `201` with the channel object. It admits no talkers; call the talker route afterwards. | | `DELETE /channels/{channel_id}` | Closes a conversation exactly like the integration route (transcript, delete, log, `closed_via` `api`), but answers with the deleted channel object as Discord does. | | `PATCH /channels/{channel_id}` | Renames a conversation or edits its topic. The two reserved channels keep their names. | | `GET /channels/{channel_id}/messages` | Reads history, with `before`, `after`, `around` and `limit` (1 to 100, default 50). | | `POST /channels/{channel_id}/messages` | Posts as the integration's bot. Bots may send embeds. | The gateway works as for any bot: identify with the secret key and receive `MESSAGE_CREATE`, `CHANNEL_CREATE`, `CHANNEL_DELETE` and the rest for the reserved server, subject to your intents. ```sh curl -s -X POST https://discord.community/api/v9/guilds/1287654321098765500/channels \ -H "Authorization: Bot $KEY" -H "Content-Type: application/json" \ -d '{"name": "refund-9912", "type": 0, "topic": "Refund request for order 9912."}' ``` --- # Talkers A talker is one of your end users as it appears in a conversation; these routes admit talkers to conversations, remove them, and revoke their tokens. ## What a talker is - A talker is **not an account**. It cannot sign in, has no password, cannot be befriended or messaged directly, and never appears in the server's member list. - A talker belongs to your integration and is identified by your own `external_id`. Admitting the same `external_id` again, to the same or another conversation, reuses the same talker (the same `id`) and overwrites its `username` with what you send. `avatar_url` replaces the avatar when sent; an admission without it keeps the avatar the talker already has. - On messages a talker looks like any author: its messages carry a Discord user object with its `id`, `username`, `global_name` (the same as `username`), `discriminator` `"0"` and `avatar`. - A talker can only act through a [channel token](/docs/chat/channel-tokens), and a channel token names one talker in one conversation. - A talker can read and send messages, edit and delete its own messages, and show typing. It cannot react, upload attachments or send embeds, and it has no management permissions. ## Two kinds of talker A talker is anyone your backend admits, your end users and your own staff alike; nobody on your side needs a Blisscord account. There are two scopes: - A **conversation talker** is admitted to named conversations (when you open one, or with `POST .../channels/{channel_id}/talkers`) and holds one channel token per conversation. Use this for end users. - A **staff talker** is admitted to every conversation of your integration, present and future, and holds one integration-wide token. One socket carries every conversation's events plus `CHANNEL_CREATE` when a new one opens, and the same token sends into any of them. Use this for the people who answer conversations in your product. Create one with `POST /integrations/@me/talkers` (below); it sets `all_channels: true`. ## The talker object | Field | Type | Description | |---|---|---| | `id` | snowflake | The talker's id, which is also the author id on its messages. | | `external_id` | string | Your identifier for this end user. | | `username` | string | The display name. | | `avatar` | ?string | The avatar hash, served at `https://cdn.discord.community/avatars/{id}/{avatar}.png`, or `null`. | | `user` | user | The talker as a Discord user object, exactly as it appears on its messages. | When a token is minted the object also carries `token` and `expires_at`. ## Token lifetime - A channel token expires after the integration's `token_ttl_seconds`, 86400 seconds (24 hours) unless platform staff changed it for your integration. - Pass `expires_in` (seconds) when admitting a talker to choose another lifetime for that token, from 60 seconds to 30 days (2592000 seconds). - A token cannot be renewed. To give an end user a fresh token, admit the same `external_id` to the same channel again: you get a new token, and the old one keeps working until it expires or is revoked. - A token also stops working when the talker is removed from the conversation, when the talker is revoked, and when the conversation closes. ## Admit a talker `POST /integrations/{id}/channels/{channel_id}/talkers` The body is one talker, with the same fields as an entry of `talkers` when [opening a conversation](/docs/chat/conversations): `external_id`, `username`, optional `avatar_url` and optional `expires_in`. Any validation failure answers `400` Invalid Form Body on `external_id`, with the message naming the field at fault (for example `username must be between 1 and 80 characters`). Answers `201 Created` with the talker object plus `token`, `expires_at` and `channel_id`. ```sh curl -s -X POST https://discord.community/api/v9/integrations/@me/channels/1290000000000000001/talkers \ -H "Authorization: Bot $KEY" -H "Content-Type: application/json" \ -d '{"external_id": "customer-88213", "username": "Dana", "expires_in": 3600}' ``` ```json { "id": "1290000000000000050", "external_id": "customer-88213", "username": "Dana", "avatar": null, "user": { "id": "1290000000000000050", "username": "Dana", "global_name": "Dana", "discriminator": "0", "avatar": null, "bot": false }, "token": "MTI5MDAwMDAwMDAwMDAwMDA1MDoxMjkwMDAwMDAwMDAwMDAwMDAx.AAAAAGj0aHM.Zk9r...", "expires_at": "2026-09-23T11:05:00.000000+00:00", "channel_id": "1290000000000000001" } ``` A `channel_id` that is not an open conversation of this integration answers `404`, code 10003, `Unknown Channel`. ## Create a staff talker `POST /integrations/@me/talkers` with the same body as an admission (`external_id`, `username`, optional `avatar_url`, optional `expires_in`). The talker is created or refreshed with `all_channels: true` and the answer carries its integration-wide token: `channel_id` is `null` and the token works in every conversation channel of your server. ```bash curl -s -X POST https://discord.community/api/v9/integrations/@me/talkers \ -H "Authorization: Bot $KEY" -H "Content-Type: application/json" \ -d '{"external_id":"agent-7","username":"Sam (Support)"}' ``` A staff talker never appears in a member list and cannot open or close conversations; those stay with your secret key. ## Renew a token Tokens expire (the default lifetime is per integration, 24 hours unless staff changed it). A conversation that lasts longer keeps going: mint a fresh token for an admission that already exists with `POST /integrations/@me/talkers/{external_id}/token`. Nothing about the talker changes, so its messages keep the same author. ```bash curl -s -X POST https://discord.community/api/v9/integrations/@me/talkers/customer-88213/token \ -H "Authorization: Bot $KEY" -H "Content-Type: application/json" \ -d '{"channel_id":"1290000000000000001","expires_in":86400}' ``` `channel_id` names a conversation the talker is admitted to; leave it out for a staff talker to get a new integration-wide token. A talker admitted per conversation must name one (`400`, field `channel_id`). The answer is the talker object plus `token`, `expires_at` and `channel_id`. `GET /integrations/@me/talkers/{external_id}` answers the talker object plus `channel_ids`, the conversations it is admitted to. ## Remove a talker from a conversation `DELETE /integrations/{id}/channels/{channel_id}/talkers/{external_id}` Removes the talker's admission to this conversation. Every token for this talker in this channel stops working at once, and the talker's gateway sessions are disconnected. Tokens for the talker's other conversations keep working (they reconnect with them). Answers `204 No Content`. URL-encode `external_id` if it contains anything other than letters, digits, `-`, `_`, `.` and `~`. ```sh curl -s -X DELETE https://discord.community/api/v9/integrations/@me/channels/1290000000000000001/talkers/customer-88213 \ -H "Authorization: Bot $KEY" ``` An unknown `external_id` answers `404`, code 10013, `Unknown User`. ## Revoke every token of a talker `POST /integrations/{id}/talkers/{external_id}/revoke` Invalidates every channel token ever minted for this talker, in every conversation, and disconnects its gateway sessions. The talker stays admitted to its conversations; admit it again to mint new tokens. Use this when an end user logs out of your product or their session there is compromised. Answers `204 No Content`. ```sh curl -s -X POST https://discord.community/api/v9/integrations/@me/talkers/customer-88213/revoke \ -H "Authorization: Bot $KEY" ``` An unknown `external_id` answers `404`, code 10013, `Unknown User`. --- # 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 ``` 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": "", "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=` 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. --- # Transcripts A transcript is the permanent record of a closed conversation, written before its channel is deleted; these routes list and read them, and this page describes the logging message and the signed transcript page. Every conversation leaves a transcript, however it was closed: through `DELETE /integrations/{id}/channels/{channel_id}`, through `DELETE /channels/{channel_id}`, by a member deleting the channel in the client, or by the conversion that created the integration (each channel the conversion swept away leaves one too). ## The transcript object | Field | Type | Description | |---|---|---| | `id` | snowflake | The transcript id. | | `channel_id` | snowflake | The id the conversation channel had. The channel no longer exists. | | `channel_name` | string | The channel's name when it closed. | | `topic` | ?string | The conversation's description, or `null`. | | `opened_at` | ISO 8601 timestamp | When the channel was created. | | `closed_at` | ISO 8601 timestamp | When it was closed. | | `closed_by` | ?snowflake | Who closed it: the integration's bot for `api`, the member for `client`, the account that confirmed the conversion for `conversion`. | | `closed_via` | string | `api` (the secret key), `client` (a member of the server, in the client) or `conversion` (swept when the server was converted). | | `message_count` | integer | How many messages the transcript holds. | | `participants` | array | Everyone who wrote in the conversation, plus every talker admitted to it even if they never spoke. Each entry is `{id, username, avatar, kind}`, where `kind` is `user` (a member of the server), `talker` or `bot`. | | `log_message_id` | ?snowflake | The message in `logging` that records this transcript, or `null` if it could not be posted. | | `url` | string | The signed link to the transcript page, the same link the logging message carries. | Timestamps look like `2026-09-23T10:31:12.000000+00:00`. ## List transcripts `GET /integrations/{id}/transcripts` Answers transcript objects (without `messages`), newest first. | Query | Description | |---|---| | `before` | Only transcripts with an id lower than this one. Pass the last id of the previous page to page backwards. | | `limit` | 1 to 100. Defaults to 50; any value outside 1 to 100 also means 50. | ```sh curl -s "https://discord.community/api/v9/integrations/@me/transcripts?limit=20" -H "Authorization: Bot $KEY" ``` ## Get one transcript `GET /integrations/{id}/transcripts/{transcript_id}` Answers the transcript object plus `messages`, oldest first. A transcript that does not exist or belongs to another integration answers `404` with `{"message": "Unknown Transcript", "code": 0}`. Each message: | Field | Type | Description | |---|---|---| | `id` | snowflake | The message id. Like every snowflake it encodes when the message was sent. | | `author` | user | The author as a Discord user object, as it was when the conversation closed. | | `content` | string | The text. | | `attachments` | array | Discord attachment objects (`id`, `filename`, `size`, `url`, ...). | | `embeds` | array | Discord embed objects. | | `type` | integer | The Discord message type (`0` default, `19` reply). | | `edited_timestamp` | ?ISO 8601 timestamp | When it was last edited, or `null`. | | `message_reference` | ?object | The Discord message reference for a reply, or `null`. | ```sh curl -s https://discord.community/api/v9/integrations/@me/transcripts/1290000000000000999 -H "Authorization: Bot $KEY" ``` ```json { "id": "1290000000000000999", "channel_id": "1290000000000000001", "channel_name": "order-4471", "topic": "Customer asks where order 4471 is. Priority: normal.", "opened_at": "2026-09-23T10:05:00.000000+00:00", "closed_at": "2026-09-23T10:31:12.000000+00:00", "closed_by": "1287654321098765433", "closed_via": "api", "message_count": 2, "participants": [ { "id": "1290000000000000050", "username": "Dana", "avatar": null, "kind": "talker" }, { "id": "1100000000000000007", "username": "sam", "avatar": null, "kind": "user" } ], "log_message_id": "1290000000000001000", "url": "https://discord.community/integrations/transcripts/1290000000000000999?sig=Qm9ndXNTaWduYXR1cmU", "messages": [ { "id": "1290000000000000101", "author": { "id": "1290000000000000050", "username": "Dana", "global_name": "Dana", "discriminator": "0", "avatar": null, "bot": false }, "content": "Hi, my order 4471 has not arrived yet.", "attachments": [], "embeds": [], "type": 0, "edited_timestamp": null, "message_reference": null }, { "id": "1290000000000000102", "author": { "id": "1100000000000000007", "username": "sam", "global_name": "Sam", "discriminator": "0", "avatar": null, "bot": false }, "content": "It left the warehouse this morning, tracking is **AC123456**.", "attachments": [], "embeds": [], "type": 0, "edited_timestamp": null, "message_reference": null } ] } ``` ## The logging message When a conversation closes, Blisscord (the system account) posts one message in the integration's `logging` channel. It carries a single embed: | Part | Content | |---|---| | Title | `Conversation closed: #` | | Description | The topic, or `(no description)` | | Field `Channel` | The channel id | | Field `Messages` | The message count | | Field `Closed by` | The closer's username, `the integration` when no closer is known, or `the server conversion` | | Fields `Opened` and `Closed` | Times like `2026-09-23 10:05 UTC` | | Field `Participants` | Participant usernames separated by commas, or `nobody` | | Field `Transcript` | The signed link to the transcript page | | Footer | `Transcript ` | Your bot receives it as an ordinary `MESSAGE_CREATE` in `logging`, and `log_message_id` on the transcript points at it. ## The transcript page The link in the logging message, also returned as `url`, opens a page on the Blisscord site: ``` https://discord.community/integrations/transcripts/{transcript_id}?sig= ``` It shows the integration and server, the channel name and topic, when it was opened and closed and by whom, the participants, and every message with its attachments and embeds. Opening it needs **both** of these: - **The signed link.** The signature is tied to the transcript id and never expires. A changed or truncated link answers "This link is not valid". - **A signed-in Blisscord account that is a member of the integration's server**, or platform staff. Someone who is not signed in is asked to log in and returns to the page afterwards; a signed-in account that is not a member is told it cannot view the transcript. So a link that leaks outside your team shows nothing on its own. To show transcripts inside your own product, read them with the secret key through the routes above instead. --- # Errors Every error answers a JSON body with a numeric `code` and a `message`, in Discord's shapes; this page lists the shapes and every code the integration surface uses. ## The error shape ```json { "message": "Missing Access", "code": 50001 } ``` `code` is `0` where Discord uses no specific code (for example `401` and `404` on an unknown transcript). Branch on the HTTP status and `code`, not on `message`. ## The form error shape Validation failures answer `400` with code 50035, `Invalid Form Body`, and name the field at fault under `errors`: ```json { "message": "Invalid Form Body", "code": 50035, "errors": { "topic": { "_errors": [ { "code": "BASE_TYPE_INVALID", "message": "A description of the conversation is required" } ] } } } ``` The key under `errors` is the field name. For a bad entry in the `talkers` array when opening a conversation it is `talkers.`, for example `talkers.0`. Read the human-readable reason from `errors.._errors[].message`. ## Codes | HTTP | Code | Message | When | |---|---|---|---| | 400 | 50035 | `Invalid Form Body` | A field failed validation. See the form error shape above and the field rules on each page. | | 400 | 30013 | `Maximum number of guild channels reached ()` | Opening a conversation while `channel_cap` conversations are already open. Close one first, or ask platform staff to raise the cap. | | 400 | 30001 | `Maximum number of integrations reached` | Creating a 26th integration from the portal. | | 401 | 0 | `401: Unauthorized` | No credential, or one that is invalid: a reset secret key, or a channel token that expired, was revoked, names a talker removed from the conversation, or belongs to a closed conversation. | | 403 | 50001 | `Missing Access` | The credential is valid but may not use this route: a channel token on any route outside its own channel, the secret key on another integration or on a numeric integration id instead of `@me`, or a signed-in account without chat integration access. Also a signed-in account that is not a member of the server, opening a transcript page. | | 403 | 50013 | `Missing Permissions` | A talker trying to attach files or to delete someone else's message. | | 403 | 50013 | `Cannot edit a message authored by another user` | A talker editing someone else's message. | | 403 | 50013 | `This server is reserved for a chat integration; conversations are opened by the integration` | Anyone other than the integration's bot creating a channel in the reserved server, or anyone creating a thread there. | | 403 | 50013 | `This channel is reserved for the chat integration and cannot be deleted` | Deleting `internal` or `logging`. | | 404 | 10002 | `Unknown Application` | The integration id does not exist or is not a chat integration, or `@me` was used without the secret key. | | 404 | 10003 | `Unknown Channel` | The `channel_id` on an integration route is not an open conversation of this integration (it never existed, it closed, or it is `internal` or `logging`). | | 404 | 10013 | `Unknown User` | No talker with that `external_id` exists in this integration. | | 404 | 0 | `Unknown Transcript` | The transcript does not exist, belongs to another integration, or the signature on a transcript link is wrong. | | 429 | 0 | `You are being rate limited.` | A channel token went over a route's rate limit. Wait `retry_after` seconds (a float) and retry. The secret key is never rate limited. | Three refusals specific to the reserved server are form errors (code 50035) rather than codes of their own: | Field | Message | When | |---|---|---| | `name` | `This channel is reserved for the chat integration and keeps its name` | Renaming `internal` or `logging`. | | `type` | `A chat integration server holds text channels only` | Creating any channel other than a text channel in the reserved server. | | `topic` | `A description of the conversation is required` | Opening a conversation with no topic, through either route. | ## The 429 body ```json { "message": "You are being rate limited.", "retry_after": 0.734, "global": false, "code": 0 } ``` The `Retry-After` header carries the same wait rounded up to whole seconds, and the `X-RateLimit-*` headers describe the bucket as on Discord.