Create a chat session

post/v2.1/chat/sessions
Requires any one of these rolesAbout roles
org.permission.conversation.create

The API key or user must hold at least one of them.

Create a linked chat session for a customer using an API token.

Identity is supplied in the JSON body (customerId, optional trackingId), not via a /c/ tracking JWT. Unlike POST /c/v2.1/chat/sessions, this route always creates a linked session (sobjects conversation).

If trackingId is omitted, the API may reuse the tracking id from the customer's latest prior chat session that had one. If none is found, the session is still created and trackingId may be unset.

Assistant bootstrap

When the request includes assistant, Kustomer also bootstraps the assistant dialog during this create call:

  1. Resolves the assistant's opening dialog/node and greeting / opening messages (same logic as customer assistant/init).
  2. Persists those outbound greeting messages on the session.
  3. Creates assistant run state on that dialog/node with progress.status: ready so a later customer reply (for example via Chat SDK /c/v2/chat/assistant/messages) can continue the tree without a separate mock inbound kickoff.
  4. May publish the greeting messages on the session's PubNub conversation channel immediately after create.

The 201 session payload may reflect updated preview / lastMessageAt after greetings are persisted. Bootstrap failures are soft-failed: they are logged and do not change the success response (session create still returns 201). Duplicate assistant state (HTTP 409 from Kustomer) is treated as idempotent success.

About this resource

Chat conversations

The server-side chat API lets your backend take part in Kustomer chat with a regular API key. It can open chat sessions for a customer, post messages as the customer, an agent or an assistant, show typing, import bot conversations and record satisfaction ratings.

A chat session is a Kustomer conversation on the chat channel, seen from the chat side. Its ID is the conversation ID, so the same conversation appears in the agent desktop and in the customer's chat widget or app, and you can read it with the conversations API too. Sessions are usually created by the chat SDKs when a customer starts a chat. These v2.1 endpoints do the same jobs from your server, for custom chat front ends, messaging bridges and bots that answer before a human does. Anything you post is delivered in realtime to the customer's open chat on every device.

A session stays active until the chat is ended or deleted. Listing with active=true returns only active sessions that have at least one message.

Identity: customerId and trackingId

These endpoints never use a chat key or a customer's chat login token. Every request names the customer in customerId, and Kustomer checks it against the session: a mismatch fails with 403. trackingId is the chat SDK's ID for a visitor's browser or device. It's optional, but when a session has one, any trackingId you send must match. Creating a session without one reuses the tracking ID from the customer's latest chat session, if there is one; handoff imports never set one.

Use a server-side API key with the roles each endpoint lists, never a chat key, which must hold only org.tracking.

Who a message is from

Endpoint Appears as
POST /v2.1/chat/messages The customer (direction: in). Returns 202 Accepted; the message is processed asynchronously.
POST /v2.1/chat/assistant/messages The customer, replying inside an assistant (bot) flow, so the assistant continues from where it is.
POST /v2.1/chat/outbound/messages An agent: from is the Kustomer user ID. Add auto: true for bot or AI replies so they don't count as a human first response.
POST /v2.1/chat/outbound/assistant/messages An assistant line, attributed to from. Send exactly one of body, meta.template or attachments.

Message bodies are up to 10,240 characters. Typing indicators are ephemeral and never stored. Your service owns their lifecycle: sending a message doesn't hide one, so send typing: false when you're done, and resend typing: true about every three seconds for long answers.

Which endpoint to use

To Call
Open a chat for a customer, optionally starting an assistant POST /v2.1/chat/sessions
Import a conversation your own bot already had POST /v2.1/chat/handoff
List a customer's or visitor's chats GET /v2.1/chat/sessions
Read a chat's messages GET /v2.1/chat/sessions/{id}/messages
Post as the customer POST /v2.1/chat/messages or, in an assistant flow, POST /v2.1/chat/assistant/messages
Post as an agent or bot POST /v2.1/chat/outbound/messages
Post as an assistant POST /v2.1/chat/outbound/assistant/messages
Show or hide typing POST /v2.1/chat/outbound/typing
Record a CSAT rating or comment PUT /v2.1/chat/satisfaction-responses/{id}

A handoff takes 2 to 100 messages, including at least one inbound and one outbound, and sorts them by date; active: false creates the conversation already closed. When you pass assistant on session create, Kustomer posts the assistant's greeting, and if that fails the session is still created. Session lists are paginated, newest first by lastMessageAt, and don't include messages. The CSAT response must already exist, created by Kustomer for the chat's survey; this call fills it in, and sending answers marks it commented rather than rated.

RelatedServer-side chat APIHow chat worksCustomer identityConversations

Request body

application/jsonrequired
customerIdstringrequired

Required. Kustomer customer ID for the new session.

trackingIdstring

Optional tracking record id stored on the session.

titlestring

Session title.

max length 256
isInAssistantModeboolean

Start in assistant/bot mode when true.

brandstring

Chat settings / widget brand id.

assistantstring

Assistant public id. When set on this linked create path, Kustomer bootstraps greeting / opening messages and assistant run state during the create call (see operation description). Soft-fails on bootstrap errors; session create still returns 201.

customobject

Custom attributes. Keys must use Kustomer custom-attribute suffix rules (for example orderNumStr, priorityStr, chatSourceTree).

externalIdstring
max length 256
importedAtstring<date-time>
createdAtstring<date-time>
assignedUsersarray<ObjectId>
min items 1 · max items 10 · unique items
assignedTeamsarray<ObjectId>
min items 1 · max items 10 · unique items
tagsarray<string>
min items 1 · max items 20 · unique items

Responses

Created. When assistant was provided, greeting messages and assistant run state may already have been bootstrapped; soft-fail bootstrap errors still yield this status.

object