# 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 <key>` | 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 <token>` | 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.
