)}
/>
);
}
```
### Handling all conversation events while keeping prebuilt UI
For full event handling (node changes, bot speaking state, transcript updates, tool calls, and timeout), add a small sibling listener component that uses `useAkapuluEvents`.
```tsx theme={null}
import { AkapuluProvider, useAkapuluEvents } from "@akapulu/react";
import { AkapuluConversation } from "@akapulu/react-ui";
function ConversationEventListener() {
useAkapuluEvents((event) => {
// … handle `event` (discriminated by `event.type`; see schema below)
});
return null;
}
export function App() {
return (
);
}
```
Event schema by `event.type`:
#### `status_changed`
| Field | Type | Description |
| -------- | -------------------------------------------------------------------------------- | ----------------------- |
| `type` | `"status_changed"` | Discriminator |
| `status` | `"idle" \| "connecting" \| "connected" \| "disconnecting" \| "ended" \| "error"` | Session lifecycle state |
#### `bot_speaking_state_changed`
| Field | Type | Description |
| --------------- | ------------------------------------- | ---------------------------- |
| `type` | `"bot_speaking_state_changed"` | Discriminator |
| `speakingState` | `"idle" \| "speaking" \| "listening"` | Bot speaking/listening state |
#### `node_changed`
| Field | Type | Description |
| ------ | ---------------------------------------- | ----------------- |
| `type` | `"node_changed"` | Discriminator |
| `node` | `{ key: string; label: string } \| null` | Current flow node |
#### `tool_event`
| Field | Type | Description |
| ------ | --------------------- | ----------------------------- |
| `type` | `"tool_event"` | Discriminator |
| `tool` | `NormalizedToolEvent` | Normalized tool event payload |
#### `transcript_updated`
| Field | Type | Description |
| ------------ | ---------------------- | ---------------------- |
| `type` | `"transcript_updated"` | Discriminator |
| `transcript` | `TranscriptEntry` | Updated transcript row |
#### `call_ready`
| Field | Type | Description |
| ------ | -------------- | ------------------------ |
| `type` | `"call_ready"` | Call reached ready state |
#### `timeout`
| Field | Type | Description |
| -------- | -------------------------------------------------------- | --------------------------- |
| `type` | `"timeout"` | Discriminator |
| `reason` | `"duration_limit_reached" \| "participant_join_timeout"` | Timeout reason from backend |
```tsx theme={null}
import { AkapuluProvider, useAkapuluEvents } from "@akapulu/react";
import { AkapuluConversation } from "@akapulu/react-ui";
function ConversationEventBridge() {
useAkapuluEvents((event) => {
if (event.type === "transcript_updated") {
// event.transcript
return;
}
if (event.type === "bot_speaking_state_changed") {
// event.speakingState: "idle" | "speaking" | "listening"
return;
}
if (event.type === "node_changed") {
// event.node
return;
}
if (event.type === "tool_event") {
// event.tool
return;
}
if (event.type === "timeout") {
// event.reason:
// - "duration_limit_reached" => call ended because session duration cap was reached
// - "participant_join_timeout" => call ended because no participant joined in time
return;
}
});
return null;
}
export function App() {
return (
);
}
```
## Using `@akapulu/react` without `@akapulu/react-ui`
The **same** connect/updates route pattern applies: `AkapuluProvider` points at your local `connectPath` and `updatesPath`, your server uses `@akapulu/server`. What changes is **UI**: you build layout yourself and pull state from hooks instead of mounting `AkapuluConversation`.
**How it fits together**
1. Wrap your tree in `AkapuluProvider` (as in the Quickstart).
```tsx theme={null}
{/* your UI */}
```
2. Call `useAkapuluSession()` anywhere under that provider. It exposes everything in the session store plus `start` / `end`:
**Lifecycle & connection**
* `status` — where the client is in the join/leave flow: `"idle"` → `"connecting"` → `"connected"` → `"disconnecting"` / `"ended"`, or `"error"` if something failed.
* `start` / `end` — async actions that begin the conversation (connect + Daily join) or hang up and reset session state.
* `error` — when `status` is `"error"`, structured details (`code` optional, `message` required) for your error UI or logging.
**Call readiness & updates** (from your **updates** route)
* `callIsReady` — whether the backend considers the call ready (often used while `status === "connecting"` so you are not stuck on a spinner forever).
* `completionPercent` — numeric progress through the scenario (0–100).
* `latestUpdateText` — short human-readable status line for loading/progress copy.
**Scenario / flow**
* `currentNode` — the active scenario node (`{ key, label }`) or `null` if none.
**Transcript & bot**
* `transcripts` — ordered list of rows (`id`, `text`, `speaker`, `timestamp`, `isFinal`) for your own transcript UI.
* `botSpeakingState` — `"idle"`, `"speaking"`, or `"listening"` for indicators or turn-taking UI.
**Correlation**
* `conversationSessionId` — Akapulu Labs conversation session id from connect (used when polling updates; also useful if your app logs or links out to dashboard/API records).
```tsx theme={null}
const {
status,
start,
end,
error,
callIsReady,
conversationSessionId,
completionPercent,
latestUpdateText,
currentNode,
transcripts,
botSpeakingState,
} = useAkapuluSession();
```
3. The provider joins the **Daily** room for realtime media. Install `@daily-co/daily-react` (and peer `@daily-co/daily-js`) and use its primitives to draw video—for example `DailyVideo`, `useDaily`, and `useVideoTrack`. For assistant video selection, use `useAkapuluParticipantRoles` from `@akapulu/react`.
```tsx theme={null}
import { useAkapuluParticipantRoles } from "@akapulu/react";
import { DailyVideo, useDaily, useVideoTrack } from "@daily-co/daily-react";
function BotVideoTile() {
const { akapuluBotParticipantId } = useAkapuluParticipantRoles();
const track = useVideoTrack(akapuluBotParticipantId);
if (!akapuluBotParticipantId || track.isOff) return null;
return ;
}
function SelfVideoTile() {
const daily = useDaily();
const sessionId = daily?.participants().local.session_id ?? "";
const track = useVideoTrack(sessionId);
if (!sessionId || track.isOff) return null;
return ;
}
```
4. Use `useAkapuluMediaControls()` for in-call mic and camera toggles (wired to that Daily session).
```tsx theme={null}
const { toggleMic, toggleCam, isMicMuted, isCamOff } = useAkapuluMediaControls();
```
5. Render `` once in the tree so assistant audio plays (small hidden element; required for typical voice/video bots).
```tsx theme={null}
```
6. Optionally `useAkapuluEvents(callback)` to react to the full event stream (`transcript_updated`, `tool_event`, `node_changed`, `timeout`, etc.) while still rendering your own UI.
```tsx theme={null}
useAkapuluEvents((event) => {
// … handle `event`
});
```
**Rough outline**
```tsx theme={null}
"use client";
import {
AkapuluBotAudio,
AkapuluProvider,
useAkapuluEvents,
useAkapuluMediaControls,
useAkapuluParticipantRoles,
useAkapuluSession,
} from "@akapulu/react";
import { DailyVideo, useDaily, useVideoTrack } from "@daily-co/daily-react";
// Single participant video tile; Daily hooks are available because `AkapuluProvider` wraps Daily context.
function VideoTile(props: { sessionId: string; isLocal: boolean }) {
// Track state for this participant’s video in the current Daily call.
const videoTrack = useVideoTrack(props.sessionId);
if (videoTrack.isOff) {
// TODO: render your own “camera off” placeholder here.
return null;
}
// `sessionId` must be this participant’s Daily `session_id` (from `useAkapuluParticipantRoles` or `participants().local`).
return ;
}
function CustomCallUi() {
// Akapulu Labs session: status, lifecycle controls, transcript + progress state.
const {
status,
start,
end,
error,
transcripts,
completionPercent,
latestUpdateText,
botSpeakingState,
currentNode,
} = useAkapuluSession();
// Media controls for the underlying Daily call.
const { toggleMic, toggleCam, isMicMuted, isCamOff } = useAkapuluMediaControls();
// Daily participant roles + local self.
const daily = useDaily();
// Assistant video participant id selected from Daily roles.
const { akapuluBotParticipantId } = useAkapuluParticipantRoles();
// Local browser participant (the user/self-view tile).
const localParticipant = daily?.participants().local;
const localId = localParticipant?.session_id ?? "";
// Subscribe to high-level conversation events (status, tools, transcript, node, timeouts).
useAkapuluEvents((event) => {
if (event.type === "status_changed") {
// handle session lifecycle changes (idle/connecting/connected/ended/error)
return;
}
if (event.type === "tool_event") {
// handle RAG / HTTP / vision tool activity
return;
}
if (event.type === "transcript_updated") {
// handle incremental transcript updates
return;
}
if (event.type === "node_changed") {
// handle scenario node changes
return;
}
if (event.type === "bot_speaking_state_changed") {
// handle bot speaking/listening/idle state
return;
}
if (event.type === "timeout") {
// handle duration / participant_join timeouts
return;
}
});
// Render behavior by session status:
// - error -> dedicated error surface
// - idle / ended -> pre-call surface (+ start button)
// - connecting -> loading/progress surface
// - connected -> full in-call surface (video, controls, transcript)
switch (status) {
case "error":
return (
<>
{/* TODO: dedicated error UI*/}
);
case "idle":
case "ended":
return (
<>
{/* TODO: pre-call UI (title, consent, etc.) */}
);
case "connecting":
return (
<>
Connecting...
{/* TODO: replace with your spinner component */}
Spinner
{latestUpdateText}
);
case "connected":
return (
<>
{/* TODO: in-call header (botSpeakingState, currentNode, etc.) */}
{/* Assistant video */}
{akapuluBotParticipantId ? (
) : (
<>{/* TODO: waiting-for-bot-video placeholder */}
)}
{/* User/self-view video (local participant from this browser). */}
{localParticipant ? (
) : (
<>{/* TODO: waiting-for-user-video placeholder */}
)}
{/* Call controls */}
<>
{/* Transcript surface */}
<>
{transcripts.map((entry) => {
// TODO: return your transcript row component (use key={entry.id}).
// TODO: use entry.speaker / entry.text / entry.isFinal for row content + styling.
return null;
})}
);
}
}
export function App() {
return (
);
}
```
**Main exports from `@akapulu/react`**
| Export | Role |
| ------------------------- | ----------------------------------------------------------- |
| `AkapuluProvider` | Config, session store, Daily context for children |
| `useAkapuluSession` | Session state + `start` / `end` |
| `useAkapuluMediaControls` | Mic/cam state and toggles |
| `AkapuluBotAudio` | Plays bot audio track |
| `useAkapuluEvents` | Subscribe to `AkapuluEvent` stream |
| `useAkapuluDailyCall` | Access the Daily call object when you need lower-level APIs |
**Ending a call:** When **your user** ends the call in your app, call `end()` from `useAkapuluSession()`. That leaves the Daily room from the browser and runs the SDK teardown so the session is no longer live. If the **assistant** disconnects from Daily first, `AkapuluProvider` calls `end()` for you so `status` does not stay `connected` with no assistant in the room.
**Types and shared logic**
Use `AkapuluEvent` from `@akapulu/react`. For `TranscriptEntry`, `NormalizedToolEvent`, and related handler shapes on `AkapuluConversation`, align with the prop types exported from `@akapulu/react-ui`.
## Conversation detail and recording
Separate from the live call **connect** and **updates** loop, `@akapulu/server` can fetch post-call (or in-progress) **conversation detail** and **recording** responses from your backend—for example dedicated HTTP handlers your UI calls after `conversation_session_id` is known.
### Conversation detail retrieval
`@akapulu/server` also exposes `getConversationDetail(conversationSessionId)` for fetching a completed or in-progress conversation detail payload from your backend.
```ts theme={null}
import { createAkapuluServerClient } from "@akapulu/server";
const akapulu = createAkapuluServerClient();
// GET /api/akapulu/conversation-details?conversation_session_id=...
export async function conversationDetailsRoute(conversationSessionId: string) {
return await akapulu.getConversationDetail(conversationSessionId);
}
```
JSON body shape (matches `ConversationDetailResponse` from `@akapulu/server`):
| Field | Type | Description |
| ----------------- | -------- | ------------------------------------------------------------------------------ |
| `id` | `string` | Conversation id |
| `created_at` | `string` | Created timestamp |
| `created_at_text` | `string` | Human-readable created time |
| `duration_text` | `string` | Human-readable duration |
| `avatar` | object | Avatar summary (see below) |
| `scenario_id` | `string` | Scenario id |
| `recording` | object | Recording metadata on this conversation (see below; not the downloadable file) |
| `transcript_rows` | array | Ordered transcript rows (see below) |
#### `avatar`
| Field | Type | Description |
| ------------------- | -------- | ------------------- |
| `id` | `string` | Avatar id |
| `href` | `string` | Avatar resource URL |
| `profile_image_url` | `string` | Profile image URL |
#### `recording` (detail payload)
| Field | Type | Description |
| --------------- | --------- | --------------------------------------- |
| `has_recording` | `boolean` | Whether a recording exists |
| `status_text` | `string` | Recording status for display |
| `is_ready` | `boolean` | Whether the recording is ready to fetch |
#### `transcript_rows[]`
| Field | Type | Description |
| -------------- | ---------------------- | ------------------ |
| `role` | `string` | Speaker / row role |
| `content` | `string` (optional) | Row text |
| `node_id` | `string` (optional) | Scenario node id |
| `tool_call_id` | `string` (optional) | Tool call id |
| `tool_calls` | `unknown[]` (optional) | Tool call payloads |
### Conversation recording retrieval
`@akapulu/server` also exposes `getConversationRecording(conversationSessionId)` for fetching the recording response for a conversation from your backend.
```ts theme={null}
import { createAkapuluServerClient } from "@akapulu/server";
const akapulu = createAkapuluServerClient();
// GET /api/akapulu/view-recording?conversation_session_id=...
export async function recordingRoute(conversationSessionId: string) {
return await akapulu.getConversationRecording(conversationSessionId);
}
```
Return value shape (discriminated union, `ConversationRecordingResponse` from `@akapulu/server`):
| `kind` | Meaning |
| ------------ | ------------------------------------------------------------- |
| `"redirect"` | Akapulu Labs responded with a redirect; follow `location`. |
| `"json"` | Response body was JSON; see `payload`. |
| `"binary"` | Raw bytes (for example a media file); see `body` and headers. |
#### `kind: "redirect"`
| Field | Type | Description |
| ---------- | ------------ | ----------------- |
| `kind` | `"redirect"` | Discriminator |
| `status` | `number` | HTTP status (3xx) |
| `location` | `string` | `Location` URL |
#### `kind: "json"`
| Field | Type | Description |
| --------- | --------- | ---------------- |
| `kind` | `"json"` | Discriminator |
| `status` | `number` | HTTP status |
| `payload` | `unknown` | Parsed JSON body |
#### `kind: "binary"`
| Field | Type | Description |
| -------------------- | ------------- | --------------------- |
| `kind` | `"binary"` | Discriminator |
| `status` | `number` | HTTP status |
| `body` | `ArrayBuffer` | Raw response bytes |
| `contentType` | `string` | `Content-Type` |
| `contentDisposition` | `string` | `Content-Disposition` |
## Examples
Runnable apps that mirror this guide are available as standalone Vite + Express repos. Each has an Express `backend/` with **`@akapulu/server`** route handlers for `POST /api/connect` and `GET /api/updates?conversation_session_id=…`, plus a React `frontend/`.
* [Prebuilt UI](/examples/web-sdk/prebuilt-ui) — [`Akapulu/prebuilt-ui`](https://github.com/Akapulu/prebuilt-ui): **`@akapulu/react`** (`AkapuluProvider` with local `connectPath` / `updatesPath`) plus **`@akapulu/react-ui`** (`AkapuluConversation` for the full default layout: video, transcript, controls). Useful when you want to ship quickly and customize via props or CSS rather than rebuilding layout.
* [Prebuilt UI (styled)](/examples/web-sdk/prebuilt-ui-styled) — [`Akapulu/prebuilt-ui-styled`](https://github.com/Akapulu/prebuilt-ui-styled): the same prebuilt path with a dark theme, a custom tool toast, and a post-call review screen (recording + transcript).
* [Customized UI](/examples/web-sdk/customized-ui) — [`Akapulu/customized-ui`](https://github.com/Akapulu/customized-ui): **`@akapulu/react` only**—same provider pattern, then **`useAkapuluSession`**, **`useAkapuluMediaControls`**, **`useAkapuluParticipantRoles`**, **`useAkapuluEvents`**, **`AkapuluBotAudio`**, and **`@daily-co/daily-react`** (`DailyVideo`, track hooks) for your own chrome. Useful when you need full control over markup and state wiring.