Callbacks and events - Akapulu Labs

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

(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";

`ToolMessageType`

type ToolMessageType = "RAG" | "vision" | "http";

`TimeoutReason`

type TimeoutReason = "duration_limit_reached" | "participant_join_timeout";

Event types

`status_changed`

"status_changed"

Event discriminator.

Current high-level session lifecycle state.

`bot_speaking_state_changed`

"bot_speaking_state_changed"

Event discriminator.

"idle" | "speaking" | "listening"

Current speaking or listening state for the bot participant.

`node_changed`

"node_changed"

Event discriminator.

{ key: string; label: string } | null

Current scenario node, or null if no node is active.

`tool_event`

"tool_event"

Event discriminator.

NormalizedToolEvent

Normalized tool event payload.

Hide NormalizedToolEvent

"RAG" | "vision" | "http"

Tool message type.

string

Tool or function name.

string

Human-readable summary for the tool event.

string | undefined

Query string for RAG events when present.

string | undefined

Pretty JSON representation of HTTP tool arguments when present.

Record<string, unknown>

Raw body arguments for the tool event.

unknown

Underlying raw message before normalization.

`transcript_updated`

"transcript_updated"

Event discriminator.

TranscriptEntry

Transcript row payload.

Hide TranscriptEntry

string

Stable transcript row identifier.

string

Transcript text.

"user" | "bot"

Speaker that produced the transcript row.

string

Timestamp for the transcript row.

boolean

Whether the transcript row is finalized.

`call_ready`

"call_ready"

Event discriminator indicating the call reached ready state.

`timeout`

"timeout"

Event discriminator.

"duration_limit_reached" | "participant_join_timeout"

Timeout reason reported by the backend.

​Overview

​Event handling

​Hook signature

​Main unions

​SessionStatus

​BotSpeakingState

​ToolMessageType

​TimeoutReason

​Event types

​status_changed

​bot_speaking_state_changed

​node_changed

​tool_event

​transcript_updated

​call_ready

​timeout

​Related docs

Overview

Event handling

Hook signature

Main unions

`SessionStatus`

`BotSpeakingState`

`ToolMessageType`

`TimeoutReason`

Event types

`status_changed`

`bot_speaking_state_changed`

`node_changed`

`tool_event`

`transcript_updated`

`call_ready`

`timeout`

Related docs