Create a new persona

POST

persona

JavaScript

import Roark from '@roarkanalytics/sdk';

const client = new Roark({
  bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted
});

const simulationPersona = await client.simulationPersona.create({
  accent: 'US',
  gender: 'MALE',
  language: 'EN',
  name: 'name',
});

console.log(simulationPersona.data);

import os
from roark_analytics import Roark

client = Roark(
    bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted
)
simulation_persona = client.simulation_persona.create(
    accent="US",
    gender="MALE",
    language="EN",
    name="name",
)
print(simulation_persona.data)

curl --request POST \
  --url https://api.roark.ai/v1/persona \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "secondaryLanguage": "EN",
  "understoodLanguages": [],
  "backgroundNoise": "NONE",
  "speechPace": "NORMAL",
  "speechClarity": "CLEAR",
  "hasDisfluencies": false,
  "baseEmotion": "NEUTRAL",
  "intentClarity": "CLEAR",
  "confirmationStyle": "EXPLICIT",
  "memoryReliability": "HIGH",
  "responseTiming": "NORMAL",
  "backstoryPrompt": "A busy professional calling during lunch break",
  "idleMessages": [
    "<string>"
  ],
  "idleTimeoutSeconds": 10,
  "idleMessageMaxSpokenCount": 3,
  "idleMessageResetCountOnUserSpeechEnabled": true,
  "properties": {
    "age": 35,
    "zipCode": "94105",
    "occupation": "Software Engineer"
  }
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.roark.ai/v1/persona",
  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([
    'name' => '<string>',
    'description' => '<string>',
    'secondaryLanguage' => 'EN',
    'understoodLanguages' => [
        
    ],
    'backgroundNoise' => 'NONE',
    'speechPace' => 'NORMAL',
    'speechClarity' => 'CLEAR',
    'hasDisfluencies' => false,
    'baseEmotion' => 'NEUTRAL',
    'intentClarity' => 'CLEAR',
    'confirmationStyle' => 'EXPLICIT',
    'memoryReliability' => 'HIGH',
    'responseTiming' => 'NORMAL',
    'backstoryPrompt' => 'A busy professional calling during lunch break',
    'idleMessages' => [
        '<string>'
    ],
    'idleTimeoutSeconds' => 10,
    'idleMessageMaxSpokenCount' => 3,
    'idleMessageResetCountOnUserSpeechEnabled' => true,
    'properties' => [
        'age' => 35,
        'zipCode' => '94105',
        'occupation' => 'Software Engineer'
    ]
  ]),
  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://api.roark.ai/v1/persona"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"secondaryLanguage\": \"EN\",\n  \"understoodLanguages\": [],\n  \"backgroundNoise\": \"NONE\",\n  \"speechPace\": \"NORMAL\",\n  \"speechClarity\": \"CLEAR\",\n  \"hasDisfluencies\": false,\n  \"baseEmotion\": \"NEUTRAL\",\n  \"intentClarity\": \"CLEAR\",\n  \"confirmationStyle\": \"EXPLICIT\",\n  \"memoryReliability\": \"HIGH\",\n  \"responseTiming\": \"NORMAL\",\n  \"backstoryPrompt\": \"A busy professional calling during lunch break\",\n  \"idleMessages\": [\n    \"<string>\"\n  ],\n  \"idleTimeoutSeconds\": 10,\n  \"idleMessageMaxSpokenCount\": 3,\n  \"idleMessageResetCountOnUserSpeechEnabled\": true,\n  \"properties\": {\n    \"age\": 35,\n    \"zipCode\": \"94105\",\n    \"occupation\": \"Software Engineer\"\n  }\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://api.roark.ai/v1/persona")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"secondaryLanguage\": \"EN\",\n  \"understoodLanguages\": [],\n  \"backgroundNoise\": \"NONE\",\n  \"speechPace\": \"NORMAL\",\n  \"speechClarity\": \"CLEAR\",\n  \"hasDisfluencies\": false,\n  \"baseEmotion\": \"NEUTRAL\",\n  \"intentClarity\": \"CLEAR\",\n  \"confirmationStyle\": \"EXPLICIT\",\n  \"memoryReliability\": \"HIGH\",\n  \"responseTiming\": \"NORMAL\",\n  \"backstoryPrompt\": \"A busy professional calling during lunch break\",\n  \"idleMessages\": [\n    \"<string>\"\n  ],\n  \"idleTimeoutSeconds\": 10,\n  \"idleMessageMaxSpokenCount\": 3,\n  \"idleMessageResetCountOnUserSpeechEnabled\": true,\n  \"properties\": {\n    \"age\": 35,\n    \"zipCode\": \"94105\",\n    \"occupation\": \"Software Engineer\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.roark.ai/v1/persona")

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  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"secondaryLanguage\": \"EN\",\n  \"understoodLanguages\": [],\n  \"backgroundNoise\": \"NONE\",\n  \"speechPace\": \"NORMAL\",\n  \"speechClarity\": \"CLEAR\",\n  \"hasDisfluencies\": false,\n  \"baseEmotion\": \"NEUTRAL\",\n  \"intentClarity\": \"CLEAR\",\n  \"confirmationStyle\": \"EXPLICIT\",\n  \"memoryReliability\": \"HIGH\",\n  \"responseTiming\": \"NORMAL\",\n  \"backstoryPrompt\": \"A busy professional calling during lunch break\",\n  \"idleMessages\": [\n    \"<string>\"\n  ],\n  \"idleTimeoutSeconds\": 10,\n  \"idleMessageMaxSpokenCount\": 3,\n  \"idleMessageResetCountOnUserSpeechEnabled\": true,\n  \"properties\": {\n    \"age\": 35,\n    \"zipCode\": \"94105\",\n    \"occupation\": \"Software Engineer\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "language": "EN",
    "understoodLanguages": [
      "EN"
    ],
    "accent": "US",
    "gender": "MALE",
    "backgroundNoise": "NONE",
    "speechPace": "NORMAL",
    "speechClarity": "CLEAR",
    "hasDisfluencies": false,
    "baseEmotion": "NEUTRAL",
    "intentClarity": "CLEAR",
    "confirmationStyle": "EXPLICIT",
    "memoryReliability": "HIGH",
    "responseTiming": "NORMAL",
    "idleMessages": [
      "<string>"
    ],
    "idleTimeoutSeconds": 10,
    "idleMessageMaxSpokenCount": 3,
    "idleMessageResetCountOnUserSpeechEnabled": true,
    "properties": {
      "age": 35,
      "zipCode": "94105",
      "occupation": "Software Engineer"
    },
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "description": "<string>",
    "secondaryLanguage": "EN",
    "backstoryPrompt": "A busy professional calling during lunch break"
  }
}

