# Organization API: Discord

> Your own Discord bot: application credentials, the staff channel that receives tickets, and which Discord accounts are staff.

Source: https://docs.coritan.com/api/reference/organizations/discord/

Your own Discord bot: application credentials, the staff channel that receives tickets, and which Discord accounts are staff. The bot token is write-only: we store it encrypted and never return it.

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Organization API reference](https://api.coritan.com/docs/org).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/discord`](#op-get-api-v1-orgs-org-slug-discord) | Get discord config |
| PUT | [`/api/v1/orgs/{org_slug}/discord`](#op-put-api-v1-orgs-org-slug-discord) | Put discord config |
| DELETE | [`/api/v1/orgs/{org_slug}/discord`](#op-delete-api-v1-orgs-org-slug-discord) | Switch the bot off and forget the token |
| POST | [`/api/v1/orgs/{org_slug}/discord/community/sync-channels`](#op-post-api-v1-orgs-org-slug-discord-community-sync-channels) | Rebuild the public-channel allowlist from Discord's own permissions |
| GET | [`/api/v1/orgs/{org_slug}/discord/diagnostics`](#op-get-api-v1-orgs-org-slug-discord-diagnostics) | Probe the bot, the guild, the staff channel and the job queue |
| POST | [`/api/v1/orgs/{org_slug}/discord/register-commands`](#op-post-api-v1-orgs-org-slug-discord-register-commands) | Register commands |
| GET | [`/api/v1/orgs/{org_slug}/discord/role-menus`](#op-get-api-v1-orgs-org-slug-discord-role-menus) | List role menus |
| POST | [`/api/v1/orgs/{org_slug}/discord/role-menus`](#op-post-api-v1-orgs-org-slug-discord-role-menus) | Create role menu |
| PUT | [`/api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}`](#op-put-api-v1-orgs-org-slug-discord-role-menus-menu-id) | Update role menu |
| DELETE | [`/api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}`](#op-delete-api-v1-orgs-org-slug-discord-role-menus-menu-id) | Delete role menu |
| POST | [`/api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}/publish`](#op-post-api-v1-orgs-org-slug-discord-role-menus-menu-id-publish) | Post the menu to its channel, or edit the message already posted for it |
| GET | [`/api/v1/orgs/{org_slug}/discord/roles`](#op-get-api-v1-orgs-org-slug-discord-roles) | The roles in the org's guild, so a menu can be built by picking not typing |
| GET | [`/api/v1/orgs/{org_slug}/discord/staff`](#op-get-api-v1-orgs-org-slug-discord-staff) | List staff links |
| PUT | [`/api/v1/orgs/{org_slug}/discord/staff`](#op-put-api-v1-orgs-org-slug-discord-staff) | Put staff link |
| DELETE | [`/api/v1/orgs/{org_slug}/discord/staff/{discord_user_id}`](#op-delete-api-v1-orgs-org-slug-discord-staff-discord-user-id) | Delete staff link |

### Get discord config {#op-get-api-v1-orgs-org-slug-discord}

`GET /api/v1/orgs/{org_slug}/discord`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `configured` | boolean |
| `application_id` | string or null |
| `public_key` | string or null |
| `guild_id` | string or null |
| `staff_channel_id` | string or null |
| `staff_channel_kind` | string |
| `is_enabled` | boolean |
| `has_bot_token` | boolean |
| `commands_registered_at` | string (date-time) or null |
| `interactions_url` | string or null |
| `last_error` | string or null |
| `gateway_status` | string |
| `bot_user_id` | string or null |
| `ticket_channels_enabled` | boolean |
| `ticket_category_prefix` | string |
| `staff_role_id` | string or null |
| `max_ticket_channels` | integer |
| `community_chat_enabled` | boolean |
| `community_invite_url` | string or null |
| `community_hidden_channels` | array of string |

### Put discord config {#op-put-api-v1-orgs-org-slug-discord}

`PUT /api/v1/orgs/{org_slug}/discord`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `application_id` | string | yes |
| `public_key` | string | yes |
| `bot_token` | string or null | no |
| `guild_id` | string or null | no |
| `staff_channel_id` | string or null | no |
| `staff_channel_kind` | string or null | no |
| `is_enabled` | boolean or null | no |
| `ticket_channels_enabled` | boolean or null | no |
| `ticket_category_prefix` | string or null | no |
| `staff_role_id` | string or null | no |
| `max_ticket_channels` | integer or null | no |
| `community_chat_enabled` | boolean or null | no |
| `community_invite_url` | string or null | no |
| `community_hidden_channels` | array of string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `configured` | boolean |
| `application_id` | string or null |
| `public_key` | string or null |
| `guild_id` | string or null |
| `staff_channel_id` | string or null |
| `staff_channel_kind` | string |
| `is_enabled` | boolean |
| `has_bot_token` | boolean |
| `commands_registered_at` | string (date-time) or null |
| `interactions_url` | string or null |
| `last_error` | string or null |
| `gateway_status` | string |
| `bot_user_id` | string or null |
| `ticket_channels_enabled` | boolean |
| `ticket_category_prefix` | string |
| `staff_role_id` | string or null |
| `max_ticket_channels` | integer |
| `community_chat_enabled` | boolean |
| `community_invite_url` | string or null |
| `community_hidden_channels` | array of string |

### Switch the bot off and forget the token {#op-delete-api-v1-orgs-org-slug-discord}

`DELETE /api/v1/orgs/{org_slug}/discord`

Switch the bot off and forget the token.

The row stays so the channel and application ids do not have to be re-entered,
but the credential does not linger on a disabled integration.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Rebuild the public-channel allowlist from Discord's own permissions {#op-post-api-v1-orgs-org-slug-discord-community-sync-channels}

`POST /api/v1/orgs/{org_slug}/discord/community/sync-channels`

Rebuild the public-channel allowlist from Discord's own permissions.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Probe the bot, the guild, the staff channel and the job queue {#op-get-api-v1-orgs-org-slug-discord-diagnostics}

`GET /api/v1/orgs/{org_slug}/discord/diagnostics`

Probe the bot, the guild, the staff channel and the job queue.

Answers "why did my ticket not appear in Discord?" without needing shell access.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Register commands {#op-post-api-v1-orgs-org-slug-discord-register-commands}

`POST /api/v1/orgs/{org_slug}/discord/register-commands`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List role menus {#op-get-api-v1-orgs-org-slug-discord-role-menus}

`GET /api/v1/orgs/{org_slug}/discord/role-menus`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].channel_id` | string or null |
| `[].menu_key` | string or null |
| `[].message_id` | string or null |
| `[].title` | string |
| `[].description` | string or null |
| `[].options` | array of RoleOption |
| `[].options[].role_id` | string |
| `[].options[].label` | string |
| `[].options[].key` | string or null |
| `[].options[].emoji` | string or null |
| `[].options[].description` | string or null |
| `[].is_enabled` | boolean |
| `[].published` | boolean |

### Create role menu {#op-post-api-v1-orgs-org-slug-discord-role-menus}

`POST /api/v1/orgs/{org_slug}/discord/role-menus`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `channel_id` | string or null | no |
| `menu_key` | string or null | no |
| `title` | string | yes |
| `description` | string or null | no |
| `options` | array of RoleOption | no |
| `options[].role_id` | string | yes |
| `options[].label` | string | yes |
| `options[].key` | string or null | no |
| `options[].emoji` | string or null | no |
| `options[].description` | string or null | no |
| `is_enabled` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `channel_id` | string or null |
| `menu_key` | string or null |
| `message_id` | string or null |
| `title` | string |
| `description` | string or null |
| `options` | array of RoleOption |
| `options[].role_id` | string |
| `options[].label` | string |
| `options[].key` | string or null |
| `options[].emoji` | string or null |
| `options[].description` | string or null |
| `is_enabled` | boolean |
| `published` | boolean |

### Update role menu {#op-put-api-v1-orgs-org-slug-discord-role-menus-menu-id}

`PUT /api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `menu_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `channel_id` | string or null | no |
| `menu_key` | string or null | no |
| `title` | string | yes |
| `description` | string or null | no |
| `options` | array of RoleOption | no |
| `options[].role_id` | string | yes |
| `options[].label` | string | yes |
| `options[].key` | string or null | no |
| `options[].emoji` | string or null | no |
| `options[].description` | string or null | no |
| `is_enabled` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `channel_id` | string or null |
| `menu_key` | string or null |
| `message_id` | string or null |
| `title` | string |
| `description` | string or null |
| `options` | array of RoleOption |
| `options[].role_id` | string |
| `options[].label` | string |
| `options[].key` | string or null |
| `options[].emoji` | string or null |
| `options[].description` | string or null |
| `is_enabled` | boolean |
| `published` | boolean |

### Delete role menu {#op-delete-api-v1-orgs-org-slug-discord-role-menus-menu-id}

`DELETE /api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `menu_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Post the menu to its channel, or edit the message already posted for it {#op-post-api-v1-orgs-org-slug-discord-role-menus-menu-id-publish}

`POST /api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}/publish`

Post the menu to its channel, or edit the message already posted for it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `menu_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The roles in the org's guild, so a menu can be built by picking not typing {#op-get-api-v1-orgs-org-slug-discord-roles}

`GET /api/v1/orgs/{org_slug}/discord/roles`

The roles in the org's guild, so a menu can be built by picking not typing.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List staff links {#op-get-api-v1-orgs-org-slug-discord-staff}

`GET /api/v1/orgs/{org_slug}/discord/staff`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].discord_user_id` | string |
| `[].user_id` | integer or null |
| `[].admin_user_id` | integer or null |
| `[].role` | string |
| `[].email` | string or null |

### Put staff link {#op-put-api-v1-orgs-org-slug-discord-staff}

`PUT /api/v1/orgs/{org_slug}/discord/staff`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `discord_user_id` | string | yes |
| `user_id` | integer or null | no |
| `admin_user_id` | integer or null | no |
| `role` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `discord_user_id` | string |
| `user_id` | integer or null |
| `admin_user_id` | integer or null |
| `role` | string |
| `email` | string or null |

### Delete staff link {#op-delete-api-v1-orgs-org-slug-discord-staff-discord-user-id}

`DELETE /api/v1/orgs/{org_slug}/discord/staff/{discord_user_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `discord_user_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |