Skip to main content

Overview

useChat(options): UseChatResult
Runs an app’s AI chat in your own React UI. Requires a browser environment and can’t be used in the backend. The hook is headless. It gives you the conversation and the actions, and your components render them:
  • Follows the app live, and renews its socket session when it expires.
  • Turns Base44’s messages into items, and shows each open question with the step that asked it.
  • Reports what the AI is doing in status, and the live connection in connection.
  • Sends prompts, creates apps, and answers questions through the backend you pass, so no credential reaches the browser.

Example

Parameters

ChatOptions
required
The app to follow, your backend’s calls, and what to do with a created app.
string | null
required
ID of the app to follow, or null until an app exists. While it’s null, the chat follows the app that create() made, so you don’t have to pass the new ID back. Changing appId stops following that app, so setting it back to null starts a new chat. Switching to another app closes the old session and starts over.
ChatBackend
required
The functions the hook calls to reach Base44 through your backend, described in Backend calls. The hook uses the backend from the latest render, so you can pass an inline object without memoizing it.
(app: ChatApp) => void
Called with the new app after create() succeeds. The chat already follows the new app. To keep its ID in your own state, pass it back as appId.

Returned state

The hook returns one object, of type UseChatResult. Its state is below, and its functions are under Returned actions.

items

ChatItem[] The conversation, oldest first. Each open question appears with the step that asked it.
string
required
ID of the message.
"user" | "assistant"
required
Who wrote the message.
string
required
The message text, as raw markdown. Show it before the message’s steps. It’s empty when the message only holds tool calls.
string
required
When the message was created, as an ISO 8601 timestamp in UTC. A timestamp from Base44 has no Z or offset, so add a Z before parsing it with new Date(). A pending prompt has the browser’s time, which already ends in Z.
ChatStep[]
required
One step per tool call, in order.
string
required
ID of the tool call.
string
required
Name of the tool, such as write_file.
string[]
required
The file paths the tool call touched.
string
required
A line to show for the step. It’s Base44’s description of the step when there is one. Otherwise it’s the tool name followed by the entity the step touched and its record count, such as create_records Task (3), or by the step’s files.
"error" | "running" | "stopped" | "waiting" | "done"
required
The step’s progress. A waiting step needs the user to answer its question. A stopped step was declined, or its turn was stopped. A status this release doesn’t know counts as done.
ChatQuestion
The question the step needs answered, with the actions that answer it. It’s present only on a waiting step in the latest assistant reply, and goes away once answered. A waiting step in an older message has no question. It’s also absent for a question kind this release doesn’t know.
ChatAnswer[]
The user’s answers to a choice question, one for each question the step asked. It stays after the question closes, so you can show the answers in the chat’s history.
string
required
The question text.
string[]
required
The labels the user picked.
string
The free text the user wrote, if any.
boolean
required
Whether this is a stand-in for a prompt you just sent. When you call send() or create(), the prompt appears in items right away as a pending item, and Base44’s copy of the message replaces it once it arrives. A failed send removes it. A prompt sent while the AI is working waits in Base44’s queue, so it stays pending until it runs.

status

ChatStatus What the AI is doing. When several hold at once, the first in this list wins.
  • error: Base44 reports that the last build failed.
  • waiting: A question waits for the user’s answer.
  • building: The AI is working.
  • submitted: A prompt, a new app, or an answer is on its way. It lasts until Base44 reports work, a reply, or a queue change, or until the call fails.
  • ready: None of the above.

connection

ChatConnection Whether the chat follows the app live.
  • connecting: The chat waits for the app’s first snapshot.
  • connected: The first snapshot arrived, and updates follow live.
  • disconnected: Live updates stopped for good. The session couldn’t open, the retries ran out, or Base44 ended the session or the app’s subscription. Check error to see why.
Watching another app, or mounting the chat again, starts over.

error