{
  "type": "validation",
  "code": "invalid_parameter",
  "message": "The request was invalid",
  "param": "email"
}

{
  "type": "authentication",
  "code": "unauthorized",
  "message": "Authentication required"
}

{
  "type": "internal",
  "code": "internal_error",
  "message": "Internal server error"
}

Authorizations

Authorization

string

header

required

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

Body

application/json

Input for creating a new persona

name

string

required

The name the agent will identify as during conversations

language

enum<string>

required

Primary language ISO 639-1 code for the persona

Available options:

EN,

ES,

DE,

HI,

FR,

NL,

AR,

EL,

IT,

ID,

TH,

JA,

TL,

MS,

ZH,

TR,

PT,

HE

accent

enum<string>

required

Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants

Available options:

US,

US_X_SOUTH,

GB,

ES,

DE,

IN,

FR,

NL,

SA,

GR,

AU,

IT,

ID,

TH,

JP,

NZ,

PH,

SG,

MY,

HK,

TR,

PT,

IL

gender

enum<string>

required

Gender of the persona

Available options:

MALE,

FEMALE

description

string | null

Human-readable description of the persona

secondaryLanguage

enum<string> | null

Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)

Available options:

EN

understoodLanguages

enum<string>[]

Languages the persona can understand. Defaults to the languages the persona speaks.

Minimum array length: 1

Available options:

EN,

ES,

DE,

HI,

FR,

NL,

AR,

EL,

IT,

ID,

TH,

JA,

TL,

MS,

ZH,

TR,

PT,

HE

backgroundNoise

enum<string>

default:NONE

Background noise setting

Available options:

NONE,

AIRPORT,

CHILDREN_PLAYING,

CITY,

COFFEE_SHOP,

DRIVING,

OFFICE,

THUNDERSTORM

speechPace

enum<string>

default:NORMAL

Speech pace of the persona

Available options:

SUPER_SLOW,

SLOW,

NORMAL,

FAST,

SUPER_FAST

speechClarity

enum<string>

default:CLEAR

Speech clarity of the persona

Available options:

CLEAR,

VAGUE,

RAMBLING

hasDisfluencies

boolean

default:false

Whether the persona uses filler words like "um" and "uh"

baseEmotion

enum<string>

default:NEUTRAL

Base emotional state of the persona

