Skip to main content
POST
Create a chat session

Authorizations

Authorization
string
header
required

Authorization: Bearer <token> where <token> is either a neo_sk_<env>_<secret> API key (service account) or a Microsoft Entra ID access token (dashboard user).

Body

application/json
agent_id
integer | null

Numeric id of the CONVERSATIONAL agent to run the session against. Provide exactly one of agent_id or managed_agent_key.

bot_id
string | null

Inbound bot app id, forwarded by the platform relay: the Teams bot app id for channel=TEAMS, the Slack app id for channel=SLACK. The backend routes the session to the ACTIVE channel registered for that bot — else, on Teams only, the tenant's Neo Support agent. Honored only for a platform service account; ignored for other callers.

channel
enum<string>
default:TEAMS

The messaging surface the session runs on: TEAMS (the default) or SLACK. For a platform caller with SLACK, bot_id carries the Slack app id and inbound_tenant_id the Slack workspace (team) id, and both are required: the session routes to the channel whose Slack app was installed in that workspace, or, for the shared Neo AI Agent Slack app, to the Neo Support agent of the tenant that connected that workspace. Honored only for a platform service account; every other caller's session is TEAMS (a dashboard caller's is always a dashboard session).

Available options:
TEAMS,
SLACK
client_id
string | null

Target tenant to create the session for. Honored only for a platform service account; the agent is resolved from bot_id (a matching channel, else that tenant's Neo Support agent). Any other caller passing it gets 403. Omit to use the caller's own tenant.

conversation_scope
enum<string> | null

The kind of conversation the relay forwards from: PERSONAL for a 1:1 chat with one person, SHARED for a group chat or a channel. A technician's Live chat takeover carries over into a new session only between PERSONAL sessions. Honored only for a platform service account.

Available options:
PERSONAL,
SHARED
end_user_email
string | null

The speaker's verified email, forwarded by the platform relay at session create. Used only for white-label END_USER dispatch: when the inbound Microsoft 365 tenant is linked to several companies (branch offices), the session is scoped to the company whose PSA contacts hold this email. Honored only for a platform service account.

inbound_tenant_id
string | null

The inbound message's tenant, forwarded by the platform relay: the Microsoft 365 tenant id for channel=TEAMS, the Slack workspace (team) id for channel=SLACK. With bot_id, lets the backend route a white-label turn via the channel installed for that tenant — the acting tenant is then resolved server-side from the channel's owning MSP, overriding client_id. Honored only for a platform service account.

managed_agent_key
enum<string> | null

Target a Neo-managed agent by its stable key instead of a numeric id — the backend resolves the target tenant's row. Lets the converged Neo Support relay stay agent-id-agnostic across tenants. Provide exactly one of agent_id or managed_agent_key.

Available options:
NEO_SUPPORT
title
string | null

Response

Success.

data
ChatSessionResource · object
required

Public surface of a chat session row. Renamed agent_id for partner clarity.

meta
object
required