--- title: "Get conversational Agent" method: GET path: "/v1/conversational-agents/{agentId}" tags: ["Conversational Agents"] --- # Get conversational Agent `GET /v1/conversational-agents/{agentId}` ## Request - Base URL: `https://api.sigmamind.ai` - URL: `https://api.sigmamind.ai/v1/conversational-agents/{agentId}` - Auth: API key in header `X-API-Key` Get a conversational agent, along with agent settings ## Path parameters - `agentId` string, required ## Response `200` OK - ConversationalAgentResponse - `agentId` string: The unique identifier of the agent within the system. - `agentName` string: Human-readable name of the agent used to identify it in the dashboard and APIs. - `startNodeName` string: The name of the node where the agent workflow starts. - `startNodeId` string: The unique identifier of the node where the agent workflow starts. - `agentSettings` CreateAgentSettingsResponse: Configuration settings that define the agent’s runtime behavior, including voice, llm model and other operational settings. - `language` string: The language your customers will primarily speak during calls. - `aiStartsConversation` boolean: If true the AI agent will initiate the conversation immediately when the call connects. If false the call will connect silently, waiting for the customer to speak first before the AI responds - `backgroundSound` 'keyboard_typing' | 'office_ambience' | 'none': Add ambient background audio during the call. - `globalPrompt` string: A global system prompt that is applied to every conversation to define the agent’s overall behavior, tone, and constraints. - `remindersIntervalDuration` integer: Interval (in seconds) after which a follow-up reminder is automatically sent if the user does not respond. - `remindersLimit` integer: Maximum number of follow-up reminders to send when the user does not respond.Set to 0 to disable reminders. - `endCallOnSilenceDuration` number, float: Specifies the duration of continuous silence (in minutes) after which the call will be automatically ended. - `maxCallDuration` integer: Maximum call duration (in minutes) before the call is automatically terminated. - `llmModel` string: The language model that powers the AI's responses. - `llmTemperature` number, double: Controls randomness in the model's output. Lower values make responses more deterministic; higher values make them more creative. If not provided, the default value is derived from the selected llmModel. - `llmTopP` number, double: Controls how diverse the output is by selecting from the most probable tokens within a probability limit. Lower values make responses more focused. If not provided, the default value is derived from the selected llmModel. - `llmTopK` integer: Limits token selection to the top-k most probable tokens. Lower values make output more deterministic; higher values increase variation. If not provided, the default value is derived from the selected llmModel - `voiceId` string: This is the AIs speaking voice id. - `voiceModelId` string: This is the AIs text to speech engine version. - `ttsSpeed` number, double: Controls the speech playback speed. Lower values make speech slower; higher values make it faster. If not provided, the default value is derived from the selected voiceModel. - `ttsTemperature` number, double: Controls variation in speech delivery. Lower values make speech more consistent; higher values add more expressiveness. If not provided, the default value is derived from the selected voiceModel. - `ttsVolume` number, double: Controls the output audio volume. Lower values make it quieter; higher values make it louder. If not provided, the default value is derived from the selected voiceModel. - `aiStartsSpeakingPlan` number, double: How quickly AI starts speaking after user input. - `aiStopsSpeakingPlan` number, double: How quickly AI stops speaking when interrupted. - `ivrHangup` boolean: Determines whether the call should be automatically disconnected when an IVR system is detected during the call. - `agentTimezone` string: The timezone of the agent in IANA format. Used to contextualize time-sensitive responses and scheduling. - `autoVolumeNormalization` boolean: If true, it keeps the user's microphone volume consistent regardless of distance or loudness. - `backgroundNoiseFilter` boolean: If true, it removes hums, buzzes, and rumbles from the audio signal. - `echoCancellation` boolean: If true, it stops the AI's audio from looping back into the microphone. - `enablePostConversationAnalysis` boolean: Indicates whether post-conversation analysis should be performed to extract insights after the conversation ends. - `postConversationAnalysisLlmModel` string: The language model that powers the AI's post-conversation analysis. - `postConversationAnalysis` PostConversationAnalysisRequest[]: List of configurations defining what insights should be extracted after the conversation ends. - `insightName` string, required: A Unique name of the insight that will be generated from the conversation. - `insightInstructions` string, required: Instructions or prompt that define how the insight should be generated from the conversation. - `dataType` 'string' | 'boolean' | 'number' | 'selector', required: Defines the expected data type of the generated insight result. - `options` string[]: List of allowed selectable values. Required only when dataType is selector. - `webhooks` WebhookConfigResponse[]: List of webhook configurations that define external endpoints to be notified on specific events. - `webhookId` string: A unique identifier for the webhook. - `name` string: Human-readable name for this webhook. Used to identify it in listings and dashboards. Does not need to be unique, but a descriptive name helps distinguish multiple webhooks on the same agent. - `url` string: HTTPS endpoint that will receive event payloads as HTTP POST requests. Must be publicly reachable. The system expects an HTTP 2xx response within the configured timeout to confirm delivery. Non-2xx responses or timeouts are treated as delivery failures. - `secret` string: Secret key used to authenticate webhook payloads. This key should be securely stored and verified on the receiving server. - `events` string[]: Set of event types that will trigger a delivery to this webhook. 'conversation_started' fires when an agent session begins. 'conversation_ended' fires when a session closes. 'conversation_analysed' fires when post-call analysis is complete. At least one event must be specified. Only events in this set will be sent — all others are silently ignored. - `nodes` AgentNodeResponse[] - union - object: Sends a response to the user before continuing to the next node in the workflow. - `nodeId` string: Unique identifier of the node. - `nodeName` string: Human-readable name of the node. Must be unique within the agent and contain only letters, numbers, and underscores. - `nodeType` 'message': Type of the node - `edge` Edge - `nextNodeId` string: The unique identifier of the node to execute next. - `nextNodeName` string: The name of the node to execute next. - `parameters` MessageNodeParameters: Configuration parameters that define the message content and how its instructions are provided. - `instructionsType` 'static' | 'prompt': Specifies how the message instructions are defined, such as static text or dynamically generated instructions. - `instructions` string: The instructions or message content to be delivered to the user. - object: Runs a sub-agent with its own instructions and tools, and continues the workflow based on its configured exit conditions. - `nodeId` string: Unique identifier of the node. - `nodeName` string: Human-readable name of the node. Must be unique within the agent and contain only letters, numbers, and underscores. - `nodeType` 'sub_agent': Type of the node, which determines its behavior and available configuration. - `parameters` SubAgentNodeParameters: Configuration parameters that define the behavior of the sub-agent. - `instructions` string: Instructions that define the behavior and objective of the sub-agent. - `edges` SubAgentEdge[]: The exit conditions and destination nodes used to continue the workflow when the exit condition satisfies. - `exitCondition` string: The condition that determines when the sub-agent should exit and continue to the next node. It can be natural language or a javascript expression. - `nextNodeId` string: The unique identifier of the node to execute after the sub-agent exits. - `nextNodeName` string: The name of the node to execute after the sub-agent exits. - `tools` CreateToolResponse[]: Tools available to the sub-agent during execution. - union - object: Transfers the active voice call to another number - … - object: Extracts and stores named variables from the conversation - … - object: This tool is used to navigate through IVR. - … - object: Ends the current voice call - … - object: Triggers an action from a connected app (e.g. Shopify, HubSpot) - … - object: Evaluates conditions and routes the conversation to the next node based on the matching condition. Condition can be in natural language or it can be a javascript expression - `nodeId` string: Unique identifier of the node. - `nodeName` string: Human-readable name of the node. Must be unique within the agent and contain only letters, numbers, and underscores. - `nodeType` 'if_else': Type of the node - `edges` ConditionEdge[]: The conditional branches evaluated by the node, each specifying a condition and its destination node. For the else branch, pass the condition as "ELSE". - `condition` string: The condition that determines whether this branch should be selected. It can be natural language or a javascript expression. - `nextNodeId` string: The unique identifier of the node to execute when the condition is satisfied. - `nextNodeName` string: The name of the node to execute when the condition is satisfied. - object: Evaluates a global condition and routes the conversation to the configured destination node when the condition is met. - `nodeId` string: Unique identifier of the node. - `nodeName` string: Human-readable name of the node. Must be unique within the agent and contain only letters, numbers, and underscores. - `nodeType` 'global_condition': Type of the node - `edge` ConditionEdge: The condition and destination node used to determine the next step in the workflow. - `condition` string: The condition that determines whether this branch should be selected. It can be natural language or a javascript expression. - `nextNodeId` string: The unique identifier of the node to execute when the condition is satisfied. - `nextNodeName` string: The name of the node to execute when the condition is satisfied. - object: Transfers the active voice call to another number - `nodeId` string: Unique identifier of the node. - `nodeName` string: Human-readable name of the node. Must be unique within the agent and contain only letters, numbers, and underscores. - `nodeType` 'voice_transfer_call': Type of the node - `parameters` TransferCallNodeParameters: Configuration parameters that define the destination and behavior of the call transfer. - `transferToRouting` 'static' | 'dynamic': Defines how the destination for the call transfer is determined. Use 'static' to always transfer to a fixed phone number. Use 'dynamic' to determine the destination at runtime based on conditions or extracted variables (e.g., user intent such as OPD, radiology, etc.). - `transferTo` string, required: Destination for the call transfer. If transferToRouting is 'static', provide a valid E.164 formatted phone number. If transferToRouting is 'dynamic', provide instructions or a dynamic variable placeholder to resolve the destination at runtime. For example: If the user wants to connect with OPD, transfer to {{dynamic_variable}} or a specific number. If the user wants to connect with radiology, transfer to {{dynamic_variable}} or a specific number. - `extensionNumber` string: Optional extension number to dial after the call is transferred. This is typically used in IVR systems to reach a specific department or user. - `transferSettings` TransferSettings: Configuration for the call transfer behaviour - `transferType` 'warm' | 'cold', required: Type of transfer to perform. 'warm' keeps the current agent connected during the transfer, while 'cold' disconnects the agent immediately after initiating the transfer. - `ringingDuration` integer: Specifies the maximum duration (in seconds) to wait for the call to be answered. - `waitForParticipantAnswer` boolean: If true, agent will wait for the new participant to answer the call. - `enableWhisperMessage` boolean: If true, a whisper message will be played privately to the destination participant before the caller is connected. - `whisperMessage` string: The content of the whisper message. Its interpretation depends on whisperMessageType. If the type is 'static', this text is played directly. If the type is 'prompt', the text is treated as a prompt that the system uses to dynamically generate the whisper message. - `whisperMessageType` 'static' | 'prompt': Defines how the whisperMessage should be interpreted. 'static' means the message is used as-is, while 'prompt' means the message is treated as a prompt for generating the final whisper message. - `enableThreeWayMessage` boolean: If true, a message will be delivered once the call becomes a three-way conversation between the caller, the current agent, and the destination participant. - `threeWayMessage` string: The content of the message delivered during the three-way connection. Its interpretation depends on threeWayMessageType. If 'static', the message is used directly. If 'prompt', it is treated as a prompt for generating the final message. - `threeWayMessageType` 'static' | 'prompt': Defines how the threeWayMessage should be interpreted. 'static' means the message is used as-is, while 'prompt' means the message is treated as a prompt for generating the final message. - `customHeaders` object: Send custom header key and values along with call transfer. - `edge` Edge - `nextNodeId` string: The unique identifier of the node to execute next. - `nextNodeName` string: The name of the node to execute next. - object: Extracts and stores named variables from the conversation - `nodeId` string: Unique identifier of the node. - `nodeName` string: Human-readable name of the node. Must be unique within the agent and contain only letters, numbers, and underscores. - `nodeType` 'extract_variables': Type of the node - `edge` Edge - `nextNodeId` string: The unique identifier of the node to execute next. - `nextNodeName` string: The name of the node to execute next. - `parameters` ExtractVariablesNodeParameters: Configuration parameters defining the variables to extract from the conversation. - `variables` Variable[]: List of variables to extract from the conversation - `variableName` string, required: Name of the variable - `dataType` 'text' | 'boolean' | 'number' | 'dateTimeIso8601': Data type of the variable to be extracted. - `description` string, required: Description of what this variable represents - object: This is used to navigate through IVR. - `nodeId` string: Unique identifier of the node. - `nodeName` string: Human-readable name of the node. Must be unique within the agent and contain only letters, numbers, and underscores. - `nodeType` 'ivr_navigator': Type of the node - `parameters` IvrNavigatorNodeParameters: Configuration parameters that control how the agent interacts with an IVR system. - `ivrStartsConversation` boolean: Indicates whether the call is initiated by an IVR (Interactive Voice Response) system. Set to true when the interaction begins with an automated IVR prompt before connecting to an agent or system flow. - `pauseDelay` integer: Specifies the duration (in milliseconds) to wait before assuming the IVR system has finished its input or prompt. This delay helps ensure that subsequent actions are triggered only after the IVR interaction is complete. - `edge` Edge - `nextNodeId` string: The unique identifier of the node to execute next. - `nextNodeName` string: The name of the node to execute next. - object: Ends the current voice call - `nodeId` string: Unique identifier of the node. - `nodeName` string: Human-readable name of the node. Must be unique within the agent and contain only letters, numbers, and underscores. - `nodeType` 'voice_end_call': Type of the node - `edge` Edge - `nextNodeId` string: The unique identifier of the node to execute next. - `nextNodeName` string: The name of the node to execute next. - object: Triggers an action from a connected app (e.g. Shopify, HubSpot) - `nodeId` string: Unique identifier of the node. - `nodeName` string: Human-readable name of the node. Must be unique within the agent and contain only letters, numbers, and underscores. - `nodeType` 'integration_tool': Type of the node - `parameters` IntegrationToolsNodeParameters: Configuration parameters that define the integration tool execution. - `toolId` string: The specific tool to execute - `speakWhileWaiting` boolean: If enabled, the agent will provide filler or holding speech while waiting for the tool to respond - `placeholders` object: Defines values for the placeholders expected by the integration tool. Each key represents a placeholder name and its value can either be a static value or a dynamic variable using the format {{variable_name}} to inject runtime data. - `mapVariables` object: Maps the response paths of the tool to dynamic variables. Each key is the variable name and the value is the mapped response path - `edge` Edge - `nextNodeId` string: The unique identifier of the node to execute next. - `nextNodeName` string: The name of the node to execute next. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `500`: Internal Server Error ## Changes - **2026-11-03** `64c0435b10eb`: 1 info - endpoint added [Operation history](https://skmtc.dev/sigmamind/apis/sigmamind-apis/changes/v1/conversational-agents/:agentId/get.md) --- [API](https://skmtc.dev/sigmamind/apis/sigmamind-apis.md) - [All operations](https://skmtc.dev/sigmamind/apis/sigmamind-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/sigmamind/apis/sigmamind-apis/revisions/783c9e4c5126?raw)