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
Properties
Properties
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.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.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 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
The message text, as raw markdown. Show it before the message’s steps. It’s empty when the message only holds tool calls.
When the message was created, as an ISO 8601 timestamp in UTC that ends in
Z, such as
2026-10-25T11:00:00.000Z. new Date(createdAt) reads it correctly in any time zone.One step per tool call, in order.
Properties
Properties
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.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.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.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
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.Returned actions
Functions on the same object, which you call to act on the chat, as inchat.send(prompt). They
never throw. If Base44 refuses the request, or your backend fails before Base44 has the prompt or
answer, error is set.
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
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
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.
Next.js server actions run one at a time, so one that waits out the turn holds up every later
call. In a server action, wait a few seconds for a refusal instead, and resolve if none comes.
Base44 refuses a request right away.
Example
createApp()
createApp(Creates an app from its first prompt. The AI starts building inside this call.prompt):Promise<ChatApp>
Parameters
Returns
ChatApp
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
Returns
SocketSession
Promise resolving to the three fields of a Create socket session
response that the browser needs. Keep the response’s session_id on your server.
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 when Base44 answers the request, which can be when the turn ends.
Examples
submitToolCallInput()
submitToolCallInput(Answers or declines a question the AI waits on. If Base44 refuses the answer, reject the promise. The hook then setsappId,answer):Promise<void>
error and shows the question again.
Parameters
Properties
Properties
Properties
Properties
Returns
Promise<void>
Promise resolving when Base44 answers the request, which can be when the turn ends.
Example
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. If Base44 refuses an
answer, or your backend fails before Base44 has it, error is set 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.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.The fields to fill.
Properties
Properties
Name of the field, which keys its value in
submit().submit()
submit(Submits the values.values):Promise<void>
Parameters
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.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.What the action would do, as far as the check publishes it. Show it so the user knows what they approve.
Properties
Properties
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.