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