# 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 same `external_id` again, to the same or another conversation, reuses the same talker (the same `id`) and overwrites its `username` with what you send. `avatar_url` replaces 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 as `username`), `discriminator` `"0"` and `avatar`.
- A talker can only act through a [channel token](/docs/chat/channel-tokens), 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_CREATE` when 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 with `POST /integrations/@me/talkers` (below); it sets `all_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_id` to 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](/docs/chat/conversations): `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`.

```sh
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}'
```

```json
{
  "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.

```bash
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.

```bash
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 `~`.

```sh
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`.

```sh
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`.
