Overview
The Akapulu React SDK exposes a normalized conversation event stream through useAkapuluEvents(...).
This hook lets you react to conversation lifecycle changes, transcript updates, tool events, node changes, bot speaking state, and timeout events.
Event handling
Use useAkapuluEvents(listener) anywhere under AkapuluProvider.
import { useAkapuluEvents } from "@akapulu/react";
function EventLogger() {
useAkapuluEvents((event) => {
if (event.type === "tool_event") {
console.log(event.tool.functionName);
return;
}
if (event.type === "transcript_updated") {
console.log(event.transcript.text);
}
});
return null;
}
Hook signature
useAkapuluEvents(listener: (event: AkapuluEvent) => void): void
listener
(event: AkapuluEvent) => void
required
Listener invoked whenever the Akapulu session store emits a normalized event.
Main unions
SessionStatus
type SessionStatus =
| "idle"
| "connecting"
| "connected"
| "disconnecting"
| "ended"
| "error";
BotSpeakingState
type BotSpeakingState = "idle" | "speaking" | "listening";
type ToolMessageType = "RAG" | "vision" | "http";
TimeoutReason
type TimeoutReason = "duration_limit_reached" | "participant_join_timeout";
Event types
status_changed
status
"idle" | "connecting" | "connected" | "disconnecting" | "ended" | "error"
Current high-level session lifecycle state.
bot_speaking_state_changed
type
"bot_speaking_state_changed"
Event discriminator.
speakingState
"idle" | "speaking" | "listening"
Current speaking or listening state for the bot participant.
node_changed
node
{ key: string; label: string } | null
Current scenario node, or null if no node is active.
Normalized tool event payload.
messageType
"RAG" | "vision" | "http"
Tool message type.
Human-readable summary for the tool event.
Query string for RAG events when present.
Pretty JSON representation of HTTP tool arguments when present.
Raw body arguments for the tool event.
Underlying raw message before normalization.
transcript_updated
Transcript row payload.
Stable transcript row identifier.
Speaker that produced the transcript row.
Timestamp for the transcript row.
Whether the transcript row is finalized.
call_ready
Event discriminator indicating the call reached ready state.
timeout
reason
"duration_limit_reached" | "participant_join_timeout"
Timeout reason reported by the backend.
