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,
"show_ai_label": false
}
'import requests
url = "https://akapulu.com/api/conversations/connect"
payload = {
"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,
"show_ai_label": False
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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,
show_ai_label: false
})
};
fetch('https://akapulu.com/api/conversations/connect', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://akapulu.com/api/conversations/connect",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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,
'show_ai_label' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://akapulu.com/api/conversations/connect"
payload := strings.NewReader("{\n \"scenario_id\": \"11111111-2222-3333-4444-555555555555\",\n \"avatar_id\": \"66666666-7777-8888-9999-000000000000\",\n \"runtime_vars\": {\n \"user_name\": \"Alex\",\n \"company_name\": \"Acme Corp\",\n \"support_ticket_id\": \"TICK-1024\"\n },\n \"stt_keywords\": [\n \"Akapulu\",\n \"Alex\",\n \"Acme\"\n ],\n \"record_conversation\": false,\n \"show_ai_label\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://akapulu.com/api/conversations/connect")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"scenario_id\": \"11111111-2222-3333-4444-555555555555\",\n \"avatar_id\": \"66666666-7777-8888-9999-000000000000\",\n \"runtime_vars\": {\n \"user_name\": \"Alex\",\n \"company_name\": \"Acme Corp\",\n \"support_ticket_id\": \"TICK-1024\"\n },\n \"stt_keywords\": [\n \"Akapulu\",\n \"Alex\",\n \"Acme\"\n ],\n \"record_conversation\": false,\n \"show_ai_label\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://akapulu.com/api/conversations/connect")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"scenario_id\": \"11111111-2222-3333-4444-555555555555\",\n \"avatar_id\": \"66666666-7777-8888-9999-000000000000\",\n \"runtime_vars\": {\n \"user_name\": \"Alex\",\n \"company_name\": \"Acme Corp\",\n \"support_ticket_id\": \"TICK-1024\"\n },\n \"stt_keywords\": [\n \"Akapulu\",\n \"Alex\",\n \"Acme\"\n ],\n \"record_conversation\": false,\n \"show_ai_label\": false\n}"
response = http.request(request)
puts response.read_body{
"room_url": "https://your-team.daily.co/room-name",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"conversation_session_id": "7f1e7f76-b38d-4d03-b8f8-2570ce8d4e6d"
}Starting a conversation
Connect Conversation
Create a conversation session and return room credentials for joining.
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,
"show_ai_label": false
}
'import requests
url = "https://akapulu.com/api/conversations/connect"
payload = {
"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,
"show_ai_label": False
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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,
show_ai_label: false
})
};
fetch('https://akapulu.com/api/conversations/connect', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://akapulu.com/api/conversations/connect",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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,
'show_ai_label' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://akapulu.com/api/conversations/connect"
payload := strings.NewReader("{\n \"scenario_id\": \"11111111-2222-3333-4444-555555555555\",\n \"avatar_id\": \"66666666-7777-8888-9999-000000000000\",\n \"runtime_vars\": {\n \"user_name\": \"Alex\",\n \"company_name\": \"Acme Corp\",\n \"support_ticket_id\": \"TICK-1024\"\n },\n \"stt_keywords\": [\n \"Akapulu\",\n \"Alex\",\n \"Acme\"\n ],\n \"record_conversation\": false,\n \"show_ai_label\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://akapulu.com/api/conversations/connect")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"scenario_id\": \"11111111-2222-3333-4444-555555555555\",\n \"avatar_id\": \"66666666-7777-8888-9999-000000000000\",\n \"runtime_vars\": {\n \"user_name\": \"Alex\",\n \"company_name\": \"Acme Corp\",\n \"support_ticket_id\": \"TICK-1024\"\n },\n \"stt_keywords\": [\n \"Akapulu\",\n \"Alex\",\n \"Acme\"\n ],\n \"record_conversation\": false,\n \"show_ai_label\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://akapulu.com/api/conversations/connect")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"scenario_id\": \"11111111-2222-3333-4444-555555555555\",\n \"avatar_id\": \"66666666-7777-8888-9999-000000000000\",\n \"runtime_vars\": {\n \"user_name\": \"Alex\",\n \"company_name\": \"Acme Corp\",\n \"support_ticket_id\": \"TICK-1024\"\n },\n \"stt_keywords\": [\n \"Akapulu\",\n \"Alex\",\n \"Acme\"\n ],\n \"record_conversation\": false,\n \"show_ai_label\": false\n}"
response = http.request(request)
puts response.read_body{
"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_urltokenconversation_session_id
error and error_code. See Error responses.
Required headers:
Authorization: Bearer <YOUR_AKAPULU_API_KEY>Content-Type: application/json
scenario_idfor the scenario to runavatar_idfor the avatar to use in this conversation
runtime_varsfor template/runtime valuesstt_keywordsfor speech recognition hints- accepts either an array of strings or a comma-separated string
- maximum
5keywords
record_conversationwhether to record this conversation session (defaultfalse)show_ai_labelwhether to overlay a This is AI label on the live video (defaultfalse; allowed on every plan). The public landing-page demo always shows this label.
{
"scenario_id": "scenario_1234",
"avatar_id": "avatar_5678",
"runtime_vars": {
"today": "2026-03-19"
},
"stt_keywords": ["Akapulu", "Dr. Nguyen", "A1C"],
"record_conversation": true,
"show_ai_label": true
}
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Scenario ID to run for this conversation.
Avatar ID to use for this conversation.
Runtime variables injected into scenario templates.
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:
5If true, enable recording for this conversation session.
If true, overlay a This is AI label on the live video. Allowed on every plan. The landing-page demo always shows this label.

