Skip to main content
POST
Create a chat session in a channel
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

POST /api/v2/chat/createSession starts a session in a factory, project or team channel your key or External App holds chat:manage for at the channel’s home org unit, and answers 201 with { "id": "<sessionId>" }. channelId and title are required. linkedEntityType and linkedEntityId are refused with 400 bad_request. A channel you may not use is 404 resource_missing; an archived channel is 409 invalid_state. Send an Idempotency-Key header to make a retry safe. A repeat with the same key and body within 24 hours never creates a second session: it returns the stored 201 with Idempotency-Replayed: true while you still hold chat:manage and chat:read and may read the created session, and otherwise 403 for a missing permission or 409 idempotency_result_unavailable. See Chat write replay.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Path Parameters

channelId
string
required
Minimum string length: 1

Body

application/json
title
string
required
Minimum string length: 1
description
string
purpose
string
autoArchiveAfterMinutes
number
relevancyScoringModeOverride
string
restrictedParticipants
string[]

Response

Session created

data
object
required

The created session's ID.

meta
object
required