Available options:

NEUTRAL,

CHEERFUL,

CONFUSED,

FRUSTRATED,

SKEPTICAL,

RUSHED,

DISTRACTED

intentClarity

enum<string>

default:CLEAR

How clearly the persona expresses their intentions

Available options:

CLEAR,

INDIRECT,

VAGUE

confirmationStyle

enum<string>

default:EXPLICIT

How the persona confirms information

Available options:

EXPLICIT,

VAGUE

memoryReliability

enum<string>

default:HIGH

How reliable the persona's memory is

Available options:

HIGH,

LOW

responseTiming

enum<string>

default:NORMAL

Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED)

Available options:

RELAXED,

NORMAL,

QUICK

backstoryPrompt

string | null

Background story and behavioral patterns for the persona

Example:

"A busy professional calling during lunch break"

idleMessages

string[] | null

Messages the persona will say when the agent goes silent during a call. Defaults to language-appropriate phrases when omitted or sent as null.

idleTimeoutSeconds

integer

default:10

Seconds of silence before the persona sends an idle message

Required range: 5 <= x <= 60

idleMessageMaxSpokenCount

integer

default:3

Maximum number of idle messages the persona will send before giving up

Required range: 1 <= x <= 10

idleMessageResetCountOnUserSpeechEnabled

boolean

default:true

Whether the idle message counter resets when the agent speaks

properties

object

Additional custom properties about the persona

Show child attributes

Example:

{
  "age": 35,
  "zipCode": "94105",
  "occupation": "Software Engineer"
}

Response

The created persona

data

object

required

Show child attributes

JavaScript

import Roark from '@roarkanalytics/sdk';

const client = new Roark({
  bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted
});

const simulationPersona = await client.simulationPersona.create({
  accent: 'US',
  gender: 'MALE',
  language: 'EN',
  name: 'name',
});

console.log(simulationPersona.data);

import os
from roark_analytics import Roark

client = Roark(
    bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted
)
simulation_persona = client.simulation_persona.create(
    accent="US",
    gender="MALE",
    language="EN",
    name="name",
)
print(simulation_persona.data)

curl --request POST \
  --url https://api.roark.ai/v1/persona \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "secondaryLanguage": "EN",
  "understoodLanguages": [],
  "backgroundNoise": "NONE",
  "speechPace": "NORMAL",
  "speechClarity": "CLEAR",
  "hasDisfluencies": false,
  "baseEmotion": "NEUTRAL",
  "intentClarity": "CLEAR",
  "confirmationStyle": "EXPLICIT",
  "memoryReliability": "HIGH",
  "responseTiming": "NORMAL",
  "backstoryPrompt": "A busy professional calling during lunch break",
  "idleMessages": [
    "<string>"
  ],
  "idleTimeoutSeconds": 10,
  "idleMessageMaxSpokenCount": 3,
  "idleMessageResetCountOnUserSpeechEnabled": true,
  "properties": {
    "age": 35,
    "zipCode": "94105",
    "occupation": "Software Engineer"
  }
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.roark.ai/v1/persona",
  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([
    'name' => '<string>',
    'description' => '<string>',
    'secondaryLanguage' => 'EN',
    'understoodLanguages' => [
        
    ],
    'backgroundNoise' => 'NONE',
    'speechPace' => 'NORMAL',
    'speechClarity' => 'CLEAR',
    'hasDisfluencies' => false,
    'baseEmotion' => 'NEUTRAL',
    'intentClarity' => 'CLEAR',
    'confirmationStyle' => 'EXPLICIT',
    'memoryReliability' => 'HIGH',
    'responseTiming' => 'NORMAL',
    'backstoryPrompt' => 'A busy professional calling during lunch break',
    'idleMessages' => [
        '<string>'
    ],
    'idleTimeoutSeconds' => 10,
    'idleMessageMaxSpokenCount' => 3,
    'idleMessageResetCountOnUserSpeechEnabled' => true,
    'properties' => [
        'age' => 35,
        'zipCode' => '94105',
        'occupation' => 'Software Engineer'
    ]
  ]),
  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://api.roark.ai/v1/persona"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"secondaryLanguage\": \"EN\",\n  \"understoodLanguages\": [],\n  \"backgroundNoise\": \"NONE\",\n  \"speechPace\": \"NORMAL\",\n  \"speechClarity\": \"CLEAR\",\n  \"hasDisfluencies\": false,\n  \"baseEmotion\": \"NEUTRAL\",\n  \"intentClarity\": \"CLEAR\",\n  \"confirmationStyle\": \"EXPLICIT\",\n  \"memoryReliability\": \"HIGH\",\n  \"responseTiming\": \"NORMAL\",\n  \"backstoryPrompt\": \"A busy professional calling during lunch break\",\n  \"idleMessages\": [\n    \"<string>\"\n  ],\n  \"idleTimeoutSeconds\": 10,\n  \"idleMessageMaxSpokenCount\": 3,\n  \"idleMessageResetCountOnUserSpeechEnabled\": true,\n  \"properties\": {\n    \"age\": 35,\n    \"zipCode\": \"94105\",\n    \"occupation\": \"Software Engineer\"\n  }\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://api.roark.ai/v1/persona")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"secondaryLanguage\": \"EN\",\n  \"understoodLanguages\": [],\n  \"backgroundNoise\": \"NONE\",\n  \"speechPace\": \"NORMAL\",\n  \"speechClarity\": \"CLEAR\",\n  \"hasDisfluencies\": false,\n  \"baseEmotion\": \"NEUTRAL\",\n  \"intentClarity\": \"CLEAR\",\n  \"confirmationStyle\": \"EXPLICIT\",\n  \"memoryReliability\": \"HIGH\",\n  \"responseTiming\": \"NORMAL\",\n  \"backstoryPrompt\": \"A busy professional calling during lunch break\",\n  \"idleMessages\": [\n    \"<string>\"\n  ],\n  \"idleTimeoutSeconds\": 10,\n  \"idleMessageMaxSpokenCount\": 3,\n  \"idleMessageResetCountOnUserSpeechEnabled\": true,\n  \"properties\": {\n    \"age\": 35,\n    \"zipCode\": \"94105\",\n    \"occupation\": \"Software Engineer\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.roark.ai/v1/persona")

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  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"secondaryLanguage\": \"EN\",\n  \"understoodLanguages\": [],\n  \"backgroundNoise\": \"NONE\",\n  \"speechPace\": \"NORMAL\",\n  \"speechClarity\": \"CLEAR\",\n  \"hasDisfluencies\": false,\n  \"baseEmotion\": \"NEUTRAL\",\n  \"intentClarity\": \"CLEAR\",\n  \"confirmationStyle\": \"EXPLICIT\",\n  \"memoryReliability\": \"HIGH\",\n  \"responseTiming\": \"NORMAL\",\n  \"backstoryPrompt\": \"A busy professional calling during lunch break\",\n  \"idleMessages\": [\n    \"<string>\"\n  ],\n  \"idleTimeoutSeconds\": 10,\n  \"idleMessageMaxSpokenCount\": 3,\n  \"idleMessageResetCountOnUserSpeechEnabled\": true,\n  \"properties\": {\n    \"age\": 35,\n    \"zipCode\": \"94105\",\n    \"occupation\": \"Software Engineer\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "language": "EN",
    "understoodLanguages": [
      "EN"
    ],
    "accent": "US",
    "gender": "MALE",
    "backgroundNoise": "NONE",
    "speechPace": "NORMAL",
    "speechClarity": "CLEAR",
    "hasDisfluencies": false,
    "baseEmotion": "NEUTRAL",
    "intentClarity": "CLEAR",
    "confirmationStyle": "EXPLICIT",
    "memoryReliability": "HIGH",
    "responseTiming": "NORMAL",
    "idleMessages": [
      "<string>"
    ],
    "idleTimeoutSeconds": 10,
    "idleMessageMaxSpokenCount": 3,
    "idleMessageResetCountOnUserSpeechEnabled": true,
    "properties": {
      "age": 35,
      "zipCode": "94105",
      "occupation": "Software Engineer"
    },
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "description": "<string>",
    "secondaryLanguage": "EN",
    "backstoryPrompt": "A busy professional calling during lunch break"
  }
}

{
  "type": "validation",
  "code": "invalid_parameter",
  "message": "The request was invalid",
  "param": "email"
}

{
  "type": "authentication",
  "code": "unauthorized",
  "message": "Authentication required"
}

{
  "type": "internal",
  "code": "internal_error",
  "message": "Internal server error"
}

API Reference

Health

Agent Endpoint

Agent

Call

Chat

Metric

Metric Policy

Metric Collection Job

Simulation Persona

Simulation

Simulation Scenario

Simulation Environment

Simulation Run Plan

Simulation Run Plan Job

Simulation Job

Customer Flow

Customer Flow Edge Case

HTTP Request Definition

Webhook

Issue

Knowledge Base

Create a new persona

Authorizations

Body

Response