Customize Conversation UI

import { AkapuluProvider } from "@akapulu/react";
import { AkapuluConversation } from "@akapulu/react-ui";

export function App() {
  return (
    <AkapuluProvider
      config={{
        endpoints: {
          connectPath: "/api/akapulu/connect",
          updatesPath: "/api/akapulu/updates",
        },
      }}
    >
      <AkapuluConversation title="Akapulu demo" />
    </AkapuluProvider>
  );
}

import { createAkapuluServerClient } from "@akapulu/server";

const akapulu = createAkapuluServerClient();

// POST /api/akapulu/connect
export async function connectRoute() {
  return await akapulu.connectConversation({
    scenario_id: "YOUR_SCENARIO_ID",
    avatar_id: "YOUR_AVATAR_ID",
    runtime_vars: {},
    record_conversation: false,
    show_ai_label: false,
  });
}

// GET /api/akapulu/updates?conversation_session_id=...
export async function updatesRoute(conversationSessionId: string) {
  return await akapulu.pollConversationUpdates(conversationSessionId);
}

import { AkapuluProvider } from "@akapulu/react";
import { AkapuluConversation } from "@akapulu/react-ui";

export function App() {
  return (
    <AkapuluProvider
      config={{
        endpoints: {
          connectPath: "/api/akapulu/connect",
          updatesPath: "/api/akapulu/updates",
        },
        connectBody: {
          tenant_id: "acme-health",
          patient_id: "patient_001",
          should_record: true,
        },
        headers: async () => {
          const token = await getAccessToken();
          return { Authorization: `Bearer ${token}` };
        },
      }}
    >
      <AkapuluConversation title="Akapulu demo" />
    </AkapuluProvider>
  );
}

import { createAkapuluServerClient } from "@akapulu/server";

const akapulu = createAkapuluServerClient();

type LocalConnectBody = {
  tenant_id?: string;
  patient_id?: string;
  should_record?: boolean;
};

export async function connectRoute(body: LocalConnectBody) {
  return await akapulu.connectConversation({
    scenario_id: "YOUR_SCENARIO_ID",
    avatar_id: "YOUR_AVATAR_ID",
    runtime_vars: {
      patient_id: body.patient_id || "patient_001",
      tenant_id: body.tenant_id || "default_tenant",
    },
    record_conversation: body.should_record === true,
    show_ai_label: false,
  });
}

<AkapuluConversation
  title="Akapulu demo"
  classes={{
    transcriptContainer: "myTranscriptContainer",
    controlEnd: "myLeaveButton",
  }}
  styles={{
    videoPane: { borderRadius: 20 },
    connectedLayout: { gap: "1.5rem" },
  }}
/>

.akapulu-transcript-container {
  border: 1px solid #334155;
  border-radius: 14px;
}

.akapulu-control-end {
  background: rgba(185, 28, 28, 0.9);
}

[data-slot="transcript-header"] {
  backdrop-filter: blur(2px);
}

[data-slot="pip"] {
  width: 28%;
  border-color: #60a5fa;
}

transcriptFilter?: (entry: TranscriptEntry) => boolean;
renderTranscriptEntry?: (entry: TranscriptEntry) => ReactNode;
onToolEvent?: (tool: NormalizedToolEvent) => void;
renderToolEvent?: (tool: NormalizedToolEvent) => ReactNode;
toolEventTimeoutMs?: number | null;
playConnectChime?: boolean;

import { AkapuluProvider } from "@akapulu/react";
import { AkapuluConversation } from "@akapulu/react-ui";

export function App() {
  return (
    <AkapuluProvider config={config}>
      <AkapuluConversation
        title="Akapulu demo"
        transcriptFilter={(entry) => {
          // Example: skip rows you do not want in the transcript list
          return entry.text.trim() !== "skip me";
        }}
        renderTranscriptEntry={(entry) => (
          <div>
            <strong>{entry.speaker === "user" ? "You" : "Bot"}:</strong> {entry.text}
          </div>
        )}
        onToolEvent={(tool) => {
          // Example: analytics side effect
          console.log("tool_event", tool.messageType, tool.functionName);
        }}
        renderToolEvent={(tool) => (
          <div style={{ border: "1px solid #334155", borderRadius: 8, padding: 12 }}>
            <strong>{tool.summary}</strong>
            <div style={{ marginTop: 6, opacity: 0.85 }}>{tool.functionName}</div>
          </div>
        )}
      />
    </AkapuluProvider>
  );
}

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 (
    <AkapuluProvider
      config={{
        endpoints: {
          connectPath: "/api/akapulu/connect",
          updatesPath: "/api/akapulu/updates",
        },
      }}
    >
      <AkapuluConversation title="Akapulu demo" />
      <ConversationEventListener />
    </AkapuluProvider>
  );
}

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 (
    <AkapuluProvider config={config}>
      <ConversationEventBridge />
      <AkapuluConversation title="Akapulu demo" />
    </AkapuluProvider>
  );
}

