← Files vox.aiARCHIVED FILE
references/tool-schemas/save_agent.json
135 KB · Nov 7, 2026 · 06:13 UTC
{
"name": "save_agent",
"inputSchema": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"create",
"update"
]
},
"payload": {
"type": "object"
},
"agent_id": {
"type": "string",
"format": "uuid",
"description": "Agent UUID returned as `agent_id`.",
"title": "Agent Id"
},
"context_receipt": {
"type": "string",
"minLength": 43,
"maxLength": 128,
"description": "No longer used: accepted for compatibility and ignored. It is never validated and never sent to the product API, so omit it. The CAS revision in payload.expected_head_revision is always required and a stale revision is rejected by the product API (409)."
}
},
"required": [
"mode",
"payload"
],
"additionalProperties": false,
"oneOf": [
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"const": "create"
},
"payload": {
"$ref": "#/$defs/CreateAgentRequest"
},
"context_receipt": {
"type": "string",
"minLength": 43,
"maxLength": 128,
"description": "No longer used: accepted for compatibility and ignored. It is never validated and never sent to the product API, so omit it. The CAS revision in payload.expected_head_revision is always required and a stale revision is rejected by the product API (409)."
}
},
"required": [
"mode",
"payload"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"format": "uuid",
"description": "Agent UUID returned as `agent_id`.",
"title": "Agent Id"
},
"mode": {
"type": "string",
"const": "update"
},
"payload": {
"$ref": "#/$defs/UpdateAgentRequest"
},
"context_receipt": {
"type": "string",
"minLength": 43,
"maxLength": 128,
"description": "No longer used: accepted for compatibility and ignored. It is never validated and never sent to the product API, so omit it. The CAS revision in payload.expected_head_revision is always required and a stale revision is rejected by the product API (409)."
}
},
"required": [
"agent_id",
"mode",
"payload"
],
"additionalProperties": false
}
],
"$defs": {
"CreateAgentRequest": {
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"title": "Name",
"description": "Agent display name shown in dashboards and list responses."
},
"type": {
"type": "string",
"enum": [
"single_prompt",
"flow"
],
"title": "Type",
"description": "Agent type. `single_prompt` uses `data`; `flow` uses a flow graph provided via `flow` (the legacy `flow_data` is deprecated) — omitting the graph fills a server default.",
"default": "single_prompt"
},
"data": {
"anyOf": [
{
"$ref": "#/$defs/AgentDataCreate"
},
{
"type": "null"
}
],
"description": "Agent configuration payload. Shape is published as `agent-schema/agent-data-create`. Missing or partial data is merged with server defaults before the agent is stored."
},
"flow": {
"description": "The flow graph for a flow agent: `nodes` and `edges`, where each edge carries its branch condition (`ai`, `logic`, or `fallback`). Optional — when omitted, the server creates a default begin→conversation→endCall graph. If you send both `flow` and `flow_data`, `flow` is used and `flow_data` is ignored. The exact shape is published at the `flow-schema/flow-data` schema endpoint.",
"$ref": "#/$defs/FlowInput"
},
"folder_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Folder Id",
"description": "Optional folder to create the agent in. Omit (or null) to create at the organization root."
}
},
"type": "object",
"required": [
"name"
],
"title": "CreateAgentRequest",
"description": "에이전트 생성 요청.\n\nsingle_prompt 는 name만 필수이고 data 미전달 또는 부분 전달 시 서버\n기본값으로 채운다. flow 에이전트는 graph 를 `flow` 필드(`{nodes, edges}`)\n로 작성하며 — deprecated `flow_data` 는 호환용 — graph 미전달 시 서버\n기본 그래프(begin→conversation→endCall) 로 채운다.",
"additionalProperties": false
},
"AgentDataCreate": {
"properties": {
"prompt": {
"$ref": "#/$defs/AgentPrompt",
"description": "Agent prompt settings."
},
"stt": {
"$ref": "#/$defs/AgentSTT",
"description": "Speech-to-text settings."
},
"llm": {
"$ref": "#/$defs/AgentLLM",
"description": "Large language model settings."
},
"voice": {
"$ref": "#/$defs/AgentVoice",
"description": "Text-to-speech voice settings."
},
"speech": {
"$ref": "#/$defs/AgentSpeech",
"description": "Agent speech behavior settings."
},
"callSettings": {
"$ref": "#/$defs/AgentCallSettings",
"description": "Agent call behavior settings. Kept camelCase for compatibility."
},
"chatSettings": {
"$ref": "#/$defs/AgentChatSettings",
"description": "Native Chat session lifecycle settings. Kept camelCase for compatibility."
},
"postCall": {
"$ref": "#/$defs/AgentPostCall",
"description": "Post-call extraction and action settings. Kept camelCase."
},
"security": {
"$ref": "#/$defs/AgentSecurity",
"description": "Agent security and privacy settings."
},
"memory": {
"$ref": "#/$defs/AgentMemory",
"description": "Agent customer-memory settings."
},
"webhookSettings": {
"$ref": "#/$defs/AgentWebhookSettings",
"description": "Agent webhook settings. Kept camelCase for compatibility."
},
"knowledge": {
"$ref": "#/$defs/AgentKnowledge",
"description": "Agent knowledge-base settings."
},
"takeoverTranscription": {
"type": "boolean",
"title": "Takeovertranscription",
"description": "Enables real-time captions and durable transcription for the recorded human takeover segment. Set to false to opt out. Defaults to true.",
"default": true
},
"presetDynamicVariables": {
"additionalProperties": {
"type": "string"
},
"type": "object",
"title": "Preset dynamic variables",
"description": "Preset dynamic variables available to the agent."
},
"toolIds": {
"items": {
"type": "string",
"format": "uuid"
},
"type": "array",
"title": "Tool IDs",
"description": "Custom tool UUIDs returned by `GET /v3/tools` and connected to the agent."
},
"builtInTools": {
"items": {
"oneOf": [
{
"$ref": "#/$defs/EndCallTool"
},
{
"$ref": "#/$defs/TransferCallTool"
},
{
"$ref": "#/$defs/TransferAgentTool"
},
{
"$ref": "#/$defs/SendSmsTool"
},
{
"$ref": "#/$defs/SendDtmfTool"
},
{
"$ref": "#/$defs/SearchAddressTool"
},
{
"$ref": "#/$defs/ExtractVariablesTool"
}
]
},
"type": "array",
"title": "Built-in tools",
"description": "Built-in tools connected to the agent."
},
"manuals": {
"additionalProperties": {
"$ref": "#/$defs/PublicManualValue-Input"
},
"type": "object",
"title": "Manuals",
"description": "Agent-owned manual values keyed by canonical manual UUID."
}
},
"type": "object",
"title": "AgentDataCreate",
"description": "Agent configuration accepted by create-agent requests.\n\nOmitted sub-schemas are filled from server defaults. Send complete\nsub-schemas when overriding defaults.",
"additionalProperties": false
},
"AgentPrompt": {
"properties": {
"prompt": {
"type": "string",
"title": "Prompt",
"description": "System prompt for the agent.",
"default": ""
},
"firstLine": {
"type": "string",
"title": "Firstline",
"description": "Static first line spoken when `firstLineType=aiFirstStatic`.",
"default": ""
},
"firstLineType": {
"type": "string",
"enum": [
"userFirst",
"aiFirstDynamic",
"aiFirstStatic"
],
"title": "Firstlinetype",
"description": "First-turn mode for single-prompt agents. `userFirst` waits for the user, `aiFirstDynamic` lets the agent generate the first line, and `aiFirstStatic` speaks `firstLine`.",
"default": "aiFirstDynamic"
},
"pauseBeforeSpeakingSeconds": {
"type": "number",
"maximum": 5.0,
"minimum": 0.0,
"title": "Pausebeforespeakingseconds",
"default": 0.0,
"description": "Delay in seconds before the agent speaks first."
},
"isFirstMessageInterruptible": {
"type": "boolean",
"title": "Isfirstmessageinterruptible",
"default": true,
"description": "Whether the user may interrupt the first agent message."
}
},
"type": "object",
"title": "AgentPrompt",
"description": "Registry: voxai://agent-schema/prompt/v1",
"additionalProperties": false
},
"AgentSTT": {
"properties": {
"languages": {
"items": {
"type": "string"
},
"type": "array",
"minItems": 1,
"title": "Languages",
"description": "Speech recognition language codes. Use base ISO 639-1 codes such as 'ko', 'en', or 'ja'. Region tags such as 'ko-KR' are accepted for compatibility and normalized to their base code before storage."
},
"speed": {
"anyOf": [
{
"type": "string",
"enum": [
"low",
"medium",
"high"
]
},
{
"type": "null"
}
],
"title": "Speed",
"default": "high",
"description": "Voice speed or speech-to-text speed setting. For voices, use `GET /v3/models/voices` capabilities as the allowed range."
}
},
"type": "object",
"title": "AgentSTT",
"description": "Registry: voxai://agent-schema/stt/v2",
"additionalProperties": false
},
"AgentLLM": {
"properties": {
"model": {
"type": "string",
"title": "Model",
"description": "LLM model identifier. Use a `model` value returned by `GET /v3/models/llms`."
},
"temperature": {
"anyOf": [
{
"type": "number",
"maximum": 2.0,
"minimum": 0.0
},
{
"type": "null"
}
],
"title": "Temperature",
"description": "Model or voice sampling temperature. Use `GET /v3/models/llms` or `GET /v3/models/voices` capabilities as the allowed range."
},
"reasoningEffort": {
"anyOf": [
{
"type": "string",
"enum": [
"none",
"minimal",
"low",
"medium",
"high"
]
},
{
"type": "null"
}
],
"title": "Reasoningeffort",
"description": "Reasoning effort override. Null clears the override."
},
"thinkingBudget": {
"anyOf": [
{
"type": "integer",
"minimum": 0.0
},
{
"type": "null"
}
],
"title": "Thinkingbudget",
"description": "Reasoning token budget. Null clears the override."
}
},
"type": "object",
"required": [
"model"
],
"title": "AgentLLM",
"description": "Registry: voxai://agent-schema/llm/v2",
"additionalProperties": false
},
"AgentVoice": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Voice ID. Use an `id` returned by `GET /v3/models/voices`."
},
"provider": {
"type": "string",
"title": "Provider",
"description": "TTS provider returned by `GET /v3/models/voices`."
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model",
"description": "TTS model override. For `elevenlabs` voices, use a `model` returned for that voice by `GET /v3/models/voices`; other values are rejected with `VOICE_NOT_FOUND`. New ElevenLabs selections default to eleven_v4_turbo when model is omitted or empty. Flash v2.5 can only be retained on the same existing voice. In PATCH, omission preserves the stored model when provider and voice ID are unchanged; null clears the override."
},
"speed": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Speed",
"description": "Voice speed. Per-voice min/max ranges are returned by `GET /v3/models/voices` in `capabilities.speed`.",
"default": 1.0
},
"volume": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Volume",
"default": 1.0,
"description": "Voice playback volume."
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Language",
"description": "Language code or locale supported by the provider."
},
"temperature": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Temperature",
"description": "Voice temperature. Per-voice min/max ranges are returned by `GET /v3/models/voices` in `capabilities.temperature`; out-of-range values are rejected.",
"default": 0.9
}
},
"type": "object",
"required": [
"id",
"provider"
],
"title": "AgentVoice",
"description": "Registry: voxai://agent-schema/voice/v1",
"additionalProperties": false
},
"AgentSpeech": {
"properties": {
"responsiveness": {
"type": "number",
"maximum": 1.0,
"minimum": 0.0,
"title": "Responsiveness",
"default": 1.0,
"description": "How quickly the agent should respond after user speech."
},
"boostedKeywords": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Boostedkeywords",
"description": "Words or phrases to bias speech recognition toward."
},
"isAllowInterruption": {
"type": "boolean",
"title": "Isallowinterruption",
"default": true,
"description": "Whether the user may interrupt agent speech."
},
"isAllowTurnDetection": {
"type": "boolean",
"title": "Isallowturndetection",
"default": true,
"description": "Whether turn detection decides when the user has finished speaking."
},
"vadMinSilenceDuration": {
"type": "number",
"minimum": 0.0,
"title": "Vadminsilenceduration",
"default": 0.5,
"description": "Minimum silence in seconds before user speech is treated as finished."
}
},
"type": "object",
"title": "AgentSpeech",
"description": "Registry: voxai://agent-schema/speech/v1.",
"additionalProperties": false
},
"AgentCallSettings": {
"properties": {
"backgroundMusic": {
"type": "string",
"enum": [
"none",
"cafe",
"office",
"call_center",
"library",
"dial_tone"
],
"title": "Backgroundmusic",
"default": "none",
"description": "Background music preset for calls, or null when disabled."
},
"backgroundMusicVolume": {
"type": "number",
"maximum": 1.0,
"minimum": 0.0,
"title": "Backgroundmusicvolume",
"default": 0.5,
"description": "Background music volume."
},
"noiseCancellation": {
"type": "string",
"enum": [
"none",
"nc",
"bvc"
],
"title": "Noisecancellation",
"default": "bvc",
"description": "Noise cancellation setting for calls."
},
"activationThreshold": {
"type": "number",
"maximum": 1.0,
"minimum": 0.0,
"title": "Activationthreshold",
"default": 0.55,
"description": "Audio activation threshold used to detect speech."
},
"callTimeoutInSeconds": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Calltimeoutinseconds",
"default": 900,
"description": "Maximum call duration in seconds before timeout handling."
},
"silenceCallTimeoutInSeconds": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Silencecalltimeoutinseconds",
"default": 30,
"description": "Maximum silence duration in seconds before timeout handling."
},
"silenceReminderTimeoutInSeconds": {
"anyOf": [
{
"type": "integer",
"maximum": 300.0,
"minimum": 10.0
},
{
"type": "null"
}
],
"title": "Silenceremindertimeoutinseconds",
"description": "Seconds to wait after the agent's last audio before each silence reminder (10-300). Must be shorter than silenceCallTimeoutInSeconds. null or omitted keeps the legacy cadence (10 seconds, then 3 seconds longer per consecutive silence, up to 25 seconds)."
},
"silenceReminderMaxCount": {
"anyOf": [
{
"type": "integer",
"maximum": 10.0,
"minimum": 0.0
},
{
"type": "null"
}
],
"title": "Silenceremindermaxcount",
"description": "Maximum silence reminders per consecutive-silence segment (0-10). 0 turns reminders off; the call-level silence timeout still ends the call. null or omitted keeps the legacy behavior of no count limit."
},
"ringDurationInSeconds": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Ringdurationinseconds",
"default": 30,
"description": "Maximum ringing duration in seconds before the call is considered unanswered."
},
"dtmfInterruptible": {
"type": "boolean",
"title": "Dtmfinterruptible",
"default": false,
"description": "Whether the first accepted digit of a DTMF batch may immediately interrupt current agent speech. Digit batching and reply admission remain unchanged."
},
"dtmfTerminationEnabled": {
"type": "boolean",
"title": "Dtmfterminationenabled",
"default": false,
"description": "Whether DTMF keypress termination is enabled."
},
"dtmfTerminationKey": {
"type": "string",
"enum": [
"0",
"1",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9",
"#",
"*"
],
"title": "Dtmfterminationkey",
"default": "#",
"description": "DTMF key that terminates the call when DTMF termination is enabled."
},
"dtmfTimeoutSeconds": {
"type": "integer",
"exclusiveMinimum": 0.0,
"title": "Dtmftimeoutseconds",
"default": 3,
"description": "Seconds to wait for DTMF input before timeout handling."
},
"callScreening": {
"anyOf": [
{
"$ref": "#/$defs/AgentCallScreening"
},
{
"type": "null"
}
],
"description": "Response configuration used when an outbound call screener is detected."
}
},
"type": "object",
"title": "AgentCallSettings",
"description": "Registry: voxai://agent-schema/call-settings/v1.",
"additionalProperties": false
},
"AgentCallScreening": {
"allOf": [
{
"if": {
"properties": {
"promptType": {
"type": "string",
"const": "static"
}
},
"required": [
"promptType"
]
},
"then": {
"properties": {
"staticSentence": {
"type": "string",
"minLength": 1,
"pattern": "\\S"
}
},
"required": [
"staticSentence"
]
}
},
{
"if": {
"properties": {
"promptType": {
"type": "string",
"const": "dynamic"
}
},
"required": [
"promptType"
]
},
"then": {
"properties": {
"prompt": {
"type": "string",
"minLength": 1,
"pattern": "\\S"
}
},
"required": [
"prompt"
]
}
}
],
"properties": {
"promptType": {
"type": "string",
"enum": [
"static",
"dynamic"
],
"title": "Prompttype"
},
"staticSentence": {
"anyOf": [
{
"type": "string",
"maxLength": 300
},
{
"type": "null"
}
],
"title": "Staticsentence"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt",
"description": "Agent prompt settings."
},
"endCallAfterResponse": {
"type": "boolean",
"title": "Endcallafterresponse",
"description": "End the call after the configured screening response finishes playing.",
"default": false
}
},
"additionalProperties": false,
"type": "object",
"required": [
"promptType"
],
"title": "AgentCallScreening",
"description": "Registry: voxai://agent-schema/call-screening/v1."
},
"AgentChatSettings": {
"properties": {
"silenceChatTimeoutInSeconds": {
"type": "integer",
"maximum": 172800.0,
"minimum": 120.0,
"title": "Silencechattimeoutinseconds",
"default": 3600,
"description": "Chat inactivity duration in seconds before the session ends."
}
},
"additionalProperties": false,
"type": "object",
"title": "AgentChatSettings",
"description": "Native Chat lifecycle settings stored in Agent data."
},
"AgentPostCall": {
"properties": {
"actions": {
"items": {
"$ref": "#/$defs/PostCallAction"
},
"type": "array",
"title": "Actions",
"description": "Post-call actions or extraction fields."
}
},
"type": "object",
"title": "AgentPostCall",
"description": "Registry: voxai://agent-schema/post-call/v1",
"additionalProperties": false
},
"PostCallAction": {
"properties": {
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable resource name."
},
"type": {
"type": "string",
"enum": [
"string",
"enum",
"boolean",
"number"
],
"title": "Type",
"description": "Resource or configuration type."
},
"isNullable": {
"type": "boolean",
"title": "Isnullable",
"default": false,
"description": "Whether this extracted field may be null."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "Human-readable description."
},
"enumOptions": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Enumoptions",
"description": "Allowed enum options for this extracted field."
}
},
"type": "object",
"required": [
"name",
"type"
],
"title": "PostCallAction",
"description": "Registry: voxai://agent-schema/post-call/v1 action item.",
"additionalProperties": false
},
"AgentSecurity": {
"properties": {
"optOutSensitiveDataStorage": {
"type": "boolean",
"title": "Optoutsensitivedatastorage",
"default": false,
"description": "Whether transcripts, recordings, and analysis outputs should avoid sensitive data storage."
},
"dataRetention": {
"anyOf": [
{
"$ref": "#/$defs/AgentDataRetention"
},
{
"type": "null"
}
]
},
"piiMasking": {
"$ref": "#/$defs/PiiMasking"
}
},
"type": "object",
"title": "AgentSecurity",
"description": "Registry: voxai://agent-schema/security/v1.",
"additionalProperties": false
},
"AgentDataRetention": {
"properties": {
"durationSeconds": {
"anyOf": [
{
"type": "integer",
"maximum": 315576000.0,
"minimum": 0.0
},
{
"type": "null"
}
],
"title": "Durationseconds",
"description": "null keeps the retained types indefinitely, 0 deletes them right after completion, and a positive value keeps them that many seconds after completion. A customer phone number is always kept at least one year."
},
"retainedDataTypes": {
"items": {
"type": "string",
"enum": [
"recording",
"transcript",
"postCallAnalysis",
"phoneNumber",
"dynamicVariables",
"metadata"
]
},
"type": "array",
"title": "Retaineddatatypes",
"description": "Types kept for the configured period; unlisted types are deleted after completion. Omit the field to keep all six."
}
},
"additionalProperties": false,
"type": "object",
"title": "AgentDataRetention",
"description": "Artifact-retention policy for call and chat data."
},
"PiiMasking": {
"properties": {
"enabled": {
"type": "boolean",
"title": "Enabled",
"description": "Master switch for replacing detected PII with numbered category placeholders in call and chat transcripts, summaries, and tool arguments/results. Post-call extraction values and phone number fields remain original.",
"default": false
},
"name": {
"type": "boolean",
"title": "Name",
"description": "Replaces person names with numbered placeholders such as [이름 1].",
"default": false
},
"phone": {
"type": "boolean",
"title": "Phone",
"description": "Replaces phone numbers with numbered placeholders such as [전화번호 1], excluding organization-owned numbers.",
"default": false
},
"birthDate": {
"type": "boolean",
"title": "Birthdate",
"description": "Replaces birth dates with numbered placeholders such as [생년월일 1].",
"default": false
},
"address": {
"type": "boolean",
"title": "Address",
"description": "Replaces addresses with numbered placeholders such as [주소 1].",
"default": false
},
"email": {
"type": "boolean",
"title": "Email",
"description": "Replaces email addresses with numbered placeholders such as [이메일 1].",
"default": false
},
"residentId": {
"type": "boolean",
"title": "Residentid",
"description": "Replaces Korean resident registration numbers with numbered placeholders such as [주민등록번호 1].",
"default": false
}
},
"type": "object",
"title": "PiiMasking",
"description": "PII categories masked in post-call artifacts.",
"additionalProperties": false
},
"AgentMemory": {
"properties": {
"enabled": {
"type": "boolean",
"title": "Enabled",
"default": false,
"description": "Whether this configuration is enabled."
}
},
"type": "object",
"title": "AgentMemory",
"description": "Registry: voxai://agent-schema/memory/v1 (1 field).",
"additionalProperties": false
},
"AgentWebhookSettings": {
"properties": {
"callDataWebhookUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Calldatawebhookurl",
"description": "HTTPS webhook URL. Dynamic path values allow only ASCII letters, digits, `_`, and `-`; arbitrary strings belong in query values."
},
"inboundCallWebhookUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Inboundcallwebhookurl",
"description": "Static HTTPS inbound-call webhook URL. Dynamic variables are not supported."
},
"webhookVersion": {
"anyOf": [
{
"type": "string",
"enum": [
"v1",
"v2"
]
},
{
"type": "null"
}
],
"title": "Webhookversion"
},
"enableAlimtalkOnCallEnd": {
"type": "boolean",
"title": "Enablealimtalkoncallend",
"default": false,
"description": "Whether to send a call summary by KakaoTalk AlimTalk when a call ends."
},
"inboundCallWebhookSigningEnabled": {
"type": "boolean",
"title": "Inboundcallwebhooksigningenabled",
"description": "Opt-in HMAC-SHA256 signing for inbound call webhook requests. When true, requests are signed with the organization webhook key and carry X-Webhook-Signature / X-Webhook-Timestamp headers (same format as organization webhooks). Omit or send false for the legacy unsigned behavior; null is rejected.",
"default": false
}
},
"type": "object",
"title": "AgentWebhookSettings",
"description": "Registry: voxai://agent-schema/webhook-settings/v1",
"additionalProperties": false
},
"AgentKnowledge": {
"properties": {
"ragEnabled": {
"type": "boolean",
"title": "Ragenabled",
"default": false,
"description": "Whether retrieval-augmented generation is enabled for this agent."
},
"knowledgeIds": {
"items": {
"type": "integer"
},
"type": "array",
"title": "Knowledgeids",
"description": "Numeric public knowledge IDs returned by `GET /v3/knowledges` and connected to this agent."
}
},
"type": "object",
"title": "AgentKnowledge",
"description": "Agent knowledge-base settings.",
"additionalProperties": false
},
"EndCallTool": {
"properties": {
"speakDuringExecution": {
"anyOf": [
{
"$ref": "#/$defs/app__dto__builtin_tool__SpeakDuringExecution"
},
{
"type": "null"
}
],
"description": "Speech messages played while the tool executes."
},
"allowInterruptionDuringExecution": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Allowinterruptionduringexecution",
"description": "Whether the user may interrupt speech while the tool executes. Omission or null allows interruption by default."
},
"responseMode": {
"type": "string",
"enum": [
"wait",
"fire_and_forget"
],
"title": "Responsemode",
"description": "`wait` blocks on tool completion. `fire_and_forget` starts the tool and lets the conversation continue.",
"default": "wait"
},
"toolType": {
"type": "string",
"const": "end_call",
"title": "Tool type",
"description": "Built-in tool type."
},
"name": {
"type": "string",
"title": "Name",
"default": "end_call",
"description": "Human-readable resource name."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "Human-readable description."
}
},
"type": "object",
"required": [
"toolType"
],
"title": "EndCallTool",
"additionalProperties": false
},
"app__dto__builtin_tool__SpeakDuringExecution": {
"properties": {
"enabled": {
"type": "boolean",
"title": "Enabled",
"default": false,
"description": "Whether this configuration is enabled."
},
"messages": {
"items": {
"type": "string"
},
"type": "array",
"title": "Messages",
"description": "Messages played while the tool is executing."
}
},
"type": "object",
"title": "SpeakDuringExecution",
"description": "Speech messages played while a tool executes.",
"additionalProperties": false
},
"TransferCallTool": {
"properties": {
"speakDuringExecution": {
"anyOf": [
{
"$ref": "#/$defs/app__dto__builtin_tool__SpeakDuringExecution"
},
{
"type": "null"
}
],
"description": "Speech messages played while the tool executes."
},
"allowInterruptionDuringExecution": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Allowinterruptionduringexecution",
"description": "Whether the user may interrupt speech while the tool executes. Omission or null allows interruption by default."
},
"responseMode": {
"type": "string",
"enum": [
"wait",
"fire_and_forget"
],
"title": "Responsemode",
"description": "`wait` blocks on tool completion. `fire_and_forget` starts the tool and lets the conversation continue.",
"default": "wait"
},
"toolType": {
"type": "string",
"const": "transfer_call",
"title": "Tool type",
"description": "Built-in tool type."
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable resource name."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "Human-readable description."
},
"transferConfigurations": {
"items": {
"$ref": "#/$defs/TransferConfig"
},
"type": "array",
"title": "Transfer configurations",
"description": "Transfer destinations. The v3 API returns `transferConfigurations`; runtime/web singular `transferConfiguration` is accepted on input."
},
"transferType": {
"type": "string",
"enum": [
"cold",
"warm"
],
"title": "Transfertype",
"description": "Call transfer mode: `cold` removes the agent as soon as the call is transferred and does not brief the operator; `warm` puts the customer on hold, briefs the operator with a conversation summary or static sentence, and then connects them. If the operator does not answer within `ringDurationInSeconds`, the agent resumes handling the customer.",
"default": "cold"
},
"transferMessageType": {
"type": "string",
"enum": [
"static",
"dynamic"
],
"title": "Transfermessagetype",
"description": "Operator briefing mode for `warm` transfers: `static` reads `warmTransferStaticSentence` verbatim to the operator, while `dynamic` uses `warmTransferPrompt` as instructions for the LLM to generate a conversation summary. Ignored for `cold` transfers.",
"default": "static"
},
"warmTransferPrompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Warmtransferprompt",
"description": "Instructions for the LLM to generate a conversation summary for the operator during a `warm` transfer. Used only when `transferMessageType` is `dynamic`."
},
"warmTransferStaticSentence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Warmtransferstaticsentence",
"description": "Sentence read verbatim to the operator during a `warm` transfer. Used only when `transferMessageType` is `static`."
},
"displayedCallerId": {
"type": "string",
"enum": [
"agent",
"user"
],
"title": "Displayedcallerid",
"description": "Caller ID shown on the operator's phone for both `cold` and `warm` transfers. `agent` shows the vox agent's phone number; `user` shows the current customer's phone number.",
"default": "agent"
},
"sipHeaders": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/TransferCallSipHeader"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Sipheaders",
"description": "Custom SIP headers sent with the transferred call. Not allowed when every destination is `operator`."
},
"holdAudio": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Holdaudio",
"description": "What the customer hears while a `warm` transfer rings the destination. Omit or `ringback` for the default ringback tone, `none` for silence, or the `file_key` of an audio file uploaded with `POST /files` and `purpose=hold_audio`. Ignored for `cold` transfers and `operator` destinations."
},
"ringDurationInSeconds": {
"anyOf": [
{
"type": "integer",
"maximum": 90.0,
"minimum": 1.0
},
{
"type": "null"
}
],
"title": "Ringdurationinseconds",
"description": "How many seconds a `warm` transfer rings the destination before it counts as unanswered, 1 to 90. Omit or null for 30. When nobody answers, a single-prompt agent resumes the conversation and a flow follows the transfer node's fallback edge. Ignored for `cold` transfers and `operator` destinations."
}
},
"type": "object",
"required": [
"toolType",
"name"
],
"title": "TransferCallTool",
"additionalProperties": false
},
"TransferConfig": {
"properties": {
"transferTo": {
"type": "string",
"title": "Transferto",
"description": "Phone number or SIP URI to transfer to. When `transferType` is `operator`, this is a display label shown to the operator, not a dialed destination."
},
"transferCondition": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Transfercondition",
"description": "Condition under which this transfer destination should be used."
},
"transferType": {
"type": "string",
"enum": [
"phone",
"sip",
"operator"
],
"title": "Transfertype",
"description": "Destination type. Defaults to `phone`, matching agent-server runtime. `operator` routes to a live human operator via the takeover handoff control plane (warm-only; `transferTo` is a display label).",
"default": "phone"
}
},
"type": "object",
"required": [
"transferTo"
],
"title": "TransferConfig",
"description": "Transfer destination for transfer_call.",
"additionalProperties": false
},
"TransferCallSipHeader": {
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"minLength": 3,
"pattern": "^X-[A-Za-z0-9-]+$",
"title": "Name",
"description": "SIP header name. Must start with `X-`, be 3-128 characters, match `X-[A-Za-z0-9-]+`, and must not use reserved system headers."
},
"value": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"title": "Value",
"description": "SIP header value. Must be 1-256 characters and must not contain CR/LF or control characters other than TAB."
}
},
"type": "object",
"required": [
"name",
"value"
],
"title": "TransferCallSipHeader",
"description": "SIP header key-value pair for transfer_call.",
"additionalProperties": false
},
"TransferAgentTool": {
"properties": {
"speakDuringExecution": {
"anyOf": [
{
"$ref": "#/$defs/app__dto__builtin_tool__SpeakDuringExecution"
},
{
"type": "null"
}
],
"description": "Speech messages played while the tool executes."
},
"allowInterruptionDuringExecution": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Allowinterruptionduringexecution",
"description": "Whether the user may interrupt speech while the tool executes. Omission or null allows interruption by default."
},
"responseMode": {
"type": "string",
"enum": [
"wait",
"fire_and_forget"
],
"title": "Responsemode",
"description": "`wait` blocks on tool completion. `fire_and_forget` starts the tool and lets the conversation continue.",
"default": "wait"
},
"toolType": {
"type": "string",
"const": "transfer_agent",
"title": "Tool type",
"description": "Built-in tool type."
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable resource name."
},
"agent": {
"$ref": "#/$defs/AgentMapping",
"description": "Agent mapping object with `agent_id` and `agent_version`. Used by cross-resource references (calls / campaigns / telephone_numbers) and by `builtInTools.transfer_agent` / flow `transferAgent` node `data.agent` per v3 §2.7 AgentMapping."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "Human-readable description."
},
"preserveChatContext": {
"type": "boolean",
"title": "Preservechatcontext",
"description": "Whether the target agent should receive prior conversation context.",
"default": false
}
},
"type": "object",
"required": [
"toolType",
"name",
"agent"
],
"title": "TransferAgentTool",
"description": "Built-in transfer_agent tool config.\n\nv3 §2.7 exposes the destination as a nested ``AgentMapping``. The same\nobject shape is used by flow transferAgent nodes and other v3 surfaces so\nclients can configure agent handoff consistently.",
"additionalProperties": false
},
"AgentMapping": {
"additionalProperties": false,
"description": "agent_id + agent_version 매핑.\n\n요청·응답 모두에서 에이전트 매핑이 필요한 경우 이 타입을 사용한다.\n요청 중 version 지정이 불필요한 엔드포인트는 flat `agent_id: UUID` 를 직접 받고,\n`AgentMapping` 을 쓰지 않는다.",
"properties": {
"agent_id": {
"description": "Agent UUID.",
"format": "uuid",
"title": "Agent Id",
"type": "string"
},
"agent_version": {
"default": "current",
"description": "에이전트 버전. 허용값: \"current\", \"production\", 또는 \"v{n}\" (n≥1). 미전송 시 \"current\"로 처리됩니다. null 전송은 거부.",
"title": "Agent Version",
"type": "string",
"pattern": "^(current|production|v[1-9][0-9]*)$",
"examples": [
"current",
"production",
"v1"
]
}
},
"required": [
"agent_id"
],
"title": "AgentMapping",
"type": "object"
},
"SendSmsTool": {
"properties": {
"speakDuringExecution": {
"anyOf": [
{
"$ref": "#/$defs/app__dto__builtin_tool__SpeakDuringExecution"
},
{
"type": "null"
}
],
"description": "Speech messages played while the tool executes."
},
"allowInterruptionDuringExecution": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Allowinterruptionduringexecution",
"description": "Whether the user may interrupt speech while the tool executes. Omission or null allows interruption by default."
},
"responseMode": {
"type": "string",
"enum": [
"wait",
"fire_and_forget"
],
"title": "Responsemode",
"description": "`wait` blocks on the SMS send result. `fire_and_forget` dispatches the SMS request and lets the conversation continue.",
"default": "wait"
},
"toolType": {
"type": "string",
"const": "send_sms",
"title": "Tool type",
"description": "Built-in tool type."
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable resource name."
},
"toolCallSound": {
"anyOf": [
{
"type": "string",
"enum": [
"none",
"typing",
"elevator_1",
"elevator_2",
"elevator_3",
"elevator_4"
]
},
{
"type": "null"
}
],
"title": "Toolcallsound",
"description": "Sound played while the tool runs, so the line does not go silent. Omit or `none` to play nothing; `typing` or `elevator_1`..`elevator_4` to pick a preset."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "Human-readable description."
},
"smsMessageType": {
"type": "string",
"enum": [
"static",
"dynamic"
],
"title": "Smsmessagetype",
"description": "SMS content mode. `static` sends the configured title/body/image file keys. `dynamic` lets the agent generate the body from `smsMessagePrompt`.",
"default": "static"
},
"smsMessageStaticSentence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Smsmessagestaticsentence",
"description": "Static message body used when `smsMessageType=static`. Together with a title or image file keys, this is sent as LMS/MMS as applicable."
},
"smsMessageStaticTitle": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Smsmessagestatictitle",
"description": "Optional static message title used when `smsMessageType=static`. Omit or null to send without a title."
},
"smsMessageStaticImageFileKeys": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 3
},
{
"type": "null"
}
],
"title": "Smsmessagestaticimagefilekeys",
"description": "Static MMS image attachment file keys. Values are opaque `file_key` strings returned by the file upload API. Provide up to 3 file keys; omit or null for text-only SMS/LMS."
},
"smsMessagePrompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Smsmessageprompt",
"description": "Prompt used by the agent to generate the SMS body when `smsMessageType=dynamic`."
},
"smsFromNumber": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Smsfromnumber",
"description": "Optional sender phone number override. It must be an SMS-send-capable number owned by the organization; omit or null to use the call context default."
}
},
"type": "object",
"required": [
"toolType",
"name"
],
"title": "SendSmsTool",
"additionalProperties": false
},
"SendDtmfTool": {
"properties": {
"toolType": {
"type": "string",
"const": "send_dtmf",
"title": "Tool type",
"description": "Built-in tool type."
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable resource name."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "Human-readable description."
},
"speakDuringExecution": {
"anyOf": [
{
"$ref": "#/$defs/app__dto__builtin_tool__SpeakDuringExecution"
},
{
"type": "null"
}
],
"description": "Speech messages played while the tool executes."
},
"responseMode": {
"type": "string",
"enum": [
"wait",
"fire_and_forget"
],
"title": "Responsemode",
"description": "`wait` blocks on tool completion. `fire_and_forget` starts the tool and lets the conversation continue.",
"default": "wait"
},
"allowInterruption": {
"type": "boolean",
"title": "Allowinterruption",
"description": "Whether the user may interrupt speech while the DTMF tool executes. Runtime/web `allowInterruptionDuringExecution` is accepted on input.",
"default": true
}
},
"type": "object",
"required": [
"toolType",
"name"
],
"title": "SendDtmfTool",
"additionalProperties": false
},
"SearchAddressTool": {
"properties": {
"speakDuringExecution": {
"$ref": "#/$defs/app__dto__builtin_tool__SpeakDuringExecution",
"description": "도구 실행 중 사용자에게 재생할 TTS 메시지를 설정합니다."
},
"allowInterruptionDuringExecution": {
"type": "boolean",
"title": "Allowinterruptionduringexecution",
"description": "도구 실행 중 사용자의 발화 끼어들기를 허용할지 설정합니다.",
"default": false
},
"responseMode": {
"type": "string",
"enum": [
"wait",
"fire_and_forget"
],
"title": "Responsemode",
"description": "`wait` blocks on tool completion. `fire_and_forget` starts the tool and lets the conversation continue.",
"default": "wait"
},
"toolType": {
"type": "string",
"const": "search_address",
"title": "Tool type",
"description": "Built-in tool type."
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable resource name."
},
"toolCallSound": {
"anyOf": [
{
"type": "string",
"enum": [
"none",
"typing",
"elevator_1",
"elevator_2",
"elevator_3",
"elevator_4"
]
},
{
"type": "null"
}
],
"title": "Toolcallsound",
"description": "Sound played while the tool runs, so the line does not go silent. Omit or `none` to play nothing; `typing` or `elevator_1`..`elevator_4` to pick a preset."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "도구의 역할과 호출 조건을 설명합니다. LLM이 이 설명을 바탕으로 도구 호출 여부를 판단합니다.",
"default": "Search Korean address candidates using OpenSearch and Kakao Local API. Use this when the caller provides Korean address clues such as region, road name and building number, jibun, or building/place name. The tool returns candidates, evidence, recommended_action, and timings; it does not confirm or commit the address."
}
},
"type": "object",
"required": [
"toolType",
"name"
],
"title": "SearchAddressTool",
"additionalProperties": false
},
"ExtractVariablesTool": {
"properties": {
"toolType": {
"type": "string",
"const": "extract_variables",
"title": "Tool type",
"description": "Built-in tool type."
},
"name": {
"type": "string",
"title": "Name",
"default": "extract_variables",
"description": "Human-readable resource name."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "When the agent should call this tool. Omit or null to use the runtime default."
},
"variables": {
"items": {
"$ref": "#/$defs/ExtractVariableDefinition"
},
"type": "array",
"minItems": 1,
"title": "Variables",
"description": "Variables this tool saves. A saved value is used like a dynamic variable in the prompt, tool fields, call records, and webhooks. A value the agent cannot extract keeps its previous value."
}
},
"type": "object",
"required": [
"toolType",
"variables"
],
"title": "ExtractVariablesTool",
"description": "Saves values from the conversation into variables.\n\nIt completes instantly, so it has no speech, interruption, response-mode, or sound settings.",
"additionalProperties": false
},
"ExtractVariableDefinition": {
"properties": {
"variableName": {
"type": "string",
"title": "Variablename",
"description": "Variable name, referenced as `{{name}}`. It must start with a letter (Korean allowed) and use only letters, digits, and `_`, up to 40 characters — the same rule as `presetDynamicVariables` keys."
},
"variableType": {
"type": "string",
"enum": [
"string",
"number",
"boolean"
],
"title": "Variabletype",
"description": "Type of the saved value."
},
"variableDescription": {
"type": "string",
"title": "Variabledescription",
"description": "What value to save. The agent reads this to decide what to extract.",
"default": ""
}
},
"type": "object",
"required": [
"variableName",
"variableType"
],
"title": "ExtractVariableDefinition",
"description": "One variable saved by the extract_variables tool (same keys as the flow extraction node).",
"additionalProperties": false
},
"PublicManualValue-Input": {
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"title": "Name",
"description": "Manual name, up to 128 characters."
},
"trigger": {
"type": "string",
"title": "Trigger",
"description": "Conversation situation that loads this manual. Leave it blank to load the manual only when another manual references it."
},
"content": {
"type": "string",
"maxLength": 8096,
"title": "Content",
"description": "Manual body, up to 8,096 characters including spaces. May contain `@tool:` and `@manual:` references."
},
"built_in_tools": {
"items": {
"oneOf": [
{
"$ref": "#/$defs/EndCallTool"
},
{
"$ref": "#/$defs/TransferCallTool"
},
{
"$ref": "#/$defs/TransferAgentTool"
},
{
"$ref": "#/$defs/SendSmsTool"
},
{
"$ref": "#/$defs/SendDtmfTool"
},
{
"$ref": "#/$defs/SearchAddressTool"
},
{
"$ref": "#/$defs/ExtractVariablesTool"
}
]
},
"type": "array",
"title": "Built In Tools",
"description": "Built-in tools owned by this manual. Reference one in `content` as `@tool:{name}`; each `name` must be a unique identifier (`[a-zA-Z_][a-zA-Z0-9_]*`)."
},
"config": {
"additionalProperties": {
"anyOf": [
{
"type": "string",
"enum": [
"none",
"typing",
"elevator_1",
"elevator_2",
"elevator_3",
"elevator_4"
]
},
{
"type": "null"
}
]
},
"type": "object",
"title": "Config",
"description": "Manual options. The only option is `tool_call_sound`, the sound played right after the manual loads."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"name",
"trigger",
"content"
],
"title": "PublicManualValue",
"description": "One agent-owned manual. `built_in_tools` uses the agent's built-in tool shapes."
},
"FlowInput": {
"properties": {
"nodes": {
"items": {
"$ref": "#/$defs/FlowNode"
},
"type": "array",
"title": "Nodes",
"description": "Flow graph nodes. Each node has an `id`, `type`, a required `position` (`{x, y}` canvas coordinates), and a type-specific `data` object."
},
"edges": {
"items": {
"$ref": "#/$defs/FlowEdgeInput"
},
"type": "array",
"title": "Edges",
"description": "Flow graph edges that connect source and target nodes."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"nodes",
"edges"
],
"title": "Flow",
"description": "Public ``flow`` document: ``{nodes, edges}``."
},
"FlowNode": {
"title": "FlowNode",
"description": "Public `flow` graph node. `type` is the discriminator and determines the schema of `data`.",
"oneOf": [
{
"$ref": "#/$defs/BeginFlowNode"
},
{
"$ref": "#/$defs/ConversationFlowNode"
},
{
"$ref": "#/$defs/ToolFlowNode"
},
{
"$ref": "#/$defs/ConditionFlowNode"
},
{
"$ref": "#/$defs/ExtractionFlowNode"
},
{
"$ref": "#/$defs/ApiFlowNode"
},
{
"$ref": "#/$defs/SendSmsFlowNode"
},
{
"$ref": "#/$defs/TransferCallFlowNode"
},
{
"$ref": "#/$defs/TransferAgentFlowNode"
},
{
"$ref": "#/$defs/EndCallFlowNode"
},
{
"$ref": "#/$defs/NoteFlowNode"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"begin": "#/components/schemas/BeginFlowNode",
"conversation": "#/components/schemas/ConversationFlowNode",
"tool": "#/components/schemas/ToolFlowNode",
"condition": "#/components/schemas/ConditionFlowNode",
"extraction": "#/components/schemas/ExtractionFlowNode",
"api": "#/components/schemas/ApiFlowNode",
"sendSms": "#/components/schemas/SendSmsFlowNode",
"transferCall": "#/components/schemas/TransferCallFlowNode",
"transferAgent": "#/components/schemas/TransferAgentFlowNode",
"endCall": "#/components/schemas/EndCallFlowNode",
"note": "#/components/schemas/NoteFlowNode"
}
}
},
"BeginFlowNode": {
"type": "object",
"title": "BeginFlowNode",
"description": "Public `flow` node with `type=begin`.",
"additionalProperties": false,
"required": [
"id",
"type",
"position"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Identifier of the response object itself, or a local identifier inside a nested configuration object."
},
"type": {
"type": "string",
"const": "begin",
"description": "Discriminator value for flow node type `begin`."
},
"position": {
"$ref": "#/$defs/Position",
"description": "Node canvas coordinates {x, y}. Required — the builder cannot render a node without a position, and the server does not invent one."
},
"data": {
"$ref": "#/$defs/BeginFlowNodeData",
"description": "Type-specific data payload for `begin`."
}
}
},
"Position": {
"properties": {
"x": {
"anyOf": [
{
"type": "integer"
},
{
"type": "number"
}
],
"title": "X"
},
"y": {
"anyOf": [
{
"type": "integer"
},
{
"type": "number"
}
],
"title": "Y"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"x",
"y"
],
"title": "Position",
"description": "Node canvas coordinates ``{x, y}``.\n\nRequired on the v2 surface: the builder cannot render a node without a\nposition, and the server never invents one. Carried verbatim so a\nread -> edit -> write cycle preserves layout. ``int | float`` keeps the\nbuilder's integer coordinates integer (lossless round-trip)."
},
"BeginFlowNodeData": {
"additionalProperties": false,
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human-readable node label. Optional on input: when omitted, the server fills a stable label from the node id at save time, so it is always present on the stored graph.",
"title": "Name"
},
"first_line_type": {
"enum": [
"aiFirst",
"userFirst"
],
"type": "string",
"description": "First-turn mode for a flow begin node: `aiFirst` or `userFirst`.",
"title": "First Line Type"
},
"pause_before_speaking_seconds": {
"anyOf": [
{
"maximum": 5.0,
"minimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"title": "Pause Before Speaking Seconds",
"description": "Delay in seconds before the agent speaks first."
}
},
"title": "BeginFlowNodeData",
"type": "object",
"description": "Type-specific `data` payload for node type `begin` in the public `flow` graph. Field names use snake_case (e.g. `prompt_type`, `first_line_type`). `transitions`, `logical_transitions`, and `global_node_settings` are represented by `flow.edges` and `data.global_node_setting`, so do not send those routing keys here. The v2 surface is strict: only the documented per-node fields (plus `global_node_setting`) are accepted on write; any other top-level key is rejected (FLOW_V2_INVALID).",
"required": [
"first_line_type"
]
},
"ConversationFlowNode": {
"type": "object",
"title": "ConversationFlowNode",
"description": "Public `flow` node with `type=conversation`.",
"additionalProperties": false,
"required": [
"id",
"type",
"position"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Identifier of the response object itself, or a local identifier inside a nested configuration object."
},
"type": {
"type": "string",
"const": "conversation",
"description": "Discriminator value for flow node type `conversation`."
},
"position": {
"$ref": "#/$defs/Position",
"description": "Node canvas coordinates {x, y}. Required — the builder cannot render a node without a position, and the server does not invent one."
},
"data": {
"$ref": "#/$defs/ConversationFlowNodeData",
"description": "Type-specific data payload for `conversation`."
}
}
},
"ConversationFlowNodeData": {
"additionalProperties": false,
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human-readable node label. Optional on input: when omitted, the server fills a stable label from the node id at save time, so it is always present on the stored graph.",
"title": "Name"
},
"prompt_type": {
"anyOf": [
{
"enum": [
"static",
"dynamic"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt Type"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt",
"description": "Agent prompt settings."
},
"static_sentence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Static Sentence"
},
"first_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "First Message",
"description": "Optional first message override for this conversation node."
},
"loop_condition": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Loop Condition",
"description": "이 대화 노드를 나가도 되는 조건이다. 참이 되면 다음 간선을 평가하고, 거짓이면 노드에 머물며 대화를 이어 간다. \"~하지 않으면 다시 묻는다\"가 아니라 \"~를 모두 받았다\", \"~를 분명히 골랐다\"처럼 완료 상태로 쓴다."
},
"is_allow_interruption": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Allow Interruption",
"description": "Whether the user may interrupt speech from this node."
},
"is_skip_user_response": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Skip waiting for a user reply after this conversation node speaks.",
"title": "Is Skip User Response"
},
"llm": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Llm",
"description": "Large language model settings."
},
"knowledge": {
"anyOf": [
{
"$ref": "#/$defs/NodeKnowledgeConfig"
},
{
"type": "null"
}
],
"description": "Agent knowledge-base settings."
},
"global_node_setting": {
"$ref": "#/$defs/GlobalNodeSetting",
"description": "Node-level global marker. Its presence marks this node as a global node; omit it for a normal node. Use the snake_case key ``global_node_setting`` — the camelCase ``globalNodeSettings`` is rejected on write."
}
},
"title": "ConversationFlowNodeData",
"type": "object",
"description": "Type-specific `data` payload for node type `conversation` in the public `flow` graph. Field names use snake_case (e.g. `prompt_type`, `first_line_type`). `transitions`, `logical_transitions`, and `global_node_settings` are represented by `flow.edges` and `data.global_node_setting`, so do not send those routing keys here. The v2 surface is strict: only the documented per-node fields (plus `global_node_setting`) are accepted on write; any other top-level key is rejected (FLOW_V2_INVALID)."
},
"NodeKnowledgeConfig": {
"additionalProperties": false,
"properties": {
"rag_enabled": {
"default": false,
"title": "Rag Enabled",
"type": "boolean",
"description": "Whether retrieval-augmented generation is enabled for this flow node."
},
"knowledge_ids": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Knowledge Ids",
"description": "Numeric public knowledge IDs connected to this flow node."
}
},
"title": "NodeKnowledgeConfig",
"type": "object"
},
"GlobalNodeSetting": {
"additionalProperties": false,
"description": "Node-level global marker. Presence of this object == global node.\n\nA global node is reachable from anywhere, so the public v2 graph carries no\nentry edges for it — only this marker plus its enter ``condition``.\n\nThe enter condition is the ``ai`` variant only. A ``logic`` / ``fallback``\nenter condition is rejected on write (``global_node_condition_unsupported``),\nso the schema is narrowed to ``AiCondition`` to advertise exactly what is\naccepted.",
"properties": {
"condition": {
"$ref": "#/$defs/AiCondition",
"description": "Condition under which the agent may jump to this global node. Only the ``ai`` variant is supported (the builder stores the entry as a ``transitionCondition`` string)."
}
},
"required": [
"condition"
],
"title": "GlobalNodeSetting",
"type": "object"
},
"AiCondition": {
"additionalProperties": false,
"description": "Natural-language edge condition, evaluated by the LLM during the call.",
"properties": {
"type": {
"const": "ai",
"title": "Type",
"type": "string",
"description": "Resource or configuration type."
},
"prompt": {
"default": "",
"description": "Natural-language transition condition.",
"title": "Prompt",
"type": "string"
}
},
"required": [
"type"
],
"title": "AiCondition",
"type": "object"
},
"ToolFlowNode": {
"type": "object",
"title": "ToolFlowNode",
"description": "Public `flow` node with `type=tool`.",
"additionalProperties": false,
"required": [
"id",
"type",
"position"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Identifier of the response object itself, or a local identifier inside a nested configuration object."
},
"type": {
"type": "string",
"const": "tool",
"description": "Discriminator value for flow node type `tool`."
},
"position": {
"$ref": "#/$defs/Position",
"description": "Node canvas coordinates {x, y}. Required — the builder cannot render a node without a position, and the server does not invent one."
},
"data": {
"$ref": "#/$defs/ToolFlowNodeData",
"description": "Type-specific data payload for `tool`."
}
}
},
"ToolFlowNodeData": {
"additionalProperties": false,
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human-readable node label. Optional on input: when omitted, the server fills a stable label from the node id at save time, so it is always present on the stored graph.",
"title": "Name"
},
"tool_call_sound": {
"anyOf": [
{
"enum": [
"none",
"typing",
"elevator_1",
"elevator_2",
"elevator_3",
"elevator_4"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Tool Call Sound"
},
"tool_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Tool Id",
"description": "Custom tool UUID. Use an `id` returned by `GET /v3/tools`."
},
"prompt_type": {
"anyOf": [
{
"enum": [
"none",
"static",
"dynamic"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Speech mode. When omitted, the runtime uses dynamic. The schema null default represents an unset field, not static speech or silence. Set none, static, or dynamic explicitly to choose the behavior.",
"title": "Prompt Type"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt",
"description": "Agent prompt settings."
},
"static_sentence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Static Sentence"
}
},
"title": "ToolFlowNodeData",
"type": "object",
"description": "Type-specific `data` payload for node type `tool` in the public `flow` graph. Field names use snake_case (e.g. `prompt_type`, `first_line_type`). `transitions`, `logical_transitions`, and `global_node_settings` are represented by `flow.edges` and `data.global_node_setting`, so do not send those routing keys here. The v2 surface is strict: only the documented per-node fields (plus `global_node_setting`) are accepted on write; any other top-level key is rejected (FLOW_V2_INVALID)."
},
"ConditionFlowNode": {
"type": "object",
"title": "ConditionFlowNode",
"description": "Public `flow` node with `type=condition`.",
"additionalProperties": false,
"required": [
"id",
"type",
"position"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Identifier of the response object itself, or a local identifier inside a nested configuration object."
},
"type": {
"type": "string",
"const": "condition",
"description": "Discriminator value for flow node type `condition`."
},
"position": {
"$ref": "#/$defs/Position",
"description": "Node canvas coordinates {x, y}. Required — the builder cannot render a node without a position, and the server does not invent one."
},
"data": {
"$ref": "#/$defs/ConditionFlowNodeData",
"description": "Type-specific data payload for `condition`."
}
}
},
"ConditionFlowNodeData": {
"additionalProperties": false,
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human-readable node label. Optional on input: when omitted, the server fills a stable label from the node id at save time, so it is always present on the stored graph.",
"title": "Name"
}
},
"title": "ConditionFlowNodeData",
"type": "object",
"description": "Type-specific `data` payload for node type `condition` in the public `flow` graph. Field names use snake_case (e.g. `prompt_type`, `first_line_type`). `transitions`, `logical_transitions`, and `global_node_settings` are represented by `flow.edges` and `data.global_node_setting`, so do not send those routing keys here. The v2 surface is strict: only the documented per-node fields (plus `global_node_setting`) are accepted on write; any other top-level key is rejected (FLOW_V2_INVALID)."
},
"ExtractionFlowNode": {
"type": "object",
"title": "ExtractionFlowNode",
"description": "Public `flow` node with `type=extraction`.",
"additionalProperties": false,
"required": [
"id",
"type",
"position"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Identifier of the response object itself, or a local identifier inside a nested configuration object."
},
"type": {
"type": "string",
"const": "extraction",
"description": "Discriminator value for flow node type `extraction`."
},
"position": {
"$ref": "#/$defs/Position",
"description": "Node canvas coordinates {x, y}. Required — the builder cannot render a node without a position, and the server does not invent one."
},
"data": {
"$ref": "#/$defs/ExtractionFlowNodeData",
"description": "Type-specific data payload for `extraction`."
}
}
},
"ExtractionFlowNodeData": {
"additionalProperties": false,
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human-readable node label. Optional on input: when omitted, the server fills a stable label from the node id at save time, so it is always present on the stored graph.",
"title": "Name"
},
"extraction_configuration": {
"$ref": "#/$defs/ExtractionConfiguration"
},
"is_skip_user_response": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"title": "Is Skip User Response",
"description": "Whether this node should execute without waiting for a user response."
},
"llm": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Llm",
"description": "Large language model settings."
},
"tool_call_sound": {
"anyOf": [
{
"enum": [
"none",
"typing",
"elevator_1",
"elevator_2",
"elevator_3",
"elevator_4"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Tool Call Sound"
}
},
"title": "ExtractionFlowNodeData",
"type": "object",
"description": "Type-specific `data` payload for node type `extraction` in the public `flow` graph. Field names use snake_case (e.g. `prompt_type`, `first_line_type`). `transitions`, `logical_transitions`, and `global_node_settings` are represented by `flow.edges` and `data.global_node_setting`, so do not send those routing keys here. The v2 surface is strict: only the documented per-node fields (plus `global_node_setting`) are accepted on write; any other top-level key is rejected (FLOW_V2_INVALID)."
},
"ExtractionConfiguration": {
"additionalProperties": false,
"properties": {
"extraction_prompt": {
"default": "",
"title": "Extraction Prompt",
"type": "string",
"description": "Prompt that tells the extraction node what information to collect."
},
"variables": {
"items": {
"$ref": "#/$defs/VariableDefinition"
},
"title": "Variables",
"type": "array",
"description": "Variables produced by this extraction configuration."
}
},
"title": "ExtractionConfiguration",
"type": "object"
},
"VariableDefinition": {
"additionalProperties": false,
"properties": {
"variable_name": {
"pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,39}$",
"title": "Variable Name",
"type": "string",
"description": "Name of the variable produced from an API response."
},
"variable_type": {
"default": "string",
"enum": [
"string",
"number",
"boolean"
],
"title": "Variable Type",
"type": "string",
"description": "Type of extracted or API response variable."
},
"variable_description": {
"default": "",
"title": "Variable Description",
"type": "string",
"description": "Human-readable description of the variable."
}
},
"required": [
"variable_name"
],
"title": "VariableDefinition",
"type": "object"
},
"ApiFlowNode": {
"type": "object",
"title": "ApiFlowNode",
"description": "Public `flow` node with `type=api`.",
"additionalProperties": false,
"required": [
"id",
"type",
"position"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Identifier of the response object itself, or a local identifier inside a nested configuration object."
},
"type": {
"type": "string",
"const": "api",
"description": "Discriminator value for flow node type `api`."
},
"position": {
"$ref": "#/$defs/Position",
"description": "Node canvas coordinates {x, y}. Required — the builder cannot render a node without a position, and the server does not invent one."
},
"data": {
"$ref": "#/$defs/ApiFlowNodeData",
"description": "Type-specific data payload for `api`."
}
}
},
"ApiFlowNodeData": {
"additionalProperties": false,
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human-readable node label. Optional on input: when omitted, the server fills a stable label from the node id at save time, so it is always present on the stored graph.",
"title": "Name"
},
"tool_call_sound": {
"anyOf": [
{
"enum": [
"none",
"typing",
"elevator_1",
"elevator_2",
"elevator_3",
"elevator_4"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Tool Call Sound"
},
"response_mode": {
"default": "wait",
"enum": [
"wait",
"fire_and_forget"
],
"title": "Response Mode",
"type": "string"
},
"api_configuration": {
"$ref": "#/$defs/ApiConfiguration"
},
"response_variables": {
"items": {
"$ref": "#/$defs/ApiResponseVariable"
},
"title": "Response Variables",
"type": "array",
"description": "Variables extracted from this API node response."
},
"prompt_type": {
"anyOf": [
{
"enum": [
"none",
"static",
"dynamic"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt Type"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt",
"description": "Agent prompt settings."
},
"static_sentence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Static Sentence"
}
},
"required": [
"api_configuration"
],
"title": "ApiFlowNodeData",
"type": "object",
"description": "Type-specific `data` payload for node type `api` in the public `flow` graph. Field names use snake_case (e.g. `prompt_type`, `first_line_type`). `transitions`, `logical_transitions`, and `global_node_settings` are represented by `flow.edges` and `data.global_node_setting`, so do not send those routing keys here. The v2 surface is strict: only the documented per-node fields (plus `global_node_setting`) are accepted on write; any other top-level key is rejected (FLOW_V2_INVALID)."
},
"ApiConfiguration": {
"additionalProperties": false,
"properties": {
"method": {
"default": "GET",
"enum": [
"GET",
"POST",
"PUT",
"DELETE"
],
"title": "Method",
"type": "string",
"description": "HTTP method used by this API node."
},
"url": {
"description": "API endpoint URL. Dynamic path values allow only ASCII letters, digits, `_`, and `-`; arbitrary strings belong in query values.",
"title": "Url",
"type": "string"
},
"authorization_enabled": {
"default": false,
"title": "Authorization Enabled",
"type": "boolean",
"description": "Whether this API node sends authorization credentials."
},
"auth_type": {
"default": "None",
"enum": [
"None",
"Basic",
"Bearer"
],
"title": "Auth Type",
"type": "string",
"description": "Authorization scheme used by this API node."
},
"auth_credentials": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Auth Credentials",
"description": "Authorization credential value or template for this API node."
},
"auth_encode_required": {
"default": false,
"title": "Auth Encode Required",
"type": "boolean",
"description": "Whether authorization credentials should be encoded before sending."
},
"headers_enabled": {
"default": false,
"title": "Headers Enabled",
"type": "boolean",
"description": "Whether custom headers are sent by this API node."
},
"headers": {
"additionalProperties": {
"type": "string"
},
"title": "Headers",
"type": "object",
"description": "Custom HTTP headers sent by this API node."
},
"body_enabled": {
"default": false,
"title": "Body Enabled",
"type": "boolean",
"description": "Whether this API node sends a request body."
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Body",
"description": "Request body payload or template sent by this API node."
},
"timeout_seconds": {
"default": 10,
"exclusiveMinimum": 0,
"title": "Timeout Seconds",
"type": "integer",
"description": "Maximum seconds to wait for this API node request."
}
},
"required": [
"url"
],
"title": "ApiConfiguration",
"type": "object"
},
"ApiResponseVariable": {
"additionalProperties": false,
"properties": {
"variable_name": {
"title": "Variable Name",
"type": "string",
"description": "Name of the variable produced from an API response."
},
"json_path": {
"title": "Json Path",
"type": "string"
}
},
"required": [
"variable_name",
"json_path"
],
"title": "ApiResponseVariable",
"type": "object"
},
"SendSmsFlowNode": {
"type": "object",
"title": "SendSmsFlowNode",
"description": "Public `flow` node with `type=sendSms`.",
"additionalProperties": false,
"required": [
"id",
"type",
"position"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Identifier of the response object itself, or a local identifier inside a nested configuration object."
},
"type": {
"type": "string",
"const": "sendSms",
"description": "Discriminator value for flow node type `sendSms`."
},
"position": {
"$ref": "#/$defs/Position",
"description": "Node canvas coordinates {x, y}. Required — the builder cannot render a node without a position, and the server does not invent one."
},
"data": {
"$ref": "#/$defs/SendSmsFlowNodeData",
"description": "Type-specific data payload for `sendSms`."
}
}
},
"SendSmsFlowNodeData": {
"additionalProperties": false,
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human-readable node label. Optional on input: when omitted, the server fills a stable label from the node id at save time, so it is always present on the stored graph.",
"title": "Name"
},
"tool_call_sound": {
"anyOf": [
{
"enum": [
"none",
"typing",
"elevator_1",
"elevator_2",
"elevator_3",
"elevator_4"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Tool Call Sound"
},
"response_mode": {
"default": "wait",
"enum": [
"wait",
"fire_and_forget"
],
"title": "Response Mode",
"type": "string"
},
"prompt_type": {
"anyOf": [
{
"enum": [
"static",
"dynamic"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "static",
"title": "Prompt Type"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt",
"description": "Agent prompt settings."
},
"static_title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Static Title"
},
"static_sentence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Static Sentence"
},
"static_image_file_keys": {
"anyOf": [
{
"items": {
"type": "string"
},
"maxItems": 3,
"type": "array"
},
{
"type": "null"
}
],
"description": "Static MMS image attachment file keys. Values are opaque file_key strings returned by the file upload endpoint.",
"title": "Static Image File Keys"
},
"sms_from_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sms From Number"
},
"global_node_setting": {
"$ref": "#/$defs/GlobalNodeSetting",
"description": "Node-level global marker. Its presence marks this node as a global node; omit it for a normal node. Use the snake_case key ``global_node_setting`` — the camelCase ``globalNodeSettings`` is rejected on write."
}
},
"title": "SendSmsFlowNodeData",
"type": "object",
"description": "Type-specific `data` payload for node type `sendSms` in the public `flow` graph. Field names use snake_case (e.g. `prompt_type`, `first_line_type`). `transitions`, `logical_transitions`, and `global_node_settings` are represented by `flow.edges` and `data.global_node_setting`, so do not send those routing keys here. The v2 surface is strict: only the documented per-node fields (plus `global_node_setting`) are accepted on write; any other top-level key is rejected (FLOW_V2_INVALID)."
},
"TransferCallFlowNode": {
"type": "object",
"title": "TransferCallFlowNode",
"description": "Public `flow` node with `type=transferCall`.",
"additionalProperties": false,
"required": [
"id",
"type",
"position"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Identifier of the response object itself, or a local identifier inside a nested configuration object."
},
"type": {
"type": "string",
"const": "transferCall",
"description": "Discriminator value for flow node type `transferCall`."
},
"position": {
"$ref": "#/$defs/Position",
"description": "Node canvas coordinates {x, y}. Required — the builder cannot render a node without a position, and the server does not invent one."
},
"data": {
"$ref": "#/$defs/TransferCallFlowNodeData",
"description": "Type-specific data payload for `transferCall`."
}
}
},
"TransferCallFlowNodeData": {
"additionalProperties": false,
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human-readable node label. Optional on input: when omitted, the server fills a stable label from the node id at save time, so it is always present on the stored graph.",
"title": "Name"
},
"transfer_configuration": {
"$ref": "#/$defs/TransferConfiguration"
},
"transfer_type": {
"anyOf": [
{
"enum": [
"cold",
"warm"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "cold",
"title": "Transfer Type",
"description": "Transfer mode used by this flow node."
},
"transfer_message_type": {
"anyOf": [
{
"enum": [
"static",
"dynamic"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "static",
"title": "Transfer Message Type"
},
"warm_transfer_prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Warm Transfer Prompt",
"description": "Prompt used to generate a warm-transfer message."
},
"warm_transfer_static_sentence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Warm Transfer Static Sentence",
"description": "Static warm-transfer message."
},
"displayed_caller_id": {
"anyOf": [
{
"enum": [
"agent",
"user"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "agent",
"title": "Displayed Caller Id",
"description": "Caller ID source displayed during call transfer."
},
"sip_headers": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/SipHeader"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Sip Headers",
"description": "SIP headers attached to the transfer call."
},
"hold_audio": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "What the customer hears while a `warm` transfer rings the destination. Omit or `ringback` for the default ringback tone, `none` for silence, or the `file_key` of an audio file uploaded with `POST /files` and `purpose=hold_audio`. Ignored for `cold` transfers and `operator` destinations.",
"title": "Hold Audio"
},
"ring_duration_in_seconds": {
"anyOf": [
{
"maximum": 90,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"description": "How many seconds a `warm` transfer rings the destination before it counts as unanswered, 1 to 90. Omit or null for 30. When nobody answers, a single-prompt agent resumes the conversation and a flow follows the transfer node's fallback edge. Ignored for `cold` transfers and `operator` destinations.",
"title": "Ring Duration In Seconds"
},
"prompt_type": {
"anyOf": [
{
"enum": [
"none",
"static",
"dynamic"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Speech mode. When omitted, the runtime uses dynamic. The schema null default represents an unset field, not static speech or silence. Set none, static, or dynamic explicitly to choose the behavior.",
"title": "Prompt Type"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt",
"description": "Agent prompt settings."
},
"static_sentence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Static Sentence"
}
},
"required": [
"transfer_configuration"
],
"title": "TransferCallFlowNodeData",
"type": "object",
"description": "Type-specific `data` payload for node type `transferCall` in the public `flow` graph. Field names use snake_case (e.g. `prompt_type`, `first_line_type`). `transitions`, `logical_transitions`, and `global_node_settings` are represented by `flow.edges` and `data.global_node_setting`, so do not send those routing keys here. The v2 surface is strict: only the documented per-node fields (plus `global_node_setting`) are accepted on write; any other top-level key is rejected (FLOW_V2_INVALID)."
},
"TransferConfiguration": {
"additionalProperties": false,
"properties": {
"transfer_to": {
"description": "Phone number or SIP URI to transfer to. When `transfer_type` is `operator`, this is a display label shown to the operator, not a dialed destination.",
"title": "Transfer To",
"type": "string"
},
"transfer_type": {
"default": "phone",
"description": "Destination transport. `operator` routes to a live human operator via the takeover handoff control plane (warm-only; `transfer_to` is a display label).",
"enum": [
"phone",
"sip",
"operator"
],
"title": "Transfer Type",
"type": "string"
},
"transfer_condition": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Transfer Condition",
"description": "Condition that determines whether the transfer should run."
}
},
"required": [
"transfer_to"
],
"title": "TransferConfiguration",
"type": "object"
},
"SipHeader": {
"additionalProperties": false,
"properties": {
"name": {
"title": "Name",
"type": "string",
"description": "Human-readable resource name."
},
"value": {
"title": "Value",
"type": "string",
"description": "Comparison value used by this condition."
}
},
"required": [
"name",
"value"
],
"title": "SipHeader",
"type": "object"
},
"TransferAgentFlowNode": {
"type": "object",
"title": "TransferAgentFlowNode",
"description": "Public `flow` node with `type=transferAgent`.",
"additionalProperties": false,
"required": [
"id",
"type",
"position"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Identifier of the response object itself, or a local identifier inside a nested configuration object."
},
"type": {
"type": "string",
"const": "transferAgent",
"description": "Discriminator value for flow node type `transferAgent`."
},
"position": {
"$ref": "#/$defs/Position",
"description": "Node canvas coordinates {x, y}. Required — the builder cannot render a node without a position, and the server does not invent one."
},
"data": {
"$ref": "#/$defs/TransferAgentFlowNodeData",
"description": "Type-specific data payload for `transferAgent`."
}
}
},
"TransferAgentFlowNodeData": {
"additionalProperties": false,
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human-readable node label. Optional on input: when omitted, the server fills a stable label from the node id at save time, so it is always present on the stored graph.",
"title": "Name"
},
"agent": {
"$ref": "#/$defs/AgentMapping",
"description": "Agent mapping object with `agent_id` and `agent_version`. Used by cross-resource references (calls / campaigns / telephone_numbers) and by `builtInTools.transfer_agent` / flow `transferAgent` node `data.agent` per v3 §2.7 AgentMapping."
},
"preserve_chat_context": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Preserve Chat Context",
"description": "Whether the target agent should receive prior conversation context."
}
},
"required": [
"agent"
],
"title": "TransferAgentFlowNodeData",
"type": "object",
"description": "Type-specific `data` payload for node type `transferAgent` in the public `flow` graph. Field names use snake_case (e.g. `prompt_type`, `first_line_type`). `transitions`, `logical_transitions`, and `global_node_settings` are represented by `flow.edges` and `data.global_node_setting`, so do not send those routing keys here. The v2 surface is strict: only the documented per-node fields (plus `global_node_setting`) are accepted on write; any other top-level key is rejected (FLOW_V2_INVALID)."
},
"EndCallFlowNode": {
"type": "object",
"title": "EndCallFlowNode",
"description": "Public `flow` node with `type=endCall`.",
"additionalProperties": false,
"required": [
"id",
"type",
"position"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Identifier of the response object itself, or a local identifier inside a nested configuration object."
},
"type": {
"type": "string",
"const": "endCall",
"description": "Discriminator value for flow node type `endCall`."
},
"position": {
"$ref": "#/$defs/Position",
"description": "Node canvas coordinates {x, y}. Required — the builder cannot render a node without a position, and the server does not invent one."
},
"data": {
"$ref": "#/$defs/EndCallFlowNodeData",
"description": "Type-specific data payload for `endCall`."
}
}
},
"EndCallFlowNodeData": {
"additionalProperties": false,
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human-readable node label. Optional on input: when omitted, the server fills a stable label from the node id at save time, so it is always present on the stored graph.",
"title": "Name"
},
"prompt_type": {
"anyOf": [
{
"enum": [
"none",
"static",
"dynamic"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Speech mode. When omitted, the runtime uses dynamic. The schema null default represents an unset field, not static speech or silence. Set none, static, or dynamic explicitly to choose the behavior.",
"title": "Prompt Type"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt",
"description": "Agent prompt settings."
},
"static_sentence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Static Sentence"
},
"global_node_setting": {
"$ref": "#/$defs/GlobalNodeSetting",
"description": "Node-level global marker. Its presence marks this node as a global node; omit it for a normal node. Use the snake_case key ``global_node_setting`` — the camelCase ``globalNodeSettings`` is rejected on write."
}
},
"title": "EndCallFlowNodeData",
"type": "object",
"description": "Type-specific `data` payload for node type `endCall` in the public `flow` graph. Field names use snake_case (e.g. `prompt_type`, `first_line_type`). `transitions`, `logical_transitions`, and `global_node_settings` are represented by `flow.edges` and `data.global_node_setting`, so do not send those routing keys here. The v2 surface is strict: only the documented per-node fields (plus `global_node_setting`) are accepted on write; any other top-level key is rejected (FLOW_V2_INVALID)."
},
"NoteFlowNode": {
"type": "object",
"title": "NoteFlowNode",
"description": "Public `flow` node with `type=note`.",
"additionalProperties": false,
"required": [
"id",
"type",
"position"
],
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Identifier of the response object itself, or a local identifier inside a nested configuration object."
},
"type": {
"type": "string",
"const": "note",
"description": "Discriminator value for flow node type `note`."
},
"position": {
"$ref": "#/$defs/Position",
"description": "Node canvas coordinates {x, y}. Required — the builder cannot render a node without a position, and the server does not invent one."
},
"data": {
"$ref": "#/$defs/NoteFlowNodeData",
"description": "Type-specific data payload for `note`."
}
}
},
"NoteFlowNodeData": {
"additionalProperties": false,
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content",
"description": "Text content for this flow node or message object."
},
"width": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Width"
},
"height": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Height"
}
},
"title": "NoteFlowNodeData",
"type": "object",
"description": "Type-specific `data` payload for node type `note` in the public `flow` graph. Field names use snake_case (e.g. `prompt_type`, `first_line_type`). `transitions`, `logical_transitions`, and `global_node_settings` are represented by `flow.edges` and `data.global_node_setting`, so do not send those routing keys here. The v2 surface is strict: only the documented per-node fields (plus `global_node_setting`) are accepted on write; any other top-level key is rejected (FLOW_V2_INVALID)."
},
"FlowEdgeInput": {
"properties": {
"id": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
],
"title": "Id",
"description": "Optional. Server generates one if omitted; reused verbatim when provided. Empty string is rejected."
},
"source": {
"type": "string",
"title": "Source",
"description": "Source flow node ID."
},
"target": {
"type": "string",
"title": "Target",
"description": "Target flow node ID."
},
"condition": {
"oneOf": [
{
"$ref": "#/$defs/AiCondition"
},
{
"$ref": "#/$defs/LogicCondition"
},
{
"$ref": "#/$defs/FallbackCondition"
}
],
"title": "Condition",
"discriminator": {
"propertyName": "type",
"mapping": {
"ai": "#/components/schemas/AiCondition",
"fallback": "#/components/schemas/FallbackCondition",
"logic": "#/components/schemas/LogicCondition"
}
}
},
"skip_user_response": {
"type": "boolean",
"title": "Skip User Response",
"description": "v1 ``isSkipUserResponse`` — skip waiting for a user reply on this hop.",
"default": false
}
},
"additionalProperties": false,
"type": "object",
"required": [
"source",
"target",
"condition"
],
"title": "FlowEdge",
"description": "Public ``flow`` edge: ``{id?, source, target, condition, skip_user_response}``."
},
"LogicCondition": {
"properties": {
"type": {
"type": "string",
"const": "logic",
"title": "Type",
"description": "Resource or configuration type."
},
"equations": {
"items": {
"$ref": "#/$defs/LogicEquation"
},
"type": "array",
"title": "Equations"
},
"operator": {
"type": "string",
"enum": [
"&&",
"||"
],
"title": "Operator",
"description": "How the equations combine. ``&&`` = AND, ``||`` = OR.",
"default": "&&"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"type"
],
"title": "LogicCondition",
"description": "Deterministic edge condition using the Retell-aligned ``equations`` shape.\n\nSource node must be a ``condition`` node (logic-source constraint, enforced elsewhere)."
},
"LogicEquation": {
"properties": {
"left": {
"type": "string",
"title": "Left",
"description": "Left operand — usually an extracted variable name."
},
"operator": {
"type": "string",
"enum": [
"equals",
"not_equals",
"contains",
"does_not_contain",
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal",
"exists",
"does_not_exist"
],
"title": "Operator",
"description": "Comparison operator in snake_case (e.g. greater_than, does_not_exist)."
},
"right": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Right",
"description": "Right operand. May be string/number/bool, or null for exists/does_not_exist."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"left",
"operator"
],
"title": "LogicEquation",
"description": "A single deterministic comparison inside a ``logic`` condition (Retell-aligned equations shape).\n\nRetell-aligned naming: ``left`` is the extracted variable, ``right`` is the\ncompared value (omitted for ``exists`` / ``does_not_exist``)."
},
"FallbackCondition": {
"properties": {
"type": {
"type": "string",
"const": "fallback",
"title": "Type",
"description": "Resource or configuration type."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"type"
],
"title": "FallbackCondition",
"description": "Default edge taken when no other condition on the source node matches."
},
"UpdateAgentRequest": {
"properties": {
"expected_head_revision": {
"type": "integer",
"minimum": 0.0,
"title": "Expected Head Revision",
"description": "Optional. The agent `head_revision` you last read. When sent, the update is rejected with 409 `REVISION_CONFLICT` if the agent changed since; omit it to save against the current revision."
},
"expected_flow_revision": {
"title": "Expected Flow Revision",
"description": "Optional. The Flow `flow_revision` you last read; omit to save against the current Flow.",
"type": "integer",
"minimum": 0.0
},
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"title": "Name",
"description": "New agent display name. Omit the field to keep the current name; `null` is rejected."
},
"data": {
"$ref": "#/$defs/AgentDataUpdate",
"description": "PATCH payload for agent configuration. Shape is published as `agent-schema/agent-data-update`. Omitted top-level sub-schemas are kept; sent sub-schemas are merged by the service according to the update schema."
},
"flow": {
"$ref": "#/$defs/FlowInput",
"description": "PATCH payload for the flow graph — use this instead of the deprecated `flow_data`. Replaces the whole graph; omit it to keep the current one. Sending `null` is rejected (it would be a misleading no-op); omit the field instead. If you send both `flow` and `flow_data`, `flow` is used and `flow_data` is ignored. The exact shape is published at the `flow-schema/flow-data` schema endpoint."
}
},
"type": "object",
"minProperties": 1,
"title": "UpdateAgentRequest",
"description": "Agent patch request.\n\n- Send at least one field.\n- Omit fields to keep existing values.\n- `type` is create-time only.\n- Send `flow` to replace a flow agent's graph; `flow_data` is the deprecated\n builder-shape equivalent kept for compatibility.",
"required": [
"expected_head_revision"
],
"anyOf": [
{
"required": [
"name"
]
},
{
"required": [
"data"
]
},
{
"required": [
"flow"
]
}
],
"additionalProperties": false
},
"AgentDataUpdate": {
"properties": {
"prompt": {
"$ref": "#/$defs/AgentPrompt",
"description": "Agent prompt settings."
},
"stt": {
"$ref": "#/$defs/AgentSTT",
"description": "Speech-to-text settings."
},
"llm": {
"$ref": "#/$defs/AgentLLM",
"description": "Large language model settings."
},
"voice": {
"$ref": "#/$defs/AgentVoice",
"description": "Text-to-speech voice settings."
},
"speech": {
"$ref": "#/$defs/AgentSpeech",
"description": "Agent speech behavior settings."
},
"callSettings": {
"$ref": "#/$defs/AgentCallSettings",
"description": "Agent call behavior settings. Kept camelCase for compatibility."
},
"chatSettings": {
"$ref": "#/$defs/AgentChatSettings",
"description": "Native Chat session lifecycle settings. Kept camelCase for compatibility."
},
"postCall": {
"$ref": "#/$defs/AgentPostCall",
"description": "Post-call extraction and action settings. Kept camelCase."
},
"security": {
"$ref": "#/$defs/AgentSecurity",
"description": "Agent security and privacy settings."
},
"memory": {
"$ref": "#/$defs/AgentMemory",
"description": "Agent customer-memory settings."
},
"webhookSettings": {
"$ref": "#/$defs/AgentWebhookSettings",
"description": "Agent webhook settings. Kept camelCase for compatibility."
},
"knowledge": {
"$ref": "#/$defs/AgentKnowledge",
"description": "Agent knowledge-base settings."
},
"takeoverTranscription": {
"type": "boolean",
"title": "Takeovertranscription",
"description": "Enables real-time captions and durable transcription for the recorded human takeover segment. Set to false to opt out. Defaults to true.",
"default": true
},
"presetDynamicVariables": {
"additionalProperties": {
"type": "string"
},
"type": "object",
"title": "Preset dynamic variables",
"description": "Preset dynamic variables available to the agent."
},
"toolIds": {
"items": {
"type": "string",
"format": "uuid"
},
"type": "array",
"title": "Tool IDs",
"description": "Custom tool UUIDs returned by `GET /v3/tools` and connected to the agent."
},
"builtInTools": {
"items": {
"oneOf": [
{
"$ref": "#/$defs/EndCallTool"
},
{
"$ref": "#/$defs/TransferCallTool"
},
{
"$ref": "#/$defs/TransferAgentTool"
},
{
"$ref": "#/$defs/SendSmsTool"
},
{
"$ref": "#/$defs/SendDtmfTool"
},
{
"$ref": "#/$defs/SearchAddressTool"
},
{
"$ref": "#/$defs/ExtractVariablesTool"
}
]
},
"type": "array",
"title": "Built-in tools",
"description": "Built-in tools connected to the agent."
},
"manuals": {
"additionalProperties": {
"$ref": "#/$defs/PublicManualValue-Input"
},
"type": "object",
"title": "Manuals",
"description": "Full replacement of the agent-owned manual map when provided."
}
},
"type": "object",
"title": "AgentDataUpdate",
"description": "Agent configuration accepted by update-agent requests.\n\nOmitted top-level sub-schemas are kept. Sent sub-schemas update that\npart of the configuration.",
"additionalProperties": false
}
}
}
}
SHA-256: 83a9f53dd2e89f7604618dd2b1f0d1f6415126948fa93594a6026ecb0112740d