ChatError | null The failure to show, or null. It’s set when a call fails, when the live connection fails, and whenever status is error. When more than one of these conditions is true, error holds the failed call first, then the connection error, then the failed build. A failed call’s error clears on the next action, and a connection error stays until clearError(). A failed build’s error stays while Base44 reports it. Switching to another app clears it.
string
required
A readable description of what went wrong, such as The build failed.
string
A value your code can check to handle the error, such as build_failed for a failed build. A connection error has one of the session or app error codes listed under the chat module’s Errors. A failed call to your backend has no code.
unknown
The error the failure came from, such as the one your backend threw. Log it to debug the failure. It’s absent when the hook found the failure itself, such as a failed build or a send with no app.

Returned actions

Functions on the same object, which you call to act on the chat, as in chat.send(prompt). They never throw. A failure sets error.

send()

send(prompt): Promise<void>
Sends a prompt to the app the chat follows. The prompt appears in items right away as a pending item, and the reply arrives there too. Base44 queues the prompt while the AI is working. If the chat doesn’t follow an app yet, it sets error instead. Use create() for the first prompt.

Parameters

string
required
The prompt to send.

Returns

Promise<void> Promise resolving once Base44 accepts the prompt, or once the send fails and sets error. It never rejects.

Example


create()

create(prompt): Promise<void>
Creates an app from its first prompt. The prompt appears in items right away as a pending item. Once the app exists, the hook passes it to onAppCreated. If appId is null, the chat then follows the new app. Otherwise it stays on the app it follows.

Parameters

string
required
The first prompt, which describes the app.

Returns

Promise<void> Promise resolving once the app exists, or once creating it fails and sets error. It never rejects.

Example


clearError()

clearError(): void
Clears a failed call’s or the connection’s error. A failed build’s error stays while Base44 reports it.

Returns

void

Example

Backend calls

The functions you write for the backend option. The hook calls them when it needs Base44, and each one usually forwards to a route on your own server, which adds your credentials. Keeping the Base44 requests on your server means the browser never holds a workspace API key or an access token. Your server can be written in any language. Each function’s route calls one Base44 endpoint: Base44 keeps the Send chat message and Submit tool-call input requests open until the AI finishes the turn. Resolve your call once Base44 accepts the request, not when it returns. The chat follows the rest live. A rejected promise from any call sets error.

Example

createApp()

createApp(prompt): Promise<ChatApp>
Creates an app from its first prompt. The AI starts building inside this call.

Parameters

string
required
The first prompt, which describes the app.

Returns

ChatApp An app the AI chat works on. Promise resolving to the new app.
string
required
ID of the app, 24 lowercase hexadecimal characters.
string
required
Display name of the app.

Example


openLiveSession()

openLiveSession(appId): Promise<SocketSession>
Opens a read-only socket session for one app. The chat calls it on the first connect and again whenever the session expires. Sessions last one hour.

Parameters

string
required
ID of the app to follow.

Returns

SocketSession The three fields of a Create socket session response that the browser needs. Keep the response’s session_id on your server. Promise resolving to the session.
string
required
Token that authenticates the socket. The client keeps it in memory and sends it only when the socket connects.
string
required
Origin of the platform socket, with no path, query, fragment, or credentials.
string
required
Absolute path the socket connects on, such as /ws/socket.io/.

Example


sendMessage()

sendMessage(appId, content): Promise<void>
Sends a prompt to an existing app. Base44 queues a prompt sent while the AI is working. If Base44 refuses the prompt, for example because the app is busy with an operation that blocks new messages, reject the promise. The hook then sets error, so your UI can show the failure.

Parameters

string
required
ID of the app.
string
required
The prompt.

Returns

Promise<void> Promise resolving once Base44 accepts the prompt.

submitToolCallInput()

submitToolCallInput(appId, answer): Promise<void>
Answers or declines a question the AI waits on.

Parameters

string
required
ID of the app.
ToolCallAnswer
required
The tool call and the answer to it.
string
required
ID of the tool call being answered.
string
required
ID of the assistant message that holds the tool call.
boolean
required
Whether to let the tool call run (true) or turn it down (false).
Record<string, unknown>
What the question asked for. A choice sends { answers }, and a secrets question sends { secrets }.

Returns

Promise<void> Promise resolving once Base44 accepts the answer.

Questions

ChatQuestion = ChoiceQuestion | SecretsQuestion | ApprovalQuestion
An open question the AI waits on. A waiting step carries it as its question, and status becomes waiting. Check kind to see which of the three kinds it is. Each kind has only the actions that fit it, and every kind can be declined. Calling an action closes the question right away and sends the answer through your submitToolCallInput(). The actions never throw. A failure sets error, and the question opens again. The hook declines a question kind this release doesn’t know, once per tool call, when Base44 names that kind on the last assistant message. If the decline fails, error says so, and the hook tries again after it reconnects.

ChoiceQuestion

The AI offers options and waits for the user to pick.
'choice'
required
Kind of question.
ChoiceEntry[]
required
The questions, in order.
string
required
The question text.
string
Supporting text for the question.
string
Base44’s type of question, such as text_input for one that takes only a free-text answer.
string[]
required
The option labels to pick from.
boolean
required
Whether more than one option can be picked.

answer()

answer(picked, texts?): Promise<void>
Answers with the picked labels, and free text where the user wrote some. For a question whose multi is false, only the first picked label counts.
Parameters
string[][]
required
One list of picked labels per question, in the order of questions.
string[]
One free-text answer per question, in the same order. Use it for a text_input question, or as a note beside a pick. A question with no pick and no text is skipped.
Returns
Promise<void> Promise resolving once Base44 accepts the answer, or once sending it fails and sets error. It never rejects.
Example

decline()

decline(): Promise<void>
Declines the question. The AI continues without the answer.
Returns
Promise<void> Promise resolving once Base44 accepts the decline, or once sending it fails and sets error. It never rejects.
Example

SecretsQuestion

The AI needs secrets, such as API keys. The values go to Base44, and the hook keeps none of them.
'secrets'
required
Kind of question.
SecretField[]
required
The fields to fill.
string
required
Name of the field, which keys its value in submit().
string
Where to get the value.

submit()

submit(values): Promise<void>
Submits the values.
Parameters
Record<string, string>
required
The values, keyed by each field’s name.
Returns
Promise<void> Promise resolving once Base44 accepts the values, or once sending it fails and sets error. It never rejects.
Example

decline()

decline(): Promise<void>
Declines the question. The AI continues without the values.
Returns
Promise<void> Promise resolving once Base44 accepts the decline, or once sending it fails and sets error. It never rejects.
Example

ApprovalQuestion

The AI asks for permission to run an action.
'approval'
required
Kind of question.
string
required
Name of the tool that wants to run.
string
required
Why the action needs approval. It’s Base44’s reason when there is one, otherwise the summary in details, and empty when neither is given.
string
required
The check that paused the action, such as exec_tool_send_email or entity_rls_guard.
ApprovalDetails
required
What the action would do, as far as the check publishes it. Show it so the user knows what they approve.
string
The AI’s summary of what the code does.
string
The entity whose records or access rules change.
string
How the access rules change.
string[]
The access operations whose rules change.
string
The backend function under test.
string
The entity method the code calls, such as delete.
boolean
Whether the check couldn’t verify the function’s source.

approve()

approve(): Promise<void>
Lets the action run.
Returns
Promise<void> Promise resolving once Base44 accepts the approval, or once sending it fails and sets error. It never rejects.
Example

decline()

decline(): Promise<void>
Declines the action. It never runs, and the AI continues.
Returns
Promise<void> Promise resolving once Base44 accepts the decline, or once sending it fails and sets error. It never rejects.
Example