# 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 |

```sh
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](/docs/chat/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:

1. A **name** (2 to 100 characters) and a **description** (1 to 400 characters).
2. A **server you own** to convert. Mirrors, student hubs and servers that already belong to an integration cannot be used.
3. A confirmation. Converting the server keeps one text channel (the system channel, or the first text channel) and renames it `internal`, creates `logging`, 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](/docs/chat/integrations) 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](/docs/chat/integrations)); the old key stops working at once.

Check that it works. With the secret key, address your own integration as `@me`:

```sh
curl -s "$API/integrations/@me" -H "Authorization: Bot $KEY"
```

```json
{
  "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 `@me` with 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 answers `403` Missing 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.

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

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

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

```sh
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](/docs/chat/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:

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

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

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

```sh
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](/docs/chat/transcripts).
