--- title: "Get Voice Agent" method: GET path: "/v2/voice-agents/{voiceAgentId}" --- # Get Voice Agent `GET /v2/voice-agents/{voiceAgentId}` Retrieves a specific voice agent by its unique identifier. ## Path parameters - `voiceAgentId` string, uuid, required ## Response `200` Successful response - GetVoiceAgentV2Response - `success` boolean - `data` VoiceAgentV2Data — Voice agent data structure - `id` string, uuid - `type` string, nullable - `name` string - `conversation` object - `greetingMessage` string - `greetingMessageType` string, nullable - `preamble` string - `pokeMessages` string[] - `params` object - `alignment` object - `greetingMessage` string - `preamble` string - `voice` object - `voiceId` string, nullable - `voiceRecordId` string, nullable - `voiceRecord` object, nullable — TTS voice details - `id` string, uuid - `name` string - `provider` string - `language` string - `image` string, nullable - `languageCode` string, nullable - `voiceRecord` object, nullable - `lang` string, nullable - `ttsParams` object, nullable - `llm` object - `provider` string - `model` string - `temperature` number - `baseUrl` string, nullable - `apiKey` string, nullable - `callSettings` object - `noiseCancellation` string - `cancelNoisePer` string, nullable - `interrupt` boolean - `responseDelay` number - `userInactivityTimeout` number - `maxCallDuration` number - `silenceThreshold` number - `backgroundNoise` boolean - `thinkingVoice` boolean - `speakerIdentification` boolean - `agenticRag` boolean - `languageDialectSwitcher` boolean - `minInterruptionDuration` number - `vadActivationThreshold` number - `enableAutoGainControl` boolean - `sendDenoisedToStt` boolean - `genderDetection` boolean - `smartCallEnd` boolean - `waitForUserToSpeakFirst` number - `tools` object[], nullable — Agent tools configuration - `knowledgeBaseItemsIds` string[] - `voiceDictionaryIds` string[] - `phoneNumber` object, nullable - `type` string - `id` string, uuid - `webhookUrl` string, nullable - `webhookAuth` object, nullable - `workflow` Workflow — Flow Agent workflow graph. Stored on the agent and only meaningful when `type` is `"Flow Agent"`. Holds the graph `nodes`, the `edges` connecting them, and workflow-level `customVariables`. Agent-level configuration (voice, llm, call settings, tools, webhooks) lives in the top-level agent fields, **not** inside this object. - `nodes` WorkflowNode[], required — The workflow nodes (the flow graph). - union — A workflow node. The concrete shape depends on the `type` discriminator. - WorkflowConversationNode — Conversation node — the agent speaks/listens. - `id` string, required — Unique node id (nanoid or UUID). - `type` 'conversation', required — Node type discriminator. - `label` string — Display label. - `description` string — Optional node description. - `isGlobal` boolean — Whether this is a global node. - `globalCondition` string — Condition that activates a global node. Supports `{{variable}}` interpolation; may be empty. - `globalConditionType` 'prompt' | 'dtmf' - `globalDtmfKey` '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '#' | '*' — DTMF key that triggers the global node when `globalConditionType` is `dtmf`. - `globalReturnToSource` boolean - `requiresDoubleConfirm` boolean - `skipResponse` boolean - `staticVariables` WorkflowStaticVariable[] - … - `metadata` WorkflowNodeMetadata, required — Node metadata. - … - `transitions` WorkflowTransition[] — Outgoing transitions to other nodes. - … - `position` WorkflowPosition, required — Canvas position of the node. - … - `messageType` 'static' | 'prompt' — Whether the message is a literal `static` string or a `prompt` for the LLM. - `message` string — Node message. May be empty. Supports `{{variable}}` interpolation. - `interruptMode` 'inherit' | 'enable' | 'disable' - `extractVariables` WorkflowExtractVariablesConfig — Variable extraction config for a node. - … - `dtmfInputCapture` WorkflowDtmfInputCapture — Captures DTMF digits into a variable. - … - WorkflowStartNode — Entry node of the workflow. - `id` string, required — Unique node id (nanoid or UUID). - `type` 'start', required — Node type discriminator. - `label` string — Display label. - `description` string — Optional node description. - `isGlobal` boolean — Whether this is a global node. - `globalCondition` string — Condition that activates a global node. Supports `{{variable}}` interpolation; may be empty. - `globalConditionType` 'prompt' | 'dtmf' - `globalDtmfKey` '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '#' | '*' — DTMF key that triggers the global node when `globalConditionType` is `dtmf`. - `globalReturnToSource` boolean - `requiresDoubleConfirm` boolean - `skipResponse` boolean - `staticVariables` WorkflowStaticVariable[] - … - `metadata` WorkflowNodeMetadata, required — Node metadata. - … - `transitions` WorkflowTransition[] — Outgoing transitions to other nodes. - … - `position` WorkflowPosition, required — Canvas position of the node. - … - `subType` 'conversation' | 'tool' - `messageType` 'static' | 'prompt' — Whether the message is a literal `static` string or a `prompt` for the LLM. - `message` string — Node message. May be empty. Supports `{{variable}}` interpolation. - `interrupt` boolean — Allow user to interrupt. - `extractVariables` WorkflowExtractVariablesConfig — Variable extraction config for a node. - … - `dtmfInputCapture` WorkflowDtmfInputCapture — Captures DTMF digits into a variable. - … - `timeout` integer — Timeout in milliseconds. - `overrideResponse` boolean — Override the default response with `customResponse`. - `customResponse` string — Custom response shown instead of the default. Required when `overrideResponse` is true. Supports `{{variable}}` interpolation; may be empty. - `outputMapping` object — Maps tool output fields to workflow variables. - `onErrorBehavior` 'continue' | 'retry' | 'fail' - `errorMessage` string — Message spoken when the node errors. Supports `{{variable}}` interpolation; may be empty. - `processingMessage` string — Message spoken while the node runs. - `processingMessageType` 'static' | 'prompt' — Whether the message is a literal `static` string or a `prompt` for the LLM. - WorkflowToolNode — Function-tool execution node. - `id` string, required — Unique node id (nanoid or UUID). - `type` 'tool', required — Node type discriminator. - `label` string — Display label. - `description` string — Optional node description. - `isGlobal` boolean — Whether this is a global node. - `globalCondition` string — Condition that activates a global node. Supports `{{variable}}` interpolation; may be empty. - `globalConditionType` 'prompt' | 'dtmf' - `globalDtmfKey` '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '#' | '*' — DTMF key that triggers the global node when `globalConditionType` is `dtmf`. - `globalReturnToSource` boolean - `requiresDoubleConfirm` boolean - `skipResponse` boolean - `staticVariables` WorkflowStaticVariable[] - … - `metadata` WorkflowNodeMetadata, required — Node metadata. - … - `transitions` WorkflowTransition[] — Outgoing transitions to other nodes. - … - `position` WorkflowPosition, required — Canvas position of the node. - … - `parameters` WorkflowToolParameter[] - … - `timeout` integer — Timeout in milliseconds. - `extractVariables` WorkflowExtractVariablesConfig — Variable extraction config for a node. - … - `overrideResponse` boolean — Override the default response with `customResponse`. - `customResponse` string — Custom response shown instead of the default. Required when `overrideResponse` is true. Supports `{{variable}}` interpolation; may be empty. - `outputMapping` object — Maps tool output fields to workflow variables. - `onErrorBehavior` 'continue' | 'retry' | 'fail' - `errorMessage` string — Message spoken when the node errors. Supports `{{variable}}` interpolation; may be empty. - `processingMessage` string — Message spoken while the node runs. - `processingMessageType` 'static' | 'prompt' — Whether the message is a literal `static` string or a `prompt` for the LLM. - WorkflowWebToolNode — Web-tool execution node. - `id` string, required — Unique node id (nanoid or UUID). - `type` 'web_tool', required — Node type discriminator. - `label` string — Display label. - `description` string — Optional node description. - `isGlobal` boolean — Whether this is a global node. - `globalCondition` string — Condition that activates a global node. Supports `{{variable}}` interpolation; may be empty. - `globalConditionType` 'prompt' | 'dtmf' - `globalDtmfKey` '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '#' | '*' — DTMF key that triggers the global node when `globalConditionType` is `dtmf`. - `globalReturnToSource` boolean - `requiresDoubleConfirm` boolean - `skipResponse` boolean - `staticVariables` WorkflowStaticVariable[] - … - `metadata` WorkflowNodeMetadata, required — Node metadata. - … - `transitions` WorkflowTransition[] — Outgoing transitions to other nodes. - … - `position` WorkflowPosition, required — Canvas position of the node. - … - `processingMessage` string — Message spoken while the web tool runs. - `processingMessageType` 'static' | 'prompt' — Whether the message is a literal `static` string or a `prompt` for the LLM. - WorkflowTransferCallNode — Transfer the call to a phone number. - `id` string, required — Unique node id (nanoid or UUID). - `type` 'transfer_call', required — Node type discriminator. - `label` string — Display label. - `description` string — Optional node description. - `isGlobal` boolean — Whether this is a global node. - `globalCondition` string — Condition that activates a global node. Supports `{{variable}}` interpolation; may be empty. - `globalConditionType` 'prompt' | 'dtmf' - `globalDtmfKey` '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '#' | '*' — DTMF key that triggers the global node when `globalConditionType` is `dtmf`. - `globalReturnToSource` boolean - `requiresDoubleConfirm` boolean - `skipResponse` boolean - `staticVariables` WorkflowStaticVariable[] - … - `metadata` WorkflowNodeMetadata, required — Node metadata. - … - `transitions` WorkflowTransition[] — Outgoing transitions to other nodes. - … - `position` WorkflowPosition, required — Canvas position of the node. - … - `phoneNumber` string, required — Destination phone number (E.164). - `transferType` 'warm' | 'cold' - `transferMessage` string — Message spoken before transferring. Supports `{{variable}}` interpolation; may be empty. - `transferMessageType` 'static' | 'prompt' — Whether the message is a literal `static` string or a `prompt` for the LLM. - `timeout` integer — Timeout in milliseconds. - `sipHeaders` WorkflowSipHeader[] — Custom SIP headers to attach to the transfer. - … - WorkflowEndCallNode — End the call. - `id` string, required — Unique node id (nanoid or UUID). - `type` 'end_call', required — Node type discriminator. - `label` string — Display label. - `description` string — Optional node description. - `isGlobal` boolean — Whether this is a global node. - `globalCondition` string — Condition that activates a global node. Supports `{{variable}}` interpolation; may be empty. - `globalConditionType` 'prompt' | 'dtmf' - `globalDtmfKey` '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '#' | '*' — DTMF key that triggers the global node when `globalConditionType` is `dtmf`. - `globalReturnToSource` boolean - `requiresDoubleConfirm` boolean - `skipResponse` boolean - `staticVariables` WorkflowStaticVariable[] - … - `metadata` WorkflowNodeMetadata, required — Node metadata. - … - `transitions` WorkflowTransition[] — Outgoing transitions to other nodes. - … - `position` WorkflowPosition, required — Canvas position of the node. - … - `finalMessage` string — Final message before ending the call. Supports `{{variable}}` interpolation; may be empty. - `messageType` 'static' | 'prompt' — Whether the message is a literal `static` string or a `prompt` for the LLM. - `reason` 'completed' | 'user_requested' | 'error' | 'timeout' - WorkflowTransferAgentNode — Hand off to another voice agent. - `id` string, required — Unique node id (nanoid or UUID). - `type` 'transfer_agent', required — Node type discriminator. - `label` string — Display label. - `description` string — Optional node description. - `isGlobal` boolean — Whether this is a global node. - `globalCondition` string — Condition that activates a global node. Supports `{{variable}}` interpolation; may be empty. - `globalConditionType` 'prompt' | 'dtmf' - `globalDtmfKey` '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '#' | '*' — DTMF key that triggers the global node when `globalConditionType` is `dtmf`. - `globalReturnToSource` boolean - `requiresDoubleConfirm` boolean - `skipResponse` boolean - `staticVariables` WorkflowStaticVariable[] - … - `metadata` WorkflowNodeMetadata, required — Node metadata. - … - `transitions` WorkflowTransition[] — Outgoing transitions to other nodes. - … - `position` WorkflowPosition, required — Canvas position of the node. - … - `agentId` string, required — Target voice agent id. - `timeout` integer — Timeout in milliseconds. - `transferMessage` string — Message spoken before handing off. Supports `{{variable}}` interpolation; may be empty. - `transferMessageType` 'static' | 'prompt' — Whether the message is a literal `static` string or a `prompt` for the LLM. - `handoffConversation` boolean — Pass the conversation transcript to the target agent. - `handoffVariables` boolean — Pass workflow variables to the target agent. - WorkflowRouterNode — Routes to a branch based on its transitions. - `id` string, required — Unique node id (nanoid or UUID). - `type` 'router', required — Node type discriminator. - `label` string — Display label. - `description` string — Optional node description. - `isGlobal` boolean — Whether this is a global node. - `globalCondition` string — Condition that activates a global node. Supports `{{variable}}` interpolation; may be empty. - `globalConditionType` 'prompt' | 'dtmf' - `globalDtmfKey` '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '#' | '*' — DTMF key that triggers the global node when `globalConditionType` is `dtmf`. - `globalReturnToSource` boolean - `requiresDoubleConfirm` boolean - `skipResponse` boolean - `staticVariables` WorkflowStaticVariable[] - … - `metadata` WorkflowNodeMetadata, required — Node metadata. - … - `transitions` WorkflowTransition[] — Outgoing transitions to other nodes. - … - `position` WorkflowPosition, required — Canvas position of the node. - … - WorkflowSetLocalVariablesNode — Sets local/static variables (see base `staticVariables`). - `id` string, required — Unique node id (nanoid or UUID). - `type` 'set_local_variables', required — Node type discriminator. - `label` string — Display label. - `description` string — Optional node description. - `isGlobal` boolean — Whether this is a global node. - `globalCondition` string — Condition that activates a global node. Supports `{{variable}}` interpolation; may be empty. - `globalConditionType` 'prompt' | 'dtmf' - `globalDtmfKey` '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '#' | '*' — DTMF key that triggers the global node when `globalConditionType` is `dtmf`. - `globalReturnToSource` boolean - `requiresDoubleConfirm` boolean - `skipResponse` boolean - `staticVariables` WorkflowStaticVariable[] - … - `metadata` WorkflowNodeMetadata, required — Node metadata. - … - `transitions` WorkflowTransition[] — Outgoing transitions to other nodes. - … - `position` WorkflowPosition, required — Canvas position of the node. - … - WorkflowChangeAgentSettingsNode — Overrides agent settings mid-flow. - `id` string, required — Unique node id (nanoid or UUID). - `type` 'change_agent_settings', required — Node type discriminator. - `label` string — Display label. - `description` string — Optional node description. - `isGlobal` boolean — Whether this is a global node. - `globalCondition` string — Condition that activates a global node. Supports `{{variable}}` interpolation; may be empty. - `globalConditionType` 'prompt' | 'dtmf' - `globalDtmfKey` '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '#' | '*' — DTMF key that triggers the global node when `globalConditionType` is `dtmf`. - `globalReturnToSource` boolean - `requiresDoubleConfirm` boolean - `skipResponse` boolean - `staticVariables` WorkflowStaticVariable[] - … - `metadata` WorkflowNodeMetadata, required — Node metadata. - … - `transitions` WorkflowTransition[] — Outgoing transitions to other nodes. - … - `position` WorkflowPosition, required — Canvas position of the node. - … - `settingsOverrides` object — Agent-setting overrides applied at this node. Stored as-is and not field-validated (mirrors agent-level config). - `edges` WorkflowEdge[], required — Edges connecting nodes in the builder canvas. - `id` string, required — Edge id (nanoid or UUID). - `source` string, required — Source node id. - `target` string, required — Target node id. - `sourceHandle` string - `targetHandle` string - `type` string — Edge render type (custom ReactFlow types like `deletable` are allowed). - `selected` boolean — Canvas selection state. - `animated` boolean - `hidden` boolean - `metadata` object - `transitionId` string - `label` string - `style` object - `customVariables` WorkflowVariable[] — Workflow-level variables available across nodes. - `id` string, required — Variable id — nanoid or author slug (e.g. `out_var_flights`). - `name` string, required — Variable name (snake_case). - `description` string - `dataType` 'string' | 'number' | 'boolean' | 'integer' | 'array' | 'object', required - `enumValues` WorkflowEnumValue[] - `value` string, required - `label` string - `isEnumEnabled` boolean - `isRequired` boolean - `defaultValue` unknown - `extractionPrompt` string - `sourceNodeId` string - `sourceNodeType` string - `properties` WorkflowVariable[] — Child variables (for `object` types). - `item` WorkflowVariable — recursive - `outcomeResponseShape` object, nullable — Expected outcome response structure - `resolvedWebTools` object[], nullable — Resolved web tools with overrides applied - `createdAt` string, date-time - `updatedAt` string, date-time - `account` object — User account plan information - `plan` string, nullable ## Other responses - `400` — Bad request - `401` — Unauthorized - `403` — Forbidden - not authorized to access this voice agent - `404` — Voice agent not found - `500` — Server Side Error --- [API](https://skmtc.net/tryhamsa/apis/hamsa-api.md) · [All operations](https://skmtc.net/tryhamsa/apis/hamsa-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryhamsa/hamsa-api/versions/ecbeb5d8dc13/schema)