Overview
useChat(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:options):UseChatResult
- 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 inconnection. - Sends prompts, creates apps, and answers questions through the backend you pass, so no credential reaches the browser.
Example
Parameters
ChatOptions
requis
The app to follow, your backend’s calls, and what to do with a created app.
Properties
Properties
string | null
requis
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
requis
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.Returned state
The hook returns one object, of typeUseChatResult. 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.
Properties
Properties
string
requis
ID of the message.
"user" | "assistant"
requis
Who wrote the message.
string
requis
The message text, as raw markdown. Show it before the message’s steps. It’s empty when the message only holds tool calls.
string
requis
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[]
requis
One step per tool call, in order.
Properties
Properties
string
requis
ID of the tool call.
string
requis
Name of the tool, such as
write_file.string[]
requis
The file paths the tool call touched.
string
requis
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"
requis
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[]
boolean
requis
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. Checkerrorto see why.
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.
Properties
Properties
string
requis
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 inchat.send(prompt). They
never throw. A failure sets error.
send()
send(Sends a prompt to the app the chat follows. The prompt appears inprompt):Promise<void>
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
requis
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(Creates an app from its first prompt. The prompt appears inprompt):Promise<void>
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
requis
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 thebackend 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:
createApp(): Create app, with the first prompt asinitial_message.openLiveSession(): Create socket session with{ app_ids: [appId] }. Return itssession_token,socket_url, andsocket_path, and keepsession_idon your server. None of them is the workspace API key.sendMessage(): Send chat message.submitToolCallInput(): Submit tool-call input. Send anX-Request-IDbuilt from the tool call ID, so a retry resumes the turn only once.
error.
Example
createApp()
createApp(Creates an app from its first prompt. The AI starts building inside this call.prompt):Promise<ChatApp>
Parameters
string
requis
The first prompt, which describes the app.
Returns
ChatApp
An app the AI chat works on.
Promise resolving to the new app.
Properties
Properties
Example
openLiveSession()
openLiveSession(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.appId):Promise<SocketSession>
Parameters
string
requis
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.
Properties
Properties
Example
sendMessage()
sendMessage(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 setsappId,content):Promise<void>
error, so your UI can show the
failure.
Parameters
Returns
Promise<void>
Promise resolving once Base44 accepts the prompt.
submitToolCallInput()
submitToolCallInput(Answers or declines a question the AI waits on.appId,answer):Promise<void>
Parameters
Properties
Properties
string
requis
ID of the app.
ToolCallAnswer
requis
The tool call and the answer to it.
Properties
Properties
string
requis
ID of the tool call being answered.
string
requis
ID of the assistant message that holds the tool call.
boolean
requis
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 =An open question the AI waits on. AChoiceQuestion|SecretsQuestion|ApprovalQuestion
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'
requis
Kind of question.
ChoiceEntry[]
requis
The questions, in order.
answer()
answer(Answers with the picked labels, and free text where the user wrote some. For a question whosepicked,texts?):Promise<void>
multi is false, only the first picked label counts.
Parameters
Properties
Properties
Returns
Promise<void>
Promise resolving once Base44 accepts the answer, or once sending it fails and sets error. It never rejects.
Example
decline()
decline():Declines the question. The AI continues without the answer.Promise<void>
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'
requis
Kind of question.
SecretField[]
requis
submit()
submit(Submits the values.values):Promise<void>
Parameters
Record<string, string>
requis
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():Declines the question. The AI continues without the values.Promise<void>
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'
requis
Kind of question.
string
requis
Name of the tool that wants to run.
string
requis
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
requis
The check that paused the action, such as
exec_tool_send_email or entity_rls_guard.ApprovalDetails
requis
What the action would do, as far as the check publishes it. Show it so the user knows what they approve.
Properties
Properties
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():Lets the action run.Promise<void>
Returns
Promise<void>
Promise resolving once Base44 accepts the approval, or once sending it fails and sets error. It never rejects.
Example
decline()
decline():Declines the action. It never runs, and the AI continues.Promise<void>
Returns
Promise<void>
Promise resolving once Base44 accepts the decline, or once sending it fails and sets error. It never rejects.