Skip to main content
POST
/
conversations
/
connect
Connect conversation
curl --request POST \
  --url https://akapulu.com/api/conversations/connect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scenario_id": "11111111-2222-3333-4444-555555555555",
  "avatar_id": "66666666-7777-8888-9999-000000000000",
  "runtime_vars": {
    "user_name": "Alex",
    "company_name": "Acme Corp",
    "support_ticket_id": "TICK-1024"
  },
  "stt_keywords": [
    "Akapulu",
    "Alex",
    "Acme"
  ],
  "record_conversation": false,
  "wait_for_client_ready": true
}
'
{
  "room_url": "https://your-team.daily.co/room-name",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "conversation_session_id": "7f1e7f76-b38d-4d03-b8f8-2570ce8d4e6d"
}

Documentation Index

Fetch the complete documentation index at: https://docs.akapulu.com/llms.txt

Use this file to discover all available pages before exploring further.

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. 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)
  • wait_for_client_ready controls when the session is marked ready to begin (default true)
    • when true, Akapulu waits until your frontend client is fully connected before marking the call ready
    • when false, Akapulu proceeds once the bot and participant are ready without waiting for explicit frontend-client readiness
    • use true for Web SDK integrations unless you have a specific reason not to
Example request body: 
{
  "scenario_id": "scenario_1234",
  "avatar_id": "avatar_5678",
  "runtime_vars": {
    "today": "2026-03-19"
  },
  "stt_keywords": ["Akapulu", "Dr. Nguyen", "A1C"],
  "record_conversation": true,
  "wait_for_client_ready": true
}

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.

​
wait_for_client_ready
boolean
default:true

If true, wait for explicit frontend client readiness before marking the call ready.

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.