Chat Runtime

Vonative chat sessions use a two-layer architecture:

the Vonative API is the control plane
https://chat.vonative.com is the runtime plane

The API remains the source of truth for authentication, organization scoping, session creation, resume, and billing metadata. The Worker at chat.vonative.com handles the live chat transport and streaming.

Connection model

Clients should not create chat runtime sessions directly from raw assistant or organization identifiers. Always bootstrap through the Vonative API first.

Frontend flow

Start or resume a chat session through the Vonative API.
Receive runtime connection details from the API.
Send messages and receive live responses from chat.vonative.com.

For assistant chat:

POST /v1/assistants/{assistant_uuid}/initiate-call

Request body:

{
  "mode": "chat"
}

For workflow chat:

POST /v1/workflows/{workflow_uuid}/initiate-call

Request body:

{
  "conversation_mode": "chat",
  "workflow_mode": "draft"
}

Expected bootstrap response shape:

{
  "success": true,
  "data": {
    "session_id": "c25ebdbd-2a92-4e6c-88c9-f8532184549b",
    "root_session_id": "c25ebdbd-2a92-4e6c-88c9-f8532184549b",
    "conversation_mode": "chat",
    "chat_runtime_url": "https://chat.vonative.com",
    "runtime_token": "rt_...",
    "messages": []
  }
}

Runtime authentication

Use a short-lived runtime token issued by the Vonative API. Do not expose internal bridge secrets to browsers, mobile apps, or third-party developers. The runtime token should represent:

organization
assistant or workflow
session
root session
conversation mode
expiry time
optional channel metadata

Web client messaging

After bootstrap, the frontend connects directly to chat.vonative.com. Recommended runtime routes:

POST https://chat.vonative.com/v1/chat/sessions/{session_id}/messages
POST https://chat.vonative.com/v1/chat/sessions/{session_id}/messages/stream
POST https://chat.vonative.com/v1/chat/sessions/{session_id}/attachments
GET  https://chat.vonative.com/v1/chat/sessions/{session_id}/messages

Headers:

Authorization: Bearer rt_...
Content-Type: application/json

Example non-streaming request:

{
  "message": "I want to reschedule my appointment"
}

Attachment-aware request:

{
  "message": "Please review this file",
  "attachment_ids": ["att_123", "att_456"]
}

Example response:

{
  "ok": true,
  "reply_text": "Sure. What date would you like instead?",
  "messages": [
    {
      "role": "user",
      "content": "I want to reschedule my appointment"
    },
    {
      "role": "assistant",
      "content": "Sure. What date would you like instead?"
    }
  ]
}

File uploads

Web chat supports session-scoped attachments through chat.vonative.com. Upload first:

POST https://chat.vonative.com/v1/chat/sessions/{session_id}/attachments
Authorization: Bearer rt_...
Content-Type: multipart/form-data

Form fields:

file: the uploaded file

Response:

{
  "ok": true,
  "attachment": {
    "id": "att_123",
    "name": "account-summary.png",
    "mime_type": "image/png",
    "size_bytes": 182344,
    "kind": "image"
  }
}

Then include attachment_ids when sending the message. Supported web-chat uploads in the current runtime:

images:
- image/png
- image/jpeg
- image/webp
- image/gif
text-like files:
- text/plain
- text/markdown
- text/csv
- text/html
- application/json
- application/xml
- text/xml
document files converted to text in the Worker:
- application/pdf
- application/vnd.openxmlformats-officedocument.wordprocessingml.document

Current limits:

images up to 5 MB
text-like files up to 1 MB
PDF and DOCX files up to 10 MB

Current behavior:

image uploads are passed to the model as image input on the next user turn
text-like uploads are inlined as text context on the next user turn
PDF and DOCX uploads are converted to markdown/text in the Worker and inlined on the next user turn
attachment metadata is visible in the chat thread for the active session and preserved across resumed chat history

Not yet supported in the current web-chat runtime:

XLSX/PPTX parsing
arbitrary binary file understanding

Example browser upload:

const form = new FormData();
form.append("file", file);

const uploadResponse = await fetch(
  `${chatRuntimeUrl}/v1/chat/sessions/${sessionId}/attachments`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${runtimeToken}`,
    },
    body: form,
  }
);

const { attachment } = await uploadResponse.json();

Streaming responses

For live token-by-token rendering, use the stream endpoint.

POST https://chat.vonative.com/v1/chat/sessions/{session_id}/messages/stream

Recommended event types:

message_start
token
tool_call
tool_result
message_end
done
error

Example browser request:

const response = await fetch(
  `${chatRuntimeUrl}/v1/chat/sessions/${sessionId}/messages/stream`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${runtimeToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: "I want to reschedule my appointment",
      attachment_ids: ["att_123"],
    }),
  }
);

Your UI should render:

streamed assistant tokens
tool execution updates when available
final message text
final usage and cost metadata if returned

Resuming a chat session

Resume should start from the Vonative API, not from the Worker directly.

POST /v1/sessions/{session_uuid}/resume

Request body:

{
  "conversation_mode": "chat"
}

Expected response:

{
  "success": true,
  "data": {
    "session_id": "new-child-session-uuid",
    "root_session_id": "original-root-session-uuid",
    "resumed_from_session_id": "previous-session-uuid",
    "conversation_mode": "chat",
    "chat_runtime_url": "https://chat.vonative.com",
    "runtime_token": "rt_...",
    "messages": [
      {
        "role": "user",
        "content": "I want to reschedule my appointment"
      },
      {
        "role": "assistant",
        "content": "Sure. What date would you like instead?"
      }
    ]
  }
}

The frontend should render the returned history immediately, then continue the session using the new child session_id.

Public developer integrations

For external developers, use the same pattern:

create or resume a session through the Vonative API
receive runtime_token and chat_runtime_url
connect directly to chat.vonative.com for live messaging

This keeps:

organization validation in the API
session lifecycle in the API
billing settlement in the API
live runtime transport in the Worker

Security model

Use two authentication layers:

Layer	Used by	Purpose
API bearer token	Frontend server, backend integrations, developers	Create or resume sessions through the Vonative API
Runtime token	Browser, mobile app, SDK client	Send and stream messages through `chat.vonative.com`

BRIDGE_SECRET is internal only and should be used only for trusted service-to-service communication.

CORS and browser support

chat.vonative.com should allow:

your Vonative dashboard origin
approved customer origins for embedded chat
Authorization and Content-Type headers
multipart/form-data uploads for attachments
long-lived streaming responses for SSE or equivalent streaming transport

Recommended division of responsibilities

Responsibility	Vonative API	chat.vonative.com
Auth and org scoping	Yes	No
Session creation	Yes	No
Session resume	Yes	No
Live message transport	No	Yes
Streaming token output	No	Yes
Compliance-aware logging	Yes	Worker sends events; API persists
Billing settlement	Yes	Worker sends usage data

Notes

Chat-only mode is text-only. It does not publish mic audio or play TTS output.
Chat runtime should be treated as the live execution surface, not the control plane.
Resume creates a new live runtime connection while preserving a stable root conversation thread.

Getting Started

Assistants

WebRTC & Realtime

Workflows

Phone Numbers

Tools

Developer

Billing

Monitoring

Chat Runtime

Chat Runtime

Connection model

Frontend flow

Runtime authentication

Web client messaging

File uploads

Streaming responses

Resuming a chat session

Public developer integrations

Security model

CORS and browser support

Recommended division of responsibilities

Notes

​Chat Runtime

​Connection model

​Frontend flow

​Runtime authentication

​Web client messaging

​File uploads

​Streaming responses

​Resuming a chat session

​Public developer integrations

​Security model

​CORS and browser support

​Recommended division of responsibilities

​Notes

Chat Runtime

Connection model

Frontend flow

Runtime authentication

Web client messaging

File uploads

Streaming responses

Resuming a chat session

Public developer integrations

Security model

CORS and browser support

Recommended division of responsibilities

Notes