Conversation Lifecycle

This guide covers the end-to-end conversation flow.

​

Connect a Conversation Session

Akapulu Labs uses Daily behind the scenes for live WebRTC audio and video transport. Your app starts a session by calling the connect endpoint, and Akapulu Labs handles room setup, assistant startup, and session coordination.

​

Connection flow diagram

​

Conversation participants

Each live conversation has a user participant and assistant participants in the Daily room:

• User participant: the person joining from your frontend (microphone and optional camera).
• Bot participants: Akapulu Labs runtime participants that handle orchestration and assistant media in the room.

Your application experience is the interaction between your user and the assistant in the same session.

​

End-to-end connection flow

1. Client calls connect
   • Your app sends POST /api/conversations/connect/ with:
     • Authorization: Bearer <API_KEY>
     • scenario_id
     • avatar_id (UUID)
     • optional runtime_vars
     • optional stt_keywords
   • scenario_id controls conversation behavior; avatar_id selects the avatar for that specific session.
2. Session is validated and prepared
   • API key ownership, scenario access, avatar access, and active plan limits are validated.
   • Scenario runtime configuration is prepared for the session.
3. Daily room and credentials are created
   • A private Daily room is created for the conversation.
   • Connection credentials are generated for the user session.
4. Connect response is returned
   • The connect response returns:
     • room_url
     • token
     • conversation_session_id
5. User joins the room
   • Your frontend uses room_url and token to join the Daily room.
6. Assistant runtime starts in parallel
   • The bot process starts for the selected scenario and avatar.
7. Bot participants join the room
   • After initialization completes, Akapulu Labs runtime participants join and the assistant media becomes available in-room.
8. Frontend monitors readiness
   • Poll GET /api/conversations/{conversation_session_id}/updates/ until call_is_ready is true, then stop.
   • Once ready, transition your UI from loading state to live in-call state. Transcripts and speaking state then come from the Daily room, not updates.

​

Pre-join timeout behavior

If no user participant joins the Daily room shortly after connect (45 seconds), Akapulu Labs automatically ends the session to avoid leaving an abandoned bot process running.

​

Understand Usage and Concurrency Limits

Conversation capacity is controlled by your current plan. Before a session starts, Akapulu Labs validates usage and concurrency limits for the API key owner.

​

How plan limits are applied

• Concurrency limit: each active conversation uses one concurrency slot.
• Max concurrency: total available slots come from your plan.
• Credits limit: total credits available come from your plan. One live conversation minute uses 1 credit. Scenario editor Testing Mode uses 0.25 credits per start (see Testing Mode). Scripted clip audio and video use the same pool.
• Per-call duration cap: each live session is capped by the lower of:
  • your plan’s max live call duration
  • your remaining credits (as whole minutes)

​

Concurrency behavior

When POST /api/conversations/connect/ succeeds, the new conversation reserves one active slot. If no slots are available, connect is rejected until another active conversation ends or expires.

​

Credit usage behavior

Live conversations debit 1 credit per minute while the call is ongoing (whole minutes). If remaining credits cannot cover another minute, connect is rejected (No minutes remaining for current plan). Clip audio and video charges are listed in clips overview. They come out of this same pool. If a user joins a call and reaches the session duration cap while the call is active, Akapulu Labs automatically ends the session. In this case, the frontend should handle a timeout event and show a clear message to the user (for example, usage limit reached). For Web SDK integrations, this appears as event.type === "timeout" with reason duration_limit_reached. You can view credits used, current concurrency slots used, and your next plan reset date on the Usage page.

​

Manage Recordings and Transcripts

You can view conversation sessions on the Conversations page. For each session, you can:

• open the transcript view, which shows a sanitized transcript that excludes full tool call messages
• click Download Recording to download and review the recording

​

API access

For programmatic access to conversation details and recordings:

• Conversation detail: session metadata and transcript rows.
• Conversation recording: signed URL for downloading the session recording.
• Post a system message: append context to a live call from your server. See Updating Conversation Context.

The Customized UI example implements conversation-details and recording handlers that call these endpoints with the Server SDK (@akapulu/server).