Create a chat session

curl --request POST \
  --url https://api.neoagent.io/public-api/chat/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": 123,
  "bot_id": "<string>",
  "client_id": "<string>",
  "inbound_tenant_id": "<string>",
  "managed_agent_key": "NEO_SUPPORT",
  "title": "<string>"
}
'

{
  "data": {
    "agent_id": 123,
    "archived_at": "2023-11-07T05:31:56Z",
    "channel": "<string>",
    "client_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "title": "<string>",
    "updated_at": "2023-11-07T05:31:56Z",
    "show_agent_progress_steps": true
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "timings_ms": {},
    "pagination": {
      "has_more": true,
      "next_cursor": "<string>"
    },
    "warnings": [
      "<string>"
    ]
  }
}

Chat

Create a chat session

Create a session against a CONVERSATIONAL agent. Returns the session resource; messages are appended via POST /chat/sessions/<id>/messages.

Select the agent with exactly one of agent_id (numeric) or managed_agent_key (a stable key for a Neo-managed agent, e.g. NEO_SUPPORT); the latter lets a caller target the agent without knowing its per-tenant id.

A platform service account may pass client_id to create the session for another tenant — used by the converged Neo Support relay to run each MSP technician’s turn as their own tenant. For a platform caller the agent is resolved from bot_id (the inbound Teams bot app id) + inbound_tenant_id (the message’s M365 tenant): a white-label bot with a channel installed for that tenant routes to the channel’s agent acting as the owning MSP (the acting tenant is then resolved server-side, overriding client_id, and returned on the resource); else the ACTIVE channel registered for that bot; else that tenant’s Neo Support agent. The caller is confined to those outcomes (never an arbitrary agent). Any non-platform caller passing client_id is rejected with 403.

A white-label session is always scoped to one end-company, resolved server-side from inbound_tenant_id. If that tenant isn’t linked to exactly one company in the owning MSP’s dashboard, the create is refused with 409 end_company_not_mapped; the error message is end-user-relayable and tells the MSP admin what to link.

POST

public-api

chat

sessions

Create a chat session

curl --request POST \
  --url https://api.neoagent.io/public-api/chat/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": 123,
  "bot_id": "<string>",
  "client_id": "<string>",
  "inbound_tenant_id": "<string>",
  "managed_agent_key": "NEO_SUPPORT",
  "title": "<string>"
}
'

{
  "data": {
    "agent_id": 123,
    "archived_at": "2023-11-07T05:31:56Z",
    "channel": "<string>",
    "client_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "title": "<string>",
    "updated_at": "2023-11-07T05:31:56Z",
    "show_agent_progress_steps": true
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "timings_ms": {},
    "pagination": {
      "has_more": true,
      "next_cursor": "<string>"
    },
    "warnings": [
      "<string>"
    ]
  }
}

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 Teams bot app id, forwarded by the platform relay so the backend routes the session to the ACTIVE channel registered for that bot — else the tenant's Neo Support agent. Honored only for a platform service account; ignored for other callers.

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.

inbound_tenant_id

string | null

The inbound message's M365 tenant id, forwarded by the platform relay. 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.

Show child attributes