<AkapuluProvider
  config={{
    endpoints: {
      connectPath: "/api/akapulu/connect",
      updatesPath: "/api/akapulu/updates",
    },
  }}
>
  {/* your UI */}
</AkapuluProvider>

const {
  status,
  start,
  end,
  error,
  callIsReady,
  conversationSessionId,
  completionPercent,
  latestUpdateText,
  currentNode,
  transcripts,
  botSpeakingState,
} = useAkapuluSession();

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 <DailyVideo sessionId={akapuluBotParticipantId} type="video" />;
}

function SelfVideoTile() {
  const daily = useDaily();
  const sessionId = daily?.participants().local.session_id ?? "";
  const track = useVideoTrack(sessionId);
  if (!sessionId || track.isOff) return null;
  return <DailyVideo sessionId={sessionId} type="video" />;
}

const { toggleMic, toggleCam, isMicMuted, isCamOff } = useAkapuluMediaControls();

<button type="button" onClick={() => void toggleMic()}>
  Mic {isMicMuted ? "unmute" : "mute"}
</button>
<button type="button" onClick={() => void toggleCam()}>
  Cam {isCamOff ? "on" : "off"}
</button>

<AkapuluBotAudio />

useConnectChime();

useAkapuluEvents((event) => {
  // … handle `event`
});

"use client";

import {
  AkapuluBotAudio,
  AkapuluProvider,
  useAkapuluEvents,
  useAkapuluMediaControls,
  useAkapuluParticipantRoles,
  useAkapuluSession,
  useConnectChime,
} 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 <DailyVideo sessionId={props.sessionId} type="video" />;
}

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

  useConnectChime();

  // 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*/}
          <AkapuluBotAudio />
        </>
      );

    case "idle":
    case "ended":
      return (
        <>
          {/* TODO: pre-call UI (title, consent, etc.) */}
          <button type="button" onClick={() => void start()}>
            Start call
          </button>
          <AkapuluBotAudio />
        </>
      );

    case "connecting":
      return (
        <>
          <p>Connecting...</p>
          {/* TODO: replace with your spinner component */}
          <div>Spinner</div>
          <progress value={completionPercent} max={100} />
          <p>{latestUpdateText}</p>
          <AkapuluBotAudio />
        </>
      );

    case "connected":
      return (
        <>
          {/* TODO: in-call header (botSpeakingState, currentNode, etc.) */}
          {/* Assistant video */}
          {akapuluBotParticipantId ? (
            <VideoTile sessionId={akapuluBotParticipantId} isLocal={false} />
          ) : (
            <>{/* TODO: waiting-for-bot-video placeholder */}</>
          )}

          {/* User/self-view video (local participant from this browser). */}
          {localParticipant ? (
            <VideoTile sessionId={localParticipant.session_id} isLocal />
          ) : (
            <>{/* TODO: waiting-for-user-video placeholder */}</>
          )}

          {/* Call controls */}
          <>
            <button onClick={toggleMic}>
              {isMicMuted ? "Unmute" : "Mute"}
            </button>
            <button onClick={toggleCam}>
              {isCamOff ? "Camera on" : "Camera off"}
            </button>
            <button onClick={() => void end()}>
              Leave
            </button>
          </>

          {/* 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;
            })}
          </>
          <AkapuluBotAudio />
        </>
      );
  }
}

export function App() {
  return (
    <AkapuluProvider
      config={{
        endpoints: {
          connectPath: "/api/akapulu/connect",
          updatesPath: "/api/akapulu/updates",
        },
        // Optional connectBody / headers — see "Passing a body and headers" above.
      }}
    >
      <CustomCallUi />
    </AkapuluProvider>
  );
}

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);
}

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);
}