# 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 <key>`), 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.<index>` 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."}'
```
