> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a customer flow > Creates a customer flow. A SCRIPTED flow carries a step graph and gets one way of running it per path through the graph; an IMPROV flow carries the briefs you send. ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/customer-flow openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Knowledge Base - name: Call Analysis - name: Health paths: /v1/customer-flow: post: tags: - Customer Flow summary: Create a customer flow description: >- Creates a customer flow. A SCRIPTED flow carries a step graph and gets one way of running it per path through the graph; an IMPROV flow carries the briefs you send. operationId: postV1Customer-flow requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCustomerFlowInput' responses: '201': description: The created customer flow content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CustomerFlow' required: - data '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error example: type: validation code: invalid_parameter message: The request was invalid param: email description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit error example: type: rate_limit code: too_many_requests message: Rate limit exceeded description: Too Many Requests '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: |- 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 customerFlow = await client.customerFlow.create({ agentIds: ['7c9e6679-7425-40de-944b-e07fc1f90ae7'], graph: [{ type: 'CUSTOMER_FIRST_MESSAGE' }], title: 'Reschedule an appointment', type: 'SCRIPTED', }); console.log(customerFlow.data); - lang: Python source: |- 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 ) customer_flow = client.customer_flow.create( agent_ids=["7c9e6679-7425-40de-944b-e07fc1f90ae7"], graph=[{ "type": "CUSTOMER_FIRST_MESSAGE" }], title="Reschedule an appointment", type="SCRIPTED", ) print(customer_flow.data) components: schemas: CreateCustomerFlowInput: oneOf: - $ref: '#/components/schemas/CreateScriptedCustomerFlowInput' - $ref: '#/components/schemas/CreateImprovCustomerFlowInput' discriminator: propertyName: type mapping: SCRIPTED: $ref: '#/components/schemas/CreateScriptedCustomerFlowInput' IMPROV: $ref: '#/components/schemas/CreateImprovCustomerFlowInput' description: >- Input for creating a customer flow. SCRIPTED writes the conversation out as a graph of turns; IMPROV gives the simulated customer a brief and lets it improvise. CustomerFlow: oneOf: - $ref: '#/components/schemas/ScriptedCustomerFlow' - $ref: '#/components/schemas/ImprovCustomerFlow' - $ref: '#/components/schemas/VoicemailCustomerFlow' discriminator: propertyName: type mapping: SCRIPTED: $ref: '#/components/schemas/ScriptedCustomerFlow' IMPROV: $ref: '#/components/schemas/ImprovCustomerFlow' VOICEMAIL: $ref: '#/components/schemas/VoicemailCustomerFlow' description: The conversation a simulated customer has with the agent under test. ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message CreateScriptedCustomerFlowInput: type: object properties: type: type: string const: SCRIPTED title: type: string minLength: 1 example: Reschedule an appointment description: type: - string - 'null' agentIds: type: array items: type: string format: uuid minItems: 1 description: Agents this flow exercises. At least one is required. agentExpectations: type: array items: $ref: '#/components/schemas/FlowExpectationInput' branchingMode: type: string enum: - DETERMINISTIC - ADAPTIVE description: >- DETERMINISTIC (the default) runs one variant per path through the graph; ADAPTIVE collapses the paths into one call the simulated customer adapts across. graph: type: array items: $ref: '#/components/schemas/FlowStep' minItems: 1 description: >- The conversation, as a graph of steps. At most 100 steps across at most 25 paths. The variants come from the graph: one per path, so they are not sent here. required: - type - title - agentIds - graph title: Scripted example: type: SCRIPTED title: Reschedule an appointment agentIds: - 7c9e6679-7425-40de-944b-e07fc1f90ae7 graph: - type: CUSTOMER_FIRST_MESSAGE content: Hi, I need to move my appointment. steps: - type: AGENT_TURN content: Offers alternative times steps: - type: CUSTOMER_TURN content: Takes the first slot - type: CUSTOMER_TURN content: Asks for later in the week CreateImprovCustomerFlowInput: type: object properties: type: type: string const: IMPROV title: type: string minLength: 1 example: Reschedule an appointment description: type: - string - 'null' agentIds: type: array items: type: string format: uuid minItems: 1 description: Agents this flow exercises. At least one is required. agentExpectations: type: array items: $ref: '#/components/schemas/FlowExpectationInput' happyPath: $ref: '#/components/schemas/FlowHappyPathInput' edgeCases: type: array items: $ref: '#/components/schemas/FlowEdgeCaseInput' description: >- Other ways of running it, each inheriting from the happy path what it does not name. required: - type - title - agentIds - happyPath title: Improv example: type: IMPROV title: Billing questions agentIds: - 7c9e6679-7425-40de-944b-e07fc1f90ae7 agentExpectations: - prompt: The agent never states an amount it has not verified happyPath: title: Asks about a charge personaOverrideId: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 environmentId: d1f5c19d-0000-4000-8000-000000000001 prompt: You want to understand a charge on your latest invoice. edgeCases: - title: Disputes the charge prompt: You are certain the charge is wrong. ScriptedCustomerFlow: type: object properties: id: type: string format: uuid title: type: string minLength: 1 description: type: - string - 'null' source: type: string enum: - SYSTEM - CUSTOM default: CUSTOM createdAt: type: string description: Creation timestamp in ISO 8601 format updatedAt: type: string description: Last update timestamp in ISO 8601 format agents: type: array items: type: object properties: id: type: string format: uuid description: Unique identifier of the agent name: type: string description: Name of the agent description: type: - string - 'null' description: Description of the agent customId: type: - string - 'null' description: Custom identifier for the agent createdAt: type: string description: Creation timestamp in ISO 8601 format updatedAt: type: string description: Last update timestamp in ISO 8601 format required: - id - name - description - customId - createdAt - updatedAt description: The agents this flow is run against. agentExpectations: type: array items: $ref: '#/components/schemas/FlowExpectation' type: type: string const: SCRIPTED branchingMode: type: string enum: - DETERMINISTIC - ADAPTIVE description: >- DETERMINISTIC runs one variant per path through the graph. ADAPTIVE collapses the paths into a single variant the simulated customer adapts across. graph: type: array items: $ref: '#/components/schemas/FlowStep' description: >- The conversation, as a graph of steps. Present on a single flow; omitted from the list, where reading it would mean walking the project step graph once per row. happyPath: oneOf: - $ref: '#/components/schemas/ScriptedFlowHappyPath' - type: 'null' description: >- The way this flow is meant to go. Null when the flow has none, and then every way is an edge case. edgeCases: type: array items: $ref: '#/components/schemas/ScriptedFlowVariant' description: Every other way of running this flow. required: - id - title - source - createdAt - updatedAt - agents - agentExpectations - type - branchingMode - happyPath - edgeCases title: Scripted description: A flow whose conversation is written out as a graph of turns. ImprovCustomerFlow: type: object properties: id: type: string format: uuid title: type: string minLength: 1 description: type: - string - 'null' source: type: string enum: - SYSTEM - CUSTOM default: CUSTOM createdAt: type: string description: Creation timestamp in ISO 8601 format updatedAt: type: string description: Last update timestamp in ISO 8601 format agents: type: array items: type: object properties: id: type: string format: uuid description: Unique identifier of the agent name: type: string description: Name of the agent description: type: - string - 'null' description: Description of the agent customId: type: - string - 'null' description: Custom identifier for the agent createdAt: type: string description: Creation timestamp in ISO 8601 format updatedAt: type: string description: Last update timestamp in ISO 8601 format required: - id - name - description - customId - createdAt - updatedAt description: The agents this flow is run against. agentExpectations: type: array items: $ref: '#/components/schemas/FlowExpectation' type: type: string const: IMPROV happyPath: oneOf: - $ref: '#/components/schemas/ImprovFlowHappyPath' - type: 'null' description: >- The way this flow is meant to go. Null when the flow has none, and then every way is an edge case. edgeCases: type: array items: $ref: '#/components/schemas/ImprovFlowVariant' description: Every other way of running this flow. required: - id - title - source - createdAt - updatedAt - agents - agentExpectations - type - happyPath - edgeCases title: Improv description: >- A flow whose conversation is not written out: each variant gives the simulated customer a brief and lets it improvise. VoicemailCustomerFlow: type: object properties: id: type: string format: uuid title: type: string minLength: 1 description: type: - string - 'null' source: type: string enum: - SYSTEM - CUSTOM default: CUSTOM createdAt: type: string description: Creation timestamp in ISO 8601 format updatedAt: type: string description: Last update timestamp in ISO 8601 format agents: type: array items: type: object properties: id: type: string format: uuid description: Unique identifier of the agent name: type: string description: Name of the agent description: type: - string - 'null' description: Description of the agent customId: type: - string - 'null' description: Custom identifier for the agent createdAt: type: string description: Creation timestamp in ISO 8601 format updatedAt: type: string description: Last update timestamp in ISO 8601 format required: - id - name - description - customId - createdAt - updatedAt description: The agents this flow is run against. agentExpectations: type: array items: $ref: '#/components/schemas/FlowExpectation' type: type: string const: VOICEMAIL happyPath: oneOf: - $ref: '#/components/schemas/VoicemailFlowHappyPath' - type: 'null' description: >- The way this flow is meant to go. Null when the flow has none, and then every way is an edge case. edgeCases: type: array items: $ref: '#/components/schemas/VoicemailFlowVariant' description: Every other way of running this flow. required: - id - title - source - createdAt - updatedAt - agents - agentExpectations - type - happyPath - edgeCases title: Voicemail description: A flow that leaves a voicemail. Curated by Roark, read-only. FlowExpectationInput: type: object properties: prompt: type: string minLength: 1 description: What the agent under test is graded against. example: The agent confirmed the new appointment time back to the customer required: - prompt FlowStep: oneOf: - type: object properties: nodeId: type: string format: uuid ref: type: string minLength: 1 maxLength: 64 steps: type: array items: $ref: '#/components/schemas/FlowStep' mergeIntoNodeIds: type: array items: type: string minLength: 1 type: type: string const: AGENT_TURN content: type: - string - 'null' required: - type additionalProperties: false - type: object properties: nodeId: type: string format: uuid ref: type: string minLength: 1 maxLength: 64 steps: type: array items: $ref: '#/components/schemas/FlowStep' mergeIntoNodeIds: type: array items: type: string minLength: 1 type: type: string const: CUSTOMER_TURN content: type: - string - 'null' required: - type additionalProperties: false - type: object properties: nodeId: type: string format: uuid ref: type: string minLength: 1 maxLength: 64 steps: type: array items: $ref: '#/components/schemas/FlowStep' mergeIntoNodeIds: type: array items: type: string minLength: 1 type: type: string const: CUSTOMER_FIRST_MESSAGE content: type: - string - 'null' required: - type additionalProperties: false - type: object properties: nodeId: type: string format: uuid ref: type: string minLength: 1 maxLength: 64 steps: type: array items: $ref: '#/components/schemas/FlowStep' mergeIntoNodeIds: type: array items: type: string minLength: 1 type: type: string const: CUSTOMER_SILENCE silenceDurationSeconds: type: - integer - 'null' exclusiveMinimum: 0 required: - type additionalProperties: false - type: object properties: nodeId: type: string format: uuid ref: type: string minLength: 1 maxLength: 64 steps: type: array items: $ref: '#/components/schemas/FlowStep' mergeIntoNodeIds: type: array items: type: string minLength: 1 type: type: string const: CUSTOMER_DTMF dtmfDigits: type: - string - 'null' required: - type additionalProperties: false - type: object properties: nodeId: type: string format: uuid ref: type: string minLength: 1 maxLength: 64 steps: type: array items: $ref: '#/components/schemas/FlowStep' mergeIntoNodeIds: type: array items: type: string minLength: 1 type: type: string const: VOICEMAIL required: - type additionalProperties: false - type: object properties: nodeId: type: string format: uuid ref: type: string minLength: 1 maxLength: 64 steps: type: array items: $ref: '#/components/schemas/FlowStep' mergeIntoNodeIds: type: array items: type: string minLength: 1 type: type: string const: SCENARIO_LINK linkedCustomerFlowId: type: - string - 'null' format: uuid linkedCustomerFlowVariantId: type: - string - 'null' format: uuid required: - type additionalProperties: false description: >- One step in a scripted flow's conversation. `nodeId` is the identity contract: include it to update the existing step, omit it to create a new one. A step continues into `steps` (more than one child is a branch point) and/or `mergeIntoNodeIds`, which names steps elsewhere in the same request that this step rejoins. Branches that come back together are represented that way rather than by repeating the shared step, so reading a flow, editing it and writing it back preserves it exactly. A merge target is named by its `nodeId` when it already exists, or by `ref` when it is being created in the same request. `ref` is a label you choose, it is request-local, and it is never stored or returned. Put the shared step inline under the first branch that reaches it and point the others at it: a top-level step is a root wired straight from the start of the flow, so a merge target parked there would also be reachable directly. FlowHappyPathInput: type: object properties: title: type: string minLength: 1 environmentId: type: string format: uuid description: >- The conditions this flow runs under. Edge cases inherit them unless they name their own. prompt: type: - string - 'null' precededByCustomerFlowId: type: - string - 'null' format: uuid precededByCustomerFlowVariantId: type: - string - 'null' format: uuid personaOverrideId: type: string format: uuid description: >- The persona this flow runs as. Edge cases inherit it unless they name their own. required: - title - environmentId - personaOverrideId description: The way this flow is meant to go. FlowEdgeCaseInput: type: object properties: title: type: string minLength: 1 environmentId: type: - string - 'null' format: uuid prompt: type: - string - 'null' precededByCustomerFlowId: type: - string - 'null' format: uuid precededByCustomerFlowVariantId: type: - string - 'null' format: uuid personaOverrideId: type: - string - 'null' format: uuid description: The persona this runs as. Omit to inherit the happy path's. required: - title FlowExpectation: type: object properties: id: type: string format: uuid prompt: type: string description: What the agent under test is graded against. required: - id - prompt description: One thing the agent under test is graded against. ScriptedFlowHappyPath: allOf: - $ref: '#/components/schemas/ScriptedFlowVariant' title: Scripted description: >- One path through a scripted flow. The path engine owns which paths exist, so editing the graph is what creates and removes these. ScriptedFlowVariant: type: object properties: id: type: string format: uuid title: type: string minLength: 1 precededByCustomerFlowId: type: - string - 'null' format: uuid precededByCustomerFlowVariantId: type: - string - 'null' format: uuid isGenerated: type: boolean default: false createdAt: type: string description: Creation timestamp in ISO 8601 format updatedAt: type: string description: Last update timestamp in ISO 8601 format personaOverride: type: - object - 'null' properties: id: type: string format: uuid description: Unique identifier of the persona name: type: string description: The name the agent will identify as during conversations description: type: - string - 'null' description: Human-readable description of the persona language: type: string enum: - EN - ES - DE - HI - FR - NL - AR - EL - IT - ID - TH - JA - TL - MS - ZH - TR - PT - HE description: Primary language ISO 639-1 code for the persona secondaryLanguage: type: - string - 'null' enum: - EN description: >- Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish) understoodLanguages: type: array items: type: string enum: - EN - ES - DE - HI - FR - NL - AR - EL - IT - ID - TH - JA - TL - MS - ZH - TR - PT - HE minItems: 1 description: >- Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support. accent: type: string enum: - 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 description: >- Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants gender: type: string enum: - MALE - FEMALE description: Gender of the persona backgroundNoise: type: string enum: - NONE - AIRPORT - CHILDREN_PLAYING - CITY - COFFEE_SHOP - DRIVING - OFFICE - THUNDERSTORM default: NONE description: Background noise setting speechPace: type: string enum: - SUPER_SLOW - SLOW - NORMAL - FAST - SUPER_FAST default: NORMAL description: Speech pace of the persona speechClarity: type: string enum: - CLEAR - VAGUE - RAMBLING default: CLEAR description: Speech clarity of the persona hasDisfluencies: type: boolean default: false description: Whether the persona uses filler words like "um" and "uh" baseEmotion: type: string enum: - NEUTRAL - CHEERFUL - CONFUSED - FRUSTRATED - SKEPTICAL - RUSHED - DISTRACTED default: NEUTRAL description: Base emotional state of the persona intentClarity: type: string enum: - CLEAR - INDIRECT - VAGUE default: CLEAR description: How clearly the persona expresses their intentions confirmationStyle: type: string enum: - EXPLICIT - VAGUE default: EXPLICIT description: How the persona confirms information memoryReliability: type: string enum: - HIGH - LOW default: HIGH description: How reliable the persona's memory is responseTiming: type: string enum: - RELAXED - NORMAL - QUICK default: NORMAL description: >- Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) backstoryPrompt: type: - string - 'null' description: Background story and behavioral patterns for the persona example: A busy professional calling during lunch break idleMessages: type: - array - 'null' items: type: string description: >- Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. idleTimeoutSeconds: type: integer minimum: 5 maximum: 60 default: 10 description: Seconds of silence before the persona sends an idle message idleMessageMaxSpokenCount: type: integer minimum: 1 maximum: 10 default: 3 description: >- Maximum number of idle messages the persona will send before giving up idleMessageResetCountOnUserSpeechEnabled: type: boolean default: true description: Whether the idle message counter resets when the agent speaks properties: type: object additionalProperties: path: /v1/integrations/livekit-sdk/chunk-upload-url default: {} description: Additional custom properties about the persona example: age: 35 zipCode: '94105' occupation: Software Engineer createdAt: type: string description: Creation timestamp updatedAt: type: string description: Last update timestamp required: - id - name - language - understoodLanguages - accent - gender - backgroundNoise - speechPace - speechClarity - hasDisfluencies - baseEmotion - intentClarity - confirmationStyle - memoryReliability - responseTiming - idleMessages - idleTimeoutSeconds - idleMessageMaxSpokenCount - idleMessageResetCountOnUserSpeechEnabled - properties - createdAt - updatedAt description: >- The persona this runs as instead of the happy path's. Null means it inherits. environment: oneOf: - $ref: '#/components/schemas/EnvironmentResponse' - type: 'null' description: >- The conditions this runs under. Null means it inherits the happy path's. additionalExpectations: type: array items: $ref: '#/components/schemas/FlowExpectation' description: Graded on top of the flow's own expectations, for this variant only. type: type: string const: SCRIPTED steps: type: array items: $ref: '#/components/schemas/FlowStep' description: >- The one path through the graph this variant runs, in order. Linear by construction, so these steps never nest. required: - id - title - precededByCustomerFlowId - precededByCustomerFlowVariantId - isGenerated - createdAt - updatedAt - personaOverride - environment - additionalExpectations - type - steps title: Scripted description: >- One path through a scripted flow. The path engine owns which paths exist, so editing the graph is what creates and removes these. ImprovFlowHappyPath: allOf: - $ref: '#/components/schemas/ImprovFlowVariant' title: Improv description: One brief to run an improv flow with. ImprovFlowVariant: type: object properties: id: type: string format: uuid title: type: string minLength: 1 precededByCustomerFlowId: type: - string - 'null' format: uuid precededByCustomerFlowVariantId: type: - string - 'null' format: uuid isGenerated: type: boolean default: false createdAt: type: string description: Creation timestamp in ISO 8601 format updatedAt: type: string description: Last update timestamp in ISO 8601 format personaOverride: type: - object - 'null' properties: id: type: string format: uuid description: Unique identifier of the persona name: type: string description: The name the agent will identify as during conversations description: type: - string - 'null' description: Human-readable description of the persona language: type: string enum: - EN - ES - DE - HI - FR - NL - AR - EL - IT - ID - TH - JA - TL - MS - ZH - TR - PT - HE description: Primary language ISO 639-1 code for the persona secondaryLanguage: type: - string - 'null' enum: - EN description: >- Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish) understoodLanguages: type: array items: type: string enum: - EN - ES - DE - HI - FR - NL - AR - EL - IT - ID - TH - JA - TL - MS - ZH - TR - PT - HE minItems: 1 description: >- Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support. accent: type: string enum: - 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 description: >- Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants gender: type: string enum: - MALE - FEMALE description: Gender of the persona backgroundNoise: type: string enum: - NONE - AIRPORT - CHILDREN_PLAYING - CITY - COFFEE_SHOP - DRIVING - OFFICE - THUNDERSTORM default: NONE description: Background noise setting speechPace: type: string enum: - SUPER_SLOW - SLOW - NORMAL - FAST - SUPER_FAST default: NORMAL description: Speech pace of the persona speechClarity: type: string enum: - CLEAR - VAGUE - RAMBLING default: CLEAR description: Speech clarity of the persona hasDisfluencies: type: boolean default: false description: Whether the persona uses filler words like "um" and "uh" baseEmotion: type: string enum: - NEUTRAL - CHEERFUL - CONFUSED - FRUSTRATED - SKEPTICAL - RUSHED - DISTRACTED default: NEUTRAL description: Base emotional state of the persona intentClarity: type: string enum: - CLEAR - INDIRECT - VAGUE default: CLEAR description: How clearly the persona expresses their intentions confirmationStyle: type: string enum: - EXPLICIT - VAGUE default: EXPLICIT description: How the persona confirms information memoryReliability: type: string enum: - HIGH - LOW default: HIGH description: How reliable the persona's memory is responseTiming: type: string enum: - RELAXED - NORMAL - QUICK default: NORMAL description: >- Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) backstoryPrompt: type: - string - 'null' description: Background story and behavioral patterns for the persona example: A busy professional calling during lunch break idleMessages: type: - array - 'null' items: type: string description: >- Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. idleTimeoutSeconds: type: integer minimum: 5 maximum: 60 default: 10 description: Seconds of silence before the persona sends an idle message idleMessageMaxSpokenCount: type: integer minimum: 1 maximum: 10 default: 3 description: >- Maximum number of idle messages the persona will send before giving up idleMessageResetCountOnUserSpeechEnabled: type: boolean default: true description: Whether the idle message counter resets when the agent speaks properties: type: object additionalProperties: path: /v1/integrations/livekit-sdk/chunk-upload-url default: {} description: Additional custom properties about the persona example: age: 35 zipCode: '94105' occupation: Software Engineer createdAt: type: string description: Creation timestamp updatedAt: type: string description: Last update timestamp required: - id - name - language - understoodLanguages - accent - gender - backgroundNoise - speechPace - speechClarity - hasDisfluencies - baseEmotion - intentClarity - confirmationStyle - memoryReliability - responseTiming - idleMessages - idleTimeoutSeconds - idleMessageMaxSpokenCount - idleMessageResetCountOnUserSpeechEnabled - properties - createdAt - updatedAt description: >- The persona this runs as instead of the happy path's. Null means it inherits. environment: oneOf: - $ref: '#/components/schemas/EnvironmentResponse' - type: 'null' description: >- The conditions this runs under. Null means it inherits the happy path's. additionalExpectations: type: array items: $ref: '#/components/schemas/FlowExpectation' description: Graded on top of the flow's own expectations, for this variant only. type: type: string const: IMPROV prompt: type: - string - 'null' description: The brief the simulated customer improvises from. required: - id - title - precededByCustomerFlowId - precededByCustomerFlowVariantId - isGenerated - createdAt - updatedAt - personaOverride - environment - additionalExpectations - type title: Improv description: One brief to run an improv flow with. VoicemailFlowHappyPath: allOf: - $ref: '#/components/schemas/VoicemailFlowVariant' title: Voicemail description: One voicemail greeting. VoicemailFlowVariant: type: object properties: id: type: string format: uuid title: type: string minLength: 1 precededByCustomerFlowId: type: - string - 'null' format: uuid precededByCustomerFlowVariantId: type: - string - 'null' format: uuid isGenerated: type: boolean default: false createdAt: type: string description: Creation timestamp in ISO 8601 format updatedAt: type: string description: Last update timestamp in ISO 8601 format personaOverride: type: - object - 'null' properties: id: type: string format: uuid description: Unique identifier of the persona name: type: string description: The name the agent will identify as during conversations description: type: - string - 'null' description: Human-readable description of the persona language: type: string enum: - EN - ES - DE - HI - FR - NL - AR - EL - IT - ID - TH - JA - TL - MS - ZH - TR - PT - HE description: Primary language ISO 639-1 code for the persona secondaryLanguage: type: - string - 'null' enum: - EN description: >- Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish) understoodLanguages: type: array items: type: string enum: - EN - ES - DE - HI - FR - NL - AR - EL - IT - ID - TH - JA - TL - MS - ZH - TR - PT - HE minItems: 1 description: >- Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support. accent: type: string enum: - 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 description: >- Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants gender: type: string enum: - MALE - FEMALE description: Gender of the persona backgroundNoise: type: string enum: - NONE - AIRPORT - CHILDREN_PLAYING - CITY - COFFEE_SHOP - DRIVING - OFFICE - THUNDERSTORM default: NONE description: Background noise setting speechPace: type: string enum: - SUPER_SLOW - SLOW - NORMAL - FAST - SUPER_FAST default: NORMAL description: Speech pace of the persona speechClarity: type: string enum: - CLEAR - VAGUE - RAMBLING default: CLEAR description: Speech clarity of the persona hasDisfluencies: type: boolean default: false description: Whether the persona uses filler words like "um" and "uh" baseEmotion: type: string enum: - NEUTRAL - CHEERFUL - CONFUSED - FRUSTRATED - SKEPTICAL - RUSHED - DISTRACTED default: NEUTRAL description: Base emotional state of the persona intentClarity: type: string enum: - CLEAR - INDIRECT - VAGUE default: CLEAR description: How clearly the persona expresses their intentions confirmationStyle: type: string enum: - EXPLICIT - VAGUE default: EXPLICIT description: How the persona confirms information memoryReliability: type: string enum: - HIGH - LOW default: HIGH description: How reliable the persona's memory is responseTiming: type: string enum: - RELAXED - NORMAL - QUICK default: NORMAL description: >- Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) backstoryPrompt: type: - string - 'null' description: Background story and behavioral patterns for the persona example: A busy professional calling during lunch break idleMessages: type: - array - 'null' items: type: string description: >- Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. idleTimeoutSeconds: type: integer minimum: 5 maximum: 60 default: 10 description: Seconds of silence before the persona sends an idle message idleMessageMaxSpokenCount: type: integer minimum: 1 maximum: 10 default: 3 description: >- Maximum number of idle messages the persona will send before giving up idleMessageResetCountOnUserSpeechEnabled: type: boolean default: true description: Whether the idle message counter resets when the agent speaks properties: type: object additionalProperties: path: /v1/integrations/livekit-sdk/chunk-upload-url default: {} description: Additional custom properties about the persona example: age: 35 zipCode: '94105' occupation: Software Engineer createdAt: type: string description: Creation timestamp updatedAt: type: string description: Last update timestamp required: - id - name - language - understoodLanguages - accent - gender - backgroundNoise - speechPace - speechClarity - hasDisfluencies - baseEmotion - intentClarity - confirmationStyle - memoryReliability - responseTiming - idleMessages - idleTimeoutSeconds - idleMessageMaxSpokenCount - idleMessageResetCountOnUserSpeechEnabled - properties - createdAt - updatedAt description: >- The persona this runs as instead of the happy path's. Null means it inherits. environment: oneOf: - $ref: '#/components/schemas/EnvironmentResponse' - type: 'null' description: >- The conditions this runs under. Null means it inherits the happy path's. additionalExpectations: type: array items: $ref: '#/components/schemas/FlowExpectation' description: Graded on top of the flow's own expectations, for this variant only. type: type: string const: VOICEMAIL required: - id - title - precededByCustomerFlowId - precededByCustomerFlowVariantId - isGenerated - createdAt - updatedAt - personaOverride - environment - additionalExpectations - type title: Voicemail description: One voicemail greeting. EnvironmentResponse: type: object properties: id: type: string format: uuid name: type: string minLength: 1 description: type: - string - 'null' backgroundNoise: type: string enum: - NONE - AIRPORT - CHILDREN_PLAYING - CITY - COFFEE_SHOP - DRIVING - OFFICE - THUNDERSTORM default: NONE createdAt: type: string description: Creation timestamp in ISO 8601 format updatedAt: type: string description: Last update timestamp in ISO 8601 format required: - id - name - backgroundNoise - createdAt - updatedAt description: >- A simulation environment: the ambient conditions a customer flow variant runs under. The list includes both your own and the ones Roark curates for every project. securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````