Talkers
A talker is one of your end users as it appears in a conversation; these routes admit talkers to conversations, remove them, and revoke their tokens.
What a talker is
- A talker is not an account. It cannot sign in, has no password, cannot be befriended or messaged directly, and never appears in the server's member list.
- A talker belongs to your integration and is identified by your own
external_id. Admitting the sameexternal_idagain, to the same or another conversation, reuses the same talker (the sameid) and overwrites itsusernamewith what you send.avatar_urlreplaces the avatar when sent; an admission without it keeps the avatar the talker already has. - On messages a talker looks like any author: its messages carry a Discord user object with its
id,username,global_name(the same asusername),discriminator"0"andavatar. - A talker can only act through a channel token, and a channel token names one talker in one conversation.
- A talker can read and send messages, edit and delete its own messages, and show typing. It cannot react, upload attachments or send embeds, and it has no management permissions.
Two kinds of talker
A talker is anyone your backend admits, your end users and your own staff alike; nobody on your side needs a Blisscord account. There are two scopes:
- A conversation talker is admitted to named conversations (when you open one, or with
POST .../channels/{channel_id}/talkers) and holds one channel token per conversation. Use this for end users. - A staff talker is admitted to every conversation of your integration, present and future, and holds one integration-wide token. One socket carries every conversation's events plus
CHANNEL_CREATEwhen a new one opens, and the same token sends into any of them. Use this for the people who answer conversations in your product. Create one withPOST /integrations/@me/talkers(below); it setsall_channels: true.
The talker object
| Field | Type | Description |
|---|---|---|
id | snowflake | The talker's id, which is also the author id on its messages. |
external_id | string | Your identifier for this end user. |
username | string | The display name. |
avatar | ?string | The avatar hash, served at https://cdn.discord.community/avatars/{id}/{avatar}.png, or null. |
user | user | The talker as a Discord user object, exactly as it appears on its messages. |
When a token is minted the object also carries token and expires_at.
Token lifetime
- A channel token expires after the integration's
token_ttl_seconds, 86400 seconds (24 hours) unless platform staff changed it for your integration. - Pass
expires_in(seconds) when admitting a talker to choose another lifetime for that token, from 60 seconds to 30 days (2592000 seconds). - A token cannot be renewed. To give an end user a fresh token, admit the same
external_idto the same channel again: you get a new token, and the old one keeps working until it expires or is revoked. - A token also stops working when the talker is removed from the conversation, when the talker is revoked, and when the conversation closes.
Admit a talker
POST /integrations/{id}/channels/{channel_id}/talkers
The body is one talker, with the same fields as an entry of talkers when opening a conversation: external_id, username, optional avatar_url and optional expires_in. Any validation failure answers 400 Invalid Form Body on external_id, with the message naming the field at fault (for example username must be between 1 and 80 characters).
Answers 201 Created with the talker object plus token, expires_at and channel_id.
curl -s -X POST https://discord.community/api/v9/integrations/@me/channels/1290000000000000001/talkers \
-H "Authorization: Bot $KEY" -H "Content-Type: application/json" \
-d '{"external_id": "customer-88213", "username": "Dana", "expires_in": 3600}'
{
"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.AAAAAGj0aHM.Zk9r...",
"expires_at": "2026-09-23T11:05:00.000000+00:00",
"channel_id": "1290000000000000001"
}
A channel_id that is not an open conversation of this integration answers 404, code 10003, Unknown Channel.
Create a staff talker
POST /integrations/@me/talkers with the same body as an admission (external_id, username, optional avatar_url, optional expires_in). The talker is created or refreshed with all_channels: true and the answer carries its integration-wide token: channel_id is null and the token works in every conversation channel of your server.
curl -s -X POST https://discord.community/api/v9/integrations/@me/talkers \
-H "Authorization: Bot $KEY" -H "Content-Type: application/json" \
-d '{"external_id":"agent-7","username":"Sam (Support)"}'
A staff talker never appears in a member list and cannot open or close conversations; those stay with your secret key.
Renew a token
Tokens expire (the default lifetime is per integration, 24 hours unless staff changed it). A conversation that lasts longer keeps going: mint a fresh token for an admission that already exists with POST /integrations/@me/talkers/{external_id}/token. Nothing about the talker changes, so its messages keep the same author.
curl -s -X POST https://discord.community/api/v9/integrations/@me/talkers/customer-88213/token \
-H "Authorization: Bot $KEY" -H "Content-Type: application/json" \
-d '{"channel_id":"1290000000000000001","expires_in":86400}'
channel_id names a conversation the talker is admitted to; leave it out for a staff talker to get a new integration-wide token. A talker admitted per conversation must name one (400, field channel_id). The answer is the talker object plus token, expires_at and channel_id.
GET /integrations/@me/talkers/{external_id} answers the talker object plus channel_ids, the conversations it is admitted to.
Remove a talker from a conversation
DELETE /integrations/{id}/channels/{channel_id}/talkers/{external_id}
Removes the talker's admission to this conversation. Every token for this talker in this channel stops working at once, and the talker's gateway sessions are disconnected. Tokens for the talker's other conversations keep working (they reconnect with them). Answers 204 No Content.
URL-encode external_id if it contains anything other than letters, digits, -, _, . and ~.
curl -s -X DELETE https://discord.community/api/v9/integrations/@me/channels/1290000000000000001/talkers/customer-88213 \
-H "Authorization: Bot $KEY"
An unknown external_id answers 404, code 10013, Unknown User.
Revoke every token of a talker
POST /integrations/{id}/talkers/{external_id}/revoke
Invalidates every channel token ever minted for this talker, in every conversation, and disconnects its gateway sessions. The talker stays admitted to its conversations; admit it again to mint new tokens. Use this when an end user logs out of your product or their session there is compromised. Answers 204 No Content.
curl -s -X POST https://discord.community/api/v9/integrations/@me/talkers/customer-88213/revoke \
-H "Authorization: Bot $KEY"
An unknown external_id answers 404, code 10013, Unknown User.