Browse docs
On this page
Headless
Build your own chat UI with the SDK's authentication, transport, tools, and transcript state. Set up the same token endpoint used by the drop-in widget before connecting the session.
Connect a session
useAstralBeamChat returns a stable session and subscribes the component to its state updates. Read the current snapshot with chat.getState() and call actions directly on chat. Use it with the styled <AstralBeamChat chat={chat} /> view, or supply your own message and composer components:
tsx
import { useAstralBeamChat } from "@astralbeam/sdk/react"
function MyChat() {
const chat = useAstralBeamChat({})
const { messages, auth, status } = chat.getState()
return (
<div>
{messages.map((message) => (
<MyMessage key={message.id} message={message} />
))}
<MyComposer
disabled={auth.status !== "ready" || status !== "ready"}
onSend={chat.sendMessage}
/>
</div>
)
}- State from
chat.getState():messages,status,error,auth,capabilities,sandbox,sandboxStatus,agentTools,history,submission, andusageLimitReached, which names the usage limit that refused or ended the last run and when it resets. - Actions on
chat:sendMessage,retry,addToolResult,stop,reload,reset.reloadrefreshes saved history and can deliver retained tool results, without resubmitting user input. - Each send becomes the
submission, whosephasemoves fromsubmittingtoaccepted,failed, orrefused.sendMessageandretry()resolve with the attempt's outcome. - Clear your composer when you send, and return the
contentof arefusedoutcome to it. Afailedsubmission may have reached the server, so offerretry(). - An attempt the session declines, such as one sent while another is active, resolves
refusedwithout replacing the active submission.stop()returns an unsent message the same way. retry()reuses the admission key. Within 24 hours, an accepted retry restores saved history without starting another response.- Keep tool schemas outside render, or memoize schemas derived from props. Changing a schema invalidates pending execution. Tool callbacks can still read current props and state.
- Options follow the props you pass, including
agentId,apiUrl, andfetchAstralBeamToken. Remount when the host identity changes, as described in Authentication. - With your own components, there is no shadow root or bundled styling. See shared sessions for ownership and moving the styled view between layouts.
Reading the transcript
Treat messages, parts, and metadata as immutable snapshots. Use session actions to change the conversation and map, filter, or toSorted to derive display values.
Import transcript helpers from @astralbeam/sdk/core:
isSandboxTool,readSandboxFileWrite,readSandboxCommandRun,readSandboxArtifact,collectSandboxActivity.isSettledToolCall,lastPartInProgress,hasPendingToolRunfor busy states.- Protocol names (
RENDER_WIDGET_TOOL,ASK_QUESTIONNAIRE_TOOL, sandbox tool names) for custom renderers.
Saved conversation controls
Open a saved conversation the current user can access:
ts
const chat = createAstralBeamChat({ tools })
const page = await chat.searchThreads()
const threadId = page.items[0]?.id
if (!threadId) throw new Error("No saved conversations yet.")
await chat.openThread(threadId)
await chat.sendMessage("Continue from here")searchThreads(query?, cursor?, signal?)returns a page of conversations. Readthreadandhistoryfrom session state. Show loading only whilehistoryisloading, which means nothing is shown yet. A send duringrefreshingwaits for it.- Use
reset()for a fresh conversation. Managers can rename the selected thread withrenameThread(title)and delete any listed thread withdeleteThread(thread). - Keep tool responses associated with their stored call and target across browser clients.
- Reopening another client's saved state loads history. It does not replay live events or resume a disconnected stream.