Getting started
This page walks through the whole life of a conversation with curl: create the integration, keep the key, open a conversation, hand a talker token to your front end, exchange messages, close the conversation and read its transcript.
The examples use these placeholder values. Replace them with your own.
| Placeholder | Meaning |
|---|---|
$KEY | Your secret key (the integration's bot token) |
1287654321098765432 | The integration id (also its application id) |
1287654321098765500 | The reserved server (guild) id |
1290000000000000001 | A conversation channel id |
$TALKER_TOKEN | A channel token minted for one talker |
1290000000000000999 | A transcript id |
export API=https://discord.community/api/v9
export KEY='your-secret-key'
Your own staff do not need Blisscord accounts either: give each of them a staff talker (POST /integrations/@me/talkers), whose one token reaches every conversation. Tokens expire; renew any of them with POST /integrations/@me/talkers/{external_id}/token. Both are described under Talkers.
1. Create the integration
Integrations are created in the developer portal at https://developers.discord.community/integrations. Your account needs chat integration access, which platform staff grant; without it the portal says you do not have access.
The portal asks for:
- A name (2 to 100 characters) and a description (1 to 400 characters).
- A server you own to convert. Mirrors, student hubs and servers that already belong to an integration cannot be used.
- A confirmation. Converting the server keeps one text channel (the system channel, or the first text channel) and renames it
internal, createslogging, and deletes every other channel. The messages of each deleted channel are saved as a transcript first. This cannot be undone, so use a new, empty server if you can.
The portal calls POST /integrations with your signed-in session and the body {"name", "description", "guild_id"}. The answer is the integration object plus one extra field, token: your secret key.
2. Keep the key
The secret key is shown once. Store it in your backend's secret store. It is a bot token, sent as Authorization: Bot <key>, and it is never rate limited. If you lose it, reset it (see Integrations); the old key stops working at once.
Check that it works. With the secret key, address your own integration as @me:
curl -s "$API/integrations/@me" -H "Authorization: Bot $KEY"
{
"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": 0,
"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"
}
Use
@mewith the secret key on every/integrations/{id}route. The numeric id is for the portal, where you are signed in as the integration's owner; with the secret key it answers403Missing Access.
3. Open a conversation
Create a channel with a name, a required topic (the description of the conversation, shown to your staff), and the talkers to admit. Each talker gets a channel token in the answer.
curl -s -X POST "$API/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", "avatar_url": "https://acme.example/avatars/88213.png" }
]
}'
{
"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": "5b1c0e8f2a9d4c3e7f6a1b2c3d4e5f60",
"user": { "id": "1290000000000000050", "username": "Dana", "global_name": "Dana", "discriminator": "0", "avatar": "5b1c0e8f2a9d4c3e7f6a1b2c3d4e5f60", "bot": false },
"token": "MTI5MDAwMDAwMDAwMDAwMDA1MDoxMjkwMDAwMDAwMDAwMDAwMDAx.AAAAAGj0Wlo.q3Jd...",
"expires_at": "2026-09-24T10:05:00.000000+00:00"
}
]
}
The channel object is abbreviated here; it is the full Discord channel object. Your staff now see #order-4471 in the reserved server.
4. Hand the token to your front end
Send talkers[0].token to Dana's browser or app, for example in the response of your own "start chat" endpoint. Never send the secret key. The token works only in channel 1290000000000000001, only as Dana, until expires_at (24 hours by default).
5. Send and receive messages
From the front end, with the channel token:
curl -s -X POST "$API/channels/1290000000000000001/messages" \
-H "Authorization: Bearer $TALKER_TOKEN" -H "Content-Type: application/json" \
-d '{"content": "Hi, my order 4471 has not arrived yet."}'
Read the history:
curl -s "$API/channels/1290000000000000001/messages?limit=50" \
-H "Authorization: Bearer $TALKER_TOKEN"
For live updates the front end connects to the gateway with the same token and receives MESSAGE_CREATE for every new message in the channel. See Channel tokens for the full list of calls and a WebSocket example.
Your backend can post into the conversation too, with the secret key, using the ordinary Discord route:
curl -s -X POST "$API/channels/1290000000000000001/messages" \
-H "Authorization: Bot $KEY" -H "Content-Type: application/json" \
-d '{"content": "Thanks Dana, a support agent will be with you shortly."}'
Your staff answer from the Blisscord client, and their messages reach Dana the same way.
6. Close the conversation
curl -s -X DELETE "$API/integrations/@me/channels/1290000000000000001" \
-H "Authorization: Bot $KEY"
The channel is transcribed, deleted, and logged in logging. Dana's session receives CHANNEL_DELETE and her token stops working. The answer is the transcript:
{
"id": "1290000000000000999",
"channel_id": "1290000000000000001",
"channel_name": "order-4471",
"topic": "Customer asks where order 4471 is. Priority: normal.",
"opened_at": "2026-09-23T10:05:00.000000+00:00",
"closed_at": "2026-09-23T10:31:12.000000+00:00",
"closed_by": "1287654321098765433",
"closed_via": "api",
"message_count": 7,
"participants": [
{ "id": "1290000000000000050", "username": "Dana", "avatar": "5b1c0e8f2a9d4c3e7f6a1b2c3d4e5f60", "kind": "talker" },
{ "id": "1287654321098765433", "username": "Acme Support", "avatar": null, "kind": "bot" },
{ "id": "1100000000000000007", "username": "sam", "avatar": null, "kind": "user" }
],
"log_message_id": "1290000000000001000",
"url": "https://discord.community/integrations/transcripts/1290000000000000999?sig=Qm9ndXNTaWduYXR1cmU"
}
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.
7. Read the transcript
curl -s "$API/integrations/@me/transcripts/1290000000000000999" \
-H "Authorization: Bot $KEY"
This answers the same object with a messages array. List every transcript, newest first, with GET /integrations/@me/transcripts. See Transcripts.