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"
  ],
  "voice_only_mode": false
}
'
{
  "room_url": "https://your-team.daily.co/room-name",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "conversation_session_id": "7f1e7f76-b38d-4d03-b8f8-2570ce8d4e6d"
}
Use this endpoint to create a conversation session and receive:
  • room_url
  • token
  • conversation_session_id
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 are optional keywords used in the speech-to-text step of the pipeline to improve recognition of specific words in user speech (maximum 5)
  • voice_only_mode for audio-only calls
  • custom_rtvi_connection when your frontend uses a custom RTVI connection
Example request body: 
{
  "scenario_id": "scenario_1234",
  "avatar_id": "avatar_5678",
  "runtime_vars": {
    "today": "2026-03-19"
  },
  "stt_keywords": ["Akapulu", "Dr. Nguyen", "A1C"],
  "voice_only_mode": false,
  "custom_rtvi_connection": false
}

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
string[]

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
​
voice_only_mode
boolean
default:false

If true, run the conversation in audio-only mode.

​
custom_rtvi_connection
boolean
default:false

If true, requires RTVI client readiness before call-ready state.

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.