Skip to main content
POST
Connect conversation
Use this endpoint to create a conversation session and receive:
  • room_url
  • token
  • conversation_session_id
The connect endpoint returns immediately after creating the conversation session and Daily room credentials. Use the updates endpoint to poll setup progress until the conversation is ready, then stop. On failure the body includes error and error_code. See Error responses. Required headers:
  • Authorization: Bearer <YOUR_AKAPULU_API_KEY>
  • Content-Type: application/json
Required request fields:
  • scenario_id for the scenario to run
  • avatar_id for the avatar to use in this conversation
Optional request fields include:
  • runtime_vars for template/runtime values
  • stt_keywords for speech recognition hints
    • accepts either an array of strings or a comma-separated string
    • maximum 5 keywords
  • record_conversation whether to record this conversation session (default false)
  • show_ai_label whether to overlay a This is AI label on the live video (default false; allowed on every plan). The public landing-page demo always shows this label.
Example request body:

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
scenario_id
string<uuid>
required

Scenario ID to run for this conversation.

avatar_id
string<uuid>
required

Avatar ID to use for this conversation.

runtime_vars
object

Runtime variables injected into scenario templates.

stt_keywords

Optional keywords used in the speech-to-text step of the pipeline to improve recognition of specific words in user speech (maximum 5).

Maximum array length: 5
record_conversation
boolean
default:false

If true, enable recording for this conversation session.

show_ai_label
boolean
default:false

If true, overlay a This is AI label on the live video. Allowed on every plan. The landing-page demo always shows this label.

Response

Conversation connection created successfully

room_url
string
required

Daily room URL for the session.

token
string
required

Daily access token for joining the room.

conversation_session_id
string<uuid>
required

Created conversation session ID.