Runtime Sessions, Chat IDs, and Recovery

Create one subject-bound runtime session for a conversation or purchase journey. Keep its session_id and resume_token in protected BFF or server state. session_id identifies the record; the signed resume_token proves authorization to resume it. Browser-readable storage, URLs, analytics, and logs must not contain the token.

Create a Session

POST /api/v1/runtime/sessions
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "agent_id": "{{agent_id}}",
  "subject_type": "external",
  "subject_id": "customer-reference-42",
  "channel": "web",
  "chat_id": "chat-10001",
  "ttl_seconds": 86400,
  "metadata": {"locale": "en-US"}
}

Omitting ttl_seconds gives the 24-hour default; positive values are capped at 30 days. Explicit 0 creates a non-expiring session only for a service identity with runtime:session_non_expiring. Its expires_at is null; completion, cancellation, or revocation can still end it. Prefer a bounded TTL and secure refresh for normal journeys. An external or user subject needs a stable subject_id; ACP stores a realm-scoped hash rather than the raw value. The BFF owns Agent, subject, and Flow selection.

The response returns session_id, resume_token, expires_at, effective status, and the current chat_id when supplied. Send the matching token on subsequent chat, structured execution, and lifecycle calls.

Refresh Before Expiry

POST /api/v1/runtime/sessions/{{session_id}}/resume-token/refresh
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "resume_token": "{{resume_token}}",
  "ttl_seconds": 86400,
  "chat_id": "chat-10002",
  "metadata": {"locale": "en-US"}
}

Refresh requires the current valid token. ACP rotates it, increments its version, and immediately invalidates the previous token; replace the BFF copy atomically. The session ID, transcript, state, and pinned Flow remain. Omitted chat_id or metadata preserves the previous value. An empty chat_id clears only the current label; a supplied metadata object replaces the prior metadata. Refresh does not shorten a later existing expiry.

Recover With a Service Identity

POST /api/v1/runtime/sessions/{{session_id}}/resume-token/recover
Authorization: Bearer {{service_access_token}}
Content-Type: application/json

{"ttl_seconds": 86400, "chat_id": "chat-10002"}

The service identity needs runtime:session_recover. Recovery does not send the old token and can rotate an active session or reactivate an expired one while preserving the session ID, transcript, state, and Flow pin. It cannot recover a completed or cancelled session. Keep the service credential on the server; never expose recovery to a client solely because it knows a session ID.

Read Status and Chat History

GET /api/v1/runtime/sessions/{session_id}/status returns the effective active, expired, completed, or cancelled state for a realm-scoped session without a resume token. Unknown IDs return 404 SESSION_NOT_FOUND; malformed IDs return 400 INVALID_SESSION_ID. Status is a read, not a recovery operation.

The session read returns the current chat_id and historical chat_ids. Changing the current label preserves old chat associations, messages, executions, and captured log IDs. One session can have multiple chat labels over time; a label can be reused across sessions. A chat ID is correlation metadata, not an authorization credential. Use the session/messages and execution endpoints to read the authorized history.

End or Reset a Journey

Endpoint	Effect
POST /api/v1/runtime/sessions/{session_id}/complete	Mark a successful journey terminal.
POST /api/v1/runtime/sessions/{session_id}/cancel	Mark an abandoned journey terminal.
POST /api/v1/runtime/sessions/{session_id}/reset	Clear the pinned Flow in an active session for a new routing decision.

These operations use { "resume_token": "{{resume_token}}" }. Create a new session after completion or cancellation. Handle 409 SESSION_COMPLETED, 410 SESSION_EXPIRED, and 422 SESSION_CANCELLED distinctly. A runtime 502 can contain a normalized ERROR action; show only its safe userMessage and use errorCode and retryable for controlled handling.

See Automatic Flow Routing, API Reference, and Security and Data Handling.