Chat API & Session Management

Overview

Sulus's Chat API lets you send text messages to an assistant and get a response back, outside of a live voice call. This page covers the basic chat request, the two ways to maintain conversation context across multiple requests, how variables behave inside a session, and the OpenAI-compatible endpoint for teams that already have that SDK pattern in place.

Send a POST request to the chat endpoint with your assistantId and the caller's message as input:

curl -X POST https://api.sulus.ai/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "your-assistant-id",
    "input": "Hello, my name is Sarah"
  }'

The response includes an id for the chat and an output field containing the assistant's reply:

{
  "id": "chat_abc123",
  "output": [
    {
      "role": "assistant",
      "content": "Hi Sarah, how can I help you today?"
    }
  ]
}

Sulus offers two mutually exclusive methods for maintaining conversation context across chat requests — they cannot be used together in the same request.

previousChatId (simple conversation chaining)

Pass the id from the previous chat response as previousChatId in the next request:

curl -X POST https://api.sulus.ai/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "your-assistant-id",
    "previousChatId": "chat_abc123",
    "input": "What was my name again?"
  }'

sessionId (complex or long-running workflows)

Create a session first, then reference the returned session.id as sessionId in every subsequent chat request for that conversation:

curl -X POST https://api.sulus.ai/session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assistantId": "your-assistant-id"}'

curl -X POST https://api.sulus.ai/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session_xyz789",
    "input": "Hello, I need help with billing"
  }'

A session is tied to one assistant — you can't pass assistantId alongside sessionId. Sessions expire after 24 hours by default; after that, you'll need to create a new session.

When you create a session with assistantOverrides.variableValues, template placeholders like {{name}} are substituted at session creation time and baked into the stored assistant configuration for that session. The placeholders no longer exist afterward, and the substituted values persist across every chat within that session.

curl -X POST https://api.sulus.ai/session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "your-assistant-id",
    "assistantOverrides": {
      "variableValues": {
        "name": "John",
        "company": "Acme Corp"
      }
    }
  }'

Because the placeholders are already gone, passing new variableValues in a later chat request within the same session has no effect — there are no {{ }} placeholders left for the new values to fill. To apply different values partway through a session, you must supply a fresh template containing new {{ }} placeholders alongside the new variableValues in that request's assistantOverrides.

If your team already has tooling built around the OpenAI SDK pattern, Sulus offers a compatible endpoint that follows OpenAI's Responses API format:

POST https://api.sulus.ai/chat/responses

Use it as a drop-in replacement by pointing the OpenAI SDK at Sulus's base URL:

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'YOUR_SULUS_API_KEY',
  baseURL: 'https://api.sulus.ai/chat',
});

const response = await openai.responses.create({
  model: 'gpt-4o',
  input: 'What is the capital of France?',
  stream: false,
  assistantId: 'your-assistant-id'
});

console.log(response.output[0].content[0].text);

Note that you call openai.responses.create (not openai.chat.completions.create), and access the reply via response.output[0].content[0].text. The endpoint supports streaming (set stream: true to receive Server-Sent Events) and conversation context via previousChatId, the same as the native chat endpoint.