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 for the talker object). Tokens are never listed.

curl -s https://discord.community/api/v9/integrations/@me/channels -H "Authorization: Bot $KEY"
[
  {
    "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

FieldTypeRule
namestringRequired, 1 to 100 characters after trimming. Error: Must be between 1 and 100 characters.
topicstringRequired, the description of the conversation, up to 1024 characters. Errors: A description of the conversation is required, Must be 1024 or fewer in length.
talkersarray, optionalUp to 25 talkers to admit at once. Error on talkers: At most 25 talkers per request.

Each entry of talkers:

FieldTypeRule
external_idstringRequired, 1 to 191 characters. Your own stable identifier for this end user. The same external_id always names the same talker in your integration.
usernamestringRequired, 1 to 80 characters. The display name shown on messages.
avatar_urlstring, optionalAn 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_ininteger, optionalSeconds 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:

FieldTypeDescription
tokenstringThe channel token for this talker in this channel. Shown only here.
expires_atISO 8601 timestampWhen the token stops working.
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 }
    ]
  }'
{
  "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), with closed_via set to api.

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.

RouteNotes
POST /guilds/{guild_id}/channelsOpens 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}/messagesReads history, with before, after, around and limit (1 to 100, default 50).
POST /channels/{channel_id}/messagesPosts 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.

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."}'