Connect a Discord server

Connect a Discord bot of your own to your organization, and your community's Discord server becomes part of your support desk. New tickets appear in a staff channel, customers use slash commands to see their servers and open tickets, members pick roles from menus, and your storefront's community page can show the server's public channels.

• You need the owner or admin role in the organization.
• Create an application with a bot in the Discord developer portal, and note its application ID, public key and bot token.
• Invite the bot to your Discord server. To copy the server and channel IDs, turn on Developer Mode in Discord's settings.

1. Go to Organizations, open your organization, then Growth, then Discord.
2. In the Discord bot card, enter the Application ID, the Public key and the Bot token. We store the token encrypted and never show it again.
3. Enter the Server (guild) ID and the Staff channel ID, the channel where we post new tickets. Under Staff channel kind, choose Text channel or Forum channel.
4. Choose Connect Discord.
5. Copy the Interactions endpoint URL from the card, and paste it into the Discord developer portal under the application's General Information.

The Discord bot card shows Enabled, with the state of the bot's connection to Discord, and the rest of the page appears: Diagnostics, Ticket channels, Community chat, Staff links and Role menus. Connecting queues the registration of the bot's slash commands, and customers can then use them in your server, in a direct message to the bot, or anywhere else they have the bot:

Ticket messages also appear in the ticket's Discord channel or forum post, except internal notes in a channel the customer can read. A file the customer attaches appears there as a line with its name and size; open the ticket in the staff console to download it.

Each card saves on its own. As you change a field, the card's footer counts the changes; choose Save changes to save them, or Discard to put the saved values back. A card sends only what you changed, so saving one card leaves unsaved changes in another alone.

• Discord bot holds the IDs and the token. Leave Bot token empty to keep the stored one, and empty an ID's field to clear it. Untick Integration enabled to keep the settings while the bot stops answering.
• Ticket channels gives each ticket its own private channel that staff and the customer both see. Tick One private channel per ticket, then enter the Staff role ID of the role that answers tickets, a Category prefix for the channel category, and Max open channels, from 1 to 450.
• Community chat shows your server's public channels on your storefront's community page. Tick Mirror public channels on the storefront, add the server's Invite link, and list any public channels to keep off the website in Hidden channels, separated by commas.

• Customers' messages from the website show under their own names when the bot has Discord's Manage Webhooks permission in the channel. Without it, the bot posts them itself, with the name in front.
• A message from your team wears a Staff badge on the website. The bot gives it to whoever holds the role in Staff role ID, to an account with a staff link, and, when you set no staff role, to anyone who manages your server. A display name never earns it.
• For your team to delete a member's message in Discord from the staff console, and for the moderation filter to delete what it refuses, the bot needs Manage Messages. Without it, those messages stay off the website but remain in Discord.
• The website shows mentions by name, custom emoji and Discord's Markdown. It shows attachments and stickers by name, with a link to the message in Discord, never the file itself.
• The mirror leaves out bots, webhooks, system messages and bot commands typed as text, such as /verify 1234.

The chat's own settings (slow mode, links, reports, rules, pausing web chat) and its moderation are on your storefront's staff console, as Moderate the community chat describes.

The Discord actions menu, beside the bot's status, has the rest:

• Register slash commands registers the commands again, for example after you change the application.
• Disconnect… turns the bot off and forgets its token. Type disconnect to confirm. We keep the IDs, so reconnecting only needs a new token: enter it in Bot token, tick Integration enabled and choose Save changes.

The Diagnostics card tests the bot's token, its place in your server, the staff channel, the community channels and our queue of Discord work. Each check shows a detail line when it fails. The card's badge reads All checks pass or Needs attention; after you fix something, select the card's Run checks again button.

Sync community channels, at the foot of the Community chat card, rebuilds the list of public channels from your server's own permissions, and removes channels you deleted in Discord. It needs a server ID, and it shows while the card has no unsaved changes.

A role menu is a message in Discord with one button per role. Members click a button to take the role or drop it.

1. Under Role menus, choose New role menu….
2. Enter a Title for the message and, if you like, a Description.
3. Enter the Channel ID to post in. To map buttons you posted by hand instead, leave it empty and give the menu a Key.
4. Tick the Roles members can choose. The list only offers roles the bot can hand out: roles below its own, and not roles that belong to another integration.
5. Choose Create menu. Then open the menu's actions on its row and choose Publish to Discord to post it.

To change a menu, select its row, change it and choose Save menu. After an edit, Repost to Discord in the row's actions updates the message already posted. Untick Buttons give out roles to keep the menu while its buttons stop giving out roles, even on a message already posted. A menu without a channel ID maps buttons you posted by hand, so there is nothing to publish.

To delete a menu, choose Delete menu… in its row's actions, type the menu's key, or its ID when it has no key, and choose Delete menu. The buttons stop working, but the message stays in Discord until you delete it there.

A staff link tells the bot which member of your team a Discord account belongs to, so a ticket reply they type in Discord is recorded as theirs, with their role. Anyone who holds the role you entered as Staff role ID can also answer tickets, and their replies carry their Discord name.

1. Under Staff links, choose New staff link….
2. Choose the Team member. Only owners, admins and support roles can be linked, because a link works with the member's own role and only those roles answer tickets.
3. Enter their Discord user ID. In Discord, turn on Developer Mode, then right-click the person and choose Copy User ID.
4. Choose Add link.

The table lists each link with the Team member, the Discord user, the Role and a Status. In force means the bot honours the link. Not in force comes with the reason: the person is No longer a member, or their role cannot work tickets. A link that Coritan's own staff set up for your server reads Coritan staff.

To give a Discord account to another member, select the link's row, choose the Team member and choose Save link. To link another Discord account instead, add a new link and remove the old one. To remove a link, choose Remove link… in its row's actions and confirm with Remove link. The person keeps their place in your organization. A link for someone who has left the organization can only be removed.

No Discord server configured

Syncing channels and listing roles need a server. Enter the Server (guild) ID in the Discord bot card and choose Save changes.

No bot token configured

The integration has no token, for example after a disconnect. Enter one in Bot token, tick Integration enabled and choose Save changes.

No assignable roles found on the server

The bot can only hand out roles below its own. In your Discord server's settings, move the bot's role above the roles it should offer.

A check fails with "Discord rejected the token"

The token was reset in the developer portal. Copy the new one into Bot token and choose Save changes.

The card shows Last error

The bot hit an error talking to Discord. Read the message, fix the cause, then select Run checks again on the Diagnostics card.

• Organization integrations
• Answer customer conversations
• Run a community with a server list, forum and guides
• Read the organization audit log

Every route needs an owner's or admin's access token, sent as Authorization: Bearer $CORITAN_TOKEN, and every change goes on the audit log.

PUT /discord takes application_id and public_key, which are required, and optionally bot_token, guild_id, staff_channel_id, staff_channel_kind (text or forum), is_enabled, ticket_channels_enabled, ticket_category_prefix, staff_role_id, max_ticket_channels (1–450), community_chat_enabled, community_invite_url and community_hidden_channels. A field you leave out keeps its value; send an empty string to clear an ID, or [] to clear the hidden channels.

curl -X PUT "https://api.coritan.com/api/v1/orgs/acme/discord" \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"application_id": "123456789012345678", "public_key": "'"$DISCORD_PUBLIC_KEY"'", "bot_token": "'"$DISCORD_BOT_TOKEN"'", "guild_id": "234567890123456789", "staff_channel_id": "345678901234567890"}'

A role menu takes title, and optionally description, channel_id (digits), menu_key, is_enabled and up to 25 options. Each option has role_id and label, and optionally emoji, description and key. Removing a role from a menu stops members taking it at once, even from a message already posted.

A staff link names the member behind a Discord account, as Link team members to their Discord accounts describes. PUT adds a link, or changes the member behind a Discord account that already has one.

curl -X PUT "https://api.coritan.com/api/v1/orgs/acme/discord/staff" \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"discord_user_id": "456789012345678901", "user_id": 1234}'

user_id must be the organization's owner or a member of its team, or the API answers 404 That user is not a member of this organization. A body without user_id answers 422. So does a body with admin_user_id: this route cannot link a Discord account to Coritan's own staff. The link takes the member's role in the organization.