Stream a chat answer

POST /api/chat/send accepts one student message and responds with text/event-stream. OpenAPI cannot describe the event framing, so this page is the contract.

Request

POST /api/chat/send
Authorization: Bearer <token>
Content-Type: application/json

Field	Type	Rule
`message`	string	Optional. Defaults to `""`. Maximum 8000 characters.
`mediaIds`	array	Optional. Up to 10 media ids from `POST /api/media`.
`replyToId`	uuid	Optional. The message this one answers.
`image.data`	string	Base64 of the image bytes. No `data:` prefix.
`image.mimeType`	string	For example `image/jpeg`.

Send message, mediaIds, image, or a combination. A request with none of them returns 400 with {"error":"empty message"}. The 400 arrives before the stream, as normal JSON.

{
  "message": "Bu soruyu çözemedim",
  "mediaIds": ["4b1e...c9"],
  "replyToId": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d"
}

Attachments go through POST /api/media first. Read Media. The image field still works and puts the bytes inline as base64, but it costs about 33 percent more bytes and holds the request open while the server stores them.

Lala answers in one message or several

Lala writes the way a person texts. Most turns are one message. Some are two or three short ones. Each message becomes its own row with its own id, and the stream announces each one. The index field is the position of the message in the turn. It starts at 0 for every turn.

Response events

The response status is 200 and the content type is text/event-stream. Each event has a name and a JSON data payload.

ChatMessageStartEvent

Lala started a new message. Open a new bubble.

event: message_start
data: {"index":0}

ChatChunkEvent

One text delta of the message at index. Repeats many times.

event: chunk
data: {"text":"hadi be ya","index":0}

ChatMessageEndEvent

The message at index is complete. It has no id yet.

event: message_end
data: {"index":0,"text":"hadi be ya"}

ChatRestartEvent

Rare. The turn starts again. Discard every message from this turn. The next index is 0.

event: restart
data: {"reason":"tool schema retry"}

ChatToolEvent

Lala started or finished a tool. Cosmetic. Use it to say what the wait is for.

event: tool
data: {"name":"plan_study","phase":"start"}

ChatSyncEvent

A tool wrote data that the application shows. Reload those screens.

event: sync
data: {"resources":["plan"]}

ChatDoneEvent

Terminal. Holds the persisted messages, with their ids, the reactions, and every resource that the turn wrote.

event: done
data: {"text":"hadi be ya\n\nkaç net oldu peki","messages":[{"id":"...","role":"lala","turnIndex":0,"content":"hadi be ya", ...}],"reactions":[{"emoji":"🔥"}],"changed":["plan"]}

ChatErrorEvent

Terminal. The turn failed.

event: error
data: {"error":"chat failed"}

The stream emits exactly one terminal event: done or error. A model failure is an error event, not an HTTP status. The HTTP status stays 200 in both cases.

Rules for the client

On message_start, open a new bubble for that index.
Append each chunk payload to the bubble named by its index.
On message_end, mark that bubble complete.
On restart, delete every bubble of this turn and wait for the next message_start.
On done, replace your bubbles with the messages array. Each entry carries the real id.
On done, show the emoji in reactions. The array is usually empty. Lala reacts rarely.
On error, show a retry control. Do not show the partial text as a finished answer.
If the socket closes with no terminal event, treat the turn as failed.
On sync, reload the named screens. Do not wait for done.
On tool, restart, done, or error, update the activity indicator. A start with no end follows a failed turn, so a terminal event must clear the indicator.

Tools change data while Lala writes

A turn can write to the planner, the deneme history, and the student profile. Lala does this with tools, in the middle of the answer. The sync event names the data that changed:

Resource	Screen	Read it again with
`plan`	The study planner	`GET /api/plan`
`journey`	The deneme history and the subject statistics	`GET /api/journey` and `GET /api/denemeler`
`profile`	The student record	`GET /api/me`

Each resource fires one sync event per turn, at the moment of the write. The write is complete when the event arrives, so a read after it returns the new data. The changed array on done repeats the full set. A client that missed an event still reloads the correct screens. The tool event carries the name of the tool. The application maps the name to its own copy, for example plan_study to “programa yazıyor”. A turn can call several tools, one after the other.

The server persists the student message before the model runs. It persists the answer after the model runs. A turn that fails mid-stream can leave the student message in the history with no answer. Read GET /api/chat/messages to resynchronize after an error.

Reactions

Lala’s reaction lands on the student message it answers, with actor set to lala. The student reacts through POST /api/chat/messages/{id}/reactions.

curl -X POST "$BASE_URL/api/chat/messages/$MESSAGE_ID/reactions" \
  -H "Authorization: Bearer $LALA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"emoji":"🔥"}'

To remove one, call DELETE /api/chat/messages/{id}/reactions/{emoji} with the emoji percent-encoded. Both calls return the whole message with its current reactions. Both are idempotent.

No resume

You cannot reconnect to a running turn. If the application goes to the background and the connection drops, the server still completes the turn and writes the messages. The messages then arrive on the realtime stream. Read Realtime updates.

Timing

The server aborts the model call after 60 seconds. One turn can take several model steps, because Lala can call tools. Allow at least 90 seconds of client timeout on this request. Do not set an idle timeout below the gap between two chunks.

Client code

final request = http.Request('POST', Uri.parse('$baseUrl/api/chat/send'))
  ..headers['Authorization'] = 'Bearer $token'
  ..headers['Content-Type'] = 'application/json'
  ..body = jsonEncode({'message': text});

final response = await http.Client().send(request);

String? eventName;
await for (final line in response.stream
    .transform(utf8.decoder)
    .transform(const LineSplitter())) {
  if (line.startsWith('event: ')) {
    eventName = line.substring(7).trim();
  } else if (line.startsWith('data: ')) {
    final payload = jsonDecode(line.substring(6));
    switch (eventName) {
      case 'message_start':
        openBubble(payload['index'] as int);
      case 'chunk':
        appendTo(payload['index'] as int, payload['text'] as String);
      case 'message_end':
        closeBubble(payload['index'] as int);
      case 'restart':
        clearTurn();
      case 'done':
        onDone(payload['messages'] as List, payload['reactions'] as List);
      case 'error':
        onError(payload['error'] as String);
    }
  }
}

const res = await fetch(`${baseUrl}/api/chat/send`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ message: text }),
});

const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = '';
let eventName = null;

for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += value;
  const lines = buffer.split('\n');
  buffer = lines.pop();
  for (const line of lines) {
    if (line.startsWith('event: ')) eventName = line.slice(7).trim();
    else if (line.startsWith('data: ')) handle(eventName, JSON.parse(line.slice(6)));
  }
}

curl -N -X POST "$BASE_URL/api/chat/send" \
  -H "Authorization: Bearer $LALA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Merhaba"}'

Do not use the browser EventSource API. EventSource sends only GET requests and cannot set the Authorization header. Use fetch with a stream reader, as shown above.

Concurrency

Send one turn at a time for one student. The server does not reject a second concurrent request, but both turns read and write the same conversation history. Disable the send control until a terminal event arrives.

Start here

Build

Understand

For agents

Request

Lala answers in one message or several

Response events

Rules for the client

Tools change data while Lala writes

Reactions

No resume

Timing

Client code

Concurrency

​Request

​Lala answers in one message or several

​Response events

​Rules for the client

​Tools change data while Lala writes

​Reactions

​No resume

​Timing

​Client code

​Concurrency

Request

Lala answers in one message or several

Response events

Rules for the client

Tools change data while Lala writes

Reactions

No resume

Timing

Client code

Concurrency