--- title: "Create Voice Pearl" method: POST path: "/v2/Pearl/Voice" tags: ["Pearl"] --- # Create Voice Pearl `POST /v2/Pearl/Voice` Creates a new voice Pearl: the conversation is driven by a graph of nodes connected by transitions. The graph must contain one OpeningSentence node (or a PreCallAPI leading to one or two OpeningSentence nodes), one EndCall node, and every node must be reachable. Provide exactly one channel: inbound settings OR outbound settings. At least one agent voice is required; to retrieve available voices, use the Get Voices endpoint (GET /v2/Account/Voices). The Pearl is created already published: the configuration you send becomes its live (published) version. For more details, click [here](/api-reference/building_a_flow). ## Request body - AddProjectVoiceApiRequest - `name` string, nullable — The name of the Pearl. - `pearl` AdvancedVoicePearlApi — Configuration of a voice Pearl: a graph of nodes driven by voice agents (unlike a Simple Pearl, which is driven by a single opening sentence and flow script). - `agentPersonality` string, nullable — Defines the agent's personality and tone (for example, more assertive or more calm). Constraints: - Max length: 35 characters. - `timeZone` string, nullable — Time zone identifier used by the Pearl's agents. The agent will operate according to this time zone, regardless of the lead/customer local time zone. For accepted values, refer to the [Windows Time Zones list](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/default-time-zones?view=windows-11). Example: "Pacific Standard Time", "Romance Standard Time". - `modelType` integer — Agent model type. Voice Pearls use one of these models: - Trident: Default, highest-quality model with standard rate. Optimized for natural, human-like interactions. - Oyster: Most cost-effective model (2 credits cheaper per minute). Straightforward, prioritizes simplicity and efficiency. - Arrow: High-intelligence model with the same depth as Trident, built for ultra-low latency (fastest). Costs 2 credits more per minute. - Hydra: Smartest model, built for demanding tasks that need deeper reasoning. Costs 2 credits more per minute. Text Pearls use: - Swan: the model dedicated to text agents (chat and messaging conversations). It is the only model available for text Pearls. Swan is not available for voice Pearls, and the voice models are not available for text Pearls. `1 - Trident` `2 - Oyster` `3 - Arrow` `4 - Hydra` `11 - Swan` - `companyName` string, nullable — The company name used by the agent during conversations. Constraints: - Max length: 100 characters. - `companyDescription` string, nullable — The company description used by the agent during conversations. Constraints: - Max length: 500 characters. - `generalInstructions` string, nullable — General behavior guidelines applied to the agent across the whole conversation, on top of the per-node scripts and instructions (for example a tone to keep or rules that always apply). Constraints: - Max length: 2,500 characters. - Cannot contain variables. - `knowledgeBase` string, nullable — Knowledge base content provided to the agent, such as FAQs, internal context, and operational instructions. Constraints: - Max length: 20,000 characters. - `memory` boolean, nullable — Indicates whether memory is enabled. When enabled, the Pearl can remember previous conversations for a given phone number. - `successDescription` string, nullable — Description of what makes a conversation successful. Used to evaluate and report the conversation outcome. Constraints: - Max length: 200 characters. - `indicatorTags` CallLabelApi[], nullable — Indicator tags used to classify conversations (name, description and color). Constraints: - Max entries: 10. - Colors must be unique across tags. - `id` string, nullable — Identifier of the label. If not provided, it will be generated automatically. Important: - The ID is the stable identifier of the label. - Changing the ID creates a new label. - Keeping the same ID while updating the name/description updates the existing label. Constraints: - Exactly 6 characters. - Letters only (A–Z, a–z). - `name` string, nullable — The label name. Max 25 characters only. - `description` string, nullable — Describes when this label should be applied. Max 250 characters only. - `color` integer — `1 - purple` `2 - red` `3 - yellow` `4 - green` `5 - blue` `6 - pink` `7 - teal` `8 - lime` `8 - gradient1` `9 - gradient2` - `nodes` NodeApi[], nullable — The nodes of the conversation graph. Each node has a unique NodeId and its transitions reference the NodeId of the target node. The entry point is determined automatically: the PreCallAPI node if present, otherwise the OpeningSentence node. Constraints: - Exactly one OpeningSentence node (or one PreCallAPI leading to one or two OpeningSentence nodes). - Exactly one EndCall node, and every path must be able to reach it. - Every non-start node needs at least one incoming transition (except a TransferCall node, which may be left unwired and is then fired by the agent from its trigger description). - `nodeId` string, nullable — Unique identifier of the node within the flow. Transitions reference this value as their target. Optional: a node may be authored with only a name, in which case the id is derived from it server-side. - `name` string, nullable — Display name of the node. - `nodeType` integer — The type of a node in a Pearl's conversation flow. It determines what the node does and which settings object it carries. - OpeningSentence: the first message the agent sends to start the conversation. - PreCallAPI: an API call executed before the conversation starts (for example a customer lookup). Its transitions use apiResult to branch on success or failure. - Dialogue: a scripted node where the agent converses with the customer. - HandoffChatToHuman: hands the conversation over to a human operator. Text Pearls only. - API: an API call executed during the conversation. - SMS: sends an SMS message. - Email: sends an email. - TransferCall: transfers the call to another phone number. Voice Pearls only. - StartCallRecording: starts recording the call from this point. Voice Pearls only. This node carries no settings. - SearchKnowledgeBase: searches the agent's knowledge base and returns the answer. - EndCall: terminates the conversation. Exactly one per flow, and every path must lead to it. - PostCallActions: a container whose nested actions run after the conversation ends. `2 - OpeningSentence` `3 - PreCallAPI` `10 - Dialogue` `31 - HandoffChatToHuman` `40 - API` `50 - SMS` `51 - Email` `60 - TransferCall` `65 - StartCallRecording` `80 - SearchKnowledgeBase` `100 - EndCall` `200 - PostCallActions` - `transitions` TransitionApi[], nullable — Outgoing transitions of the node. Each transition has a name describing the condition that triggers it and the NodeId of the target node (the transition id is generated server-side from the name). On a PreCallAPI node, every transition must set apiResult (Success or Failure) and must lead to an OpeningSentence node. - `name` string, nullable — `🧩 May support variables` The condition that triggers this transition (for example "the customer asks for a human agent"). Must be unique within the node: the transition id is generated from it server-side. Post-call variables are not allowed here. - `toNodeId` string, nullable — The NodeId of the target node. - `apiResult` integer — The outcome of the pre-call API request that fires this transition. Allowed only on the transitions of a PreCallAPI node, where every transition must set it: Success leads to the opening sentence used when the pre-call API succeeds, Failure to the one used when it fails. `1 - Success` `2 - Failure` - `script` string, nullable — `🧩 May support variables` The script the agent follows while in this node (for OpeningSentence and Dialogue nodes). - `instructions` string, nullable — `🧩 May support variables` Free-form instructions that guide the agent's behavior in this node. - `apiSettings` NodeAPISettingsApi — API call configuration of an API or PreCallAPI node. There is no trigger description here: the node runs when a transition leads to it. - `name` string, nullable — A friendly name for this API action. Max 50 characters only. - `method` integer — `1 - GET` `2 - POST` `3 - PUT` `4 - DELETE` `5 - PATCH` - `endpointUrl` string, nullable — `🧩 May support variables` The endpoint URL to call. Max 4,000 characters only. Variables support depends on the node: on a PreCallAPI node only pre-call variables are available, while on an API node pre-call and in-call variables are available. - `body` APIDataSchemaPropertyApi[], nullable — Request body definition (key/value pairs) for this API call. Constraints: - Only applicable for POST, PUT, or PATCH. - Must be empty for GET, DELETE (and any method that does not send a body). - `key` string, nullable — The request body field name (JSON key). Max 255 characters only. - `variableId` string, nullable — The variable ID to send as the value for this field (without curly braces). Constraints: - If VariableId is provided, Type and Value must be null/empty. - `type` integer — `1 - String` `2 - Long` `3 - Double` `4 - Boolean` `5 - DateOnly` `6 - TimeOnly` `7 - DateTime` - `value` string, nullable — `🧩 May support variables` The static value to send for this field. Constraints: - Max 255 characters. - Must be provided together with Type when VariableId is not provided. - Must not be provided when VariableId is provided. - When Type is String, the value may include variables using curly braces. - `required` boolean — Indicates whether this request body field is required. - `headers` object, nullable — Optional HTTP headers to include in the API request. - `description` string, nullable — A short description of what this API action does. Max 150 characters only. - `outputBody` APIDataSchemaPropertyApi[], nullable — Maps fields of the API response onto flow variables, so the values returned by the API can be used later in the conversation. - `key` string, nullable — The request body field name (JSON key). Max 255 characters only. - `variableId` string, nullable — The variable ID to send as the value for this field (without curly braces). Constraints: - If VariableId is provided, Type and Value must be null/empty. - `type` integer — `1 - String` `2 - Long` `3 - Double` `4 - Boolean` `5 - DateOnly` `6 - TimeOnly` `7 - DateTime` - `value` string, nullable — `🧩 May support variables` The static value to send for this field. Constraints: - Max 255 characters. - Must be provided together with Type when VariableId is not provided. - Must not be provided when VariableId is provided. - When Type is String, the value may include variables using curly braces. - `required` boolean — Indicates whether this request body field is required. - `credentialId` string, nullable — Optional ID of a credential used to authenticate the API call. To retrieve the credentials available to a Pearl, use the Get Pearl Credentials endpoint (GET /v2/Pearl/Credential/{pearlId}). - `smsSettings` NodeSMSTemplateApi — SMS configuration of an SMS node. There is no trigger description here: the node runs when a transition leads to it. - `body` string, nullable — `🧩 May support variables` The SMS message content. Constraints: - Max 2,000 characters. - Supports pre-call and in-call variables. Inside a PostCallActions container, post-call variables are also supported. - `emailSettings` NodeEmailTemplateApi — Email configuration of an Email node. There is no trigger description here: the node runs when a transition leads to it. - `to` string[], nullable — List of primary recipients. Constraints: - Max 10 recipients. - Max 255 characters per email address. - `cc` string[], nullable — List of CC recipients. Constraints: - Max 10 recipients. - Max 255 characters per email address. - `subject` string, nullable — `🧩 May support variables` Email subject. Constraints: - Max 150 characters. - Supports pre-call and in-call variables. Inside a PostCallActions container, post-call variables are also supported. - `body` string, nullable — `🧩 May support variables` Email body content. Constraints: - Max 100,000 characters. - Supports pre-call and in-call variables. Inside a PostCallActions container, post-call variables are also supported. - `smtpSettings` SmtpSettings - `id` string, nullable — Optional SMTP configuration identifier. - `provider` integer — `1 - Gmail` `2 - Office365` `10 - Custom` - `smtpServer` string, nullable — SMTP server hostname. - `port` integer, nullable — SMTP server port. - `enableSsl` boolean, nullable — Indicates whether SSL/TLS is enabled for the SMTP connection. - `senderEmail` string, nullable — Sender email address used for SMTP authentication and as the "From" address. - `senderPassword` string, nullable — Sender password or SMTP credential used for authentication. - `displayName` string, nullable — Display name shown in the recipient inbox (the "From" name). - `transferCallSettings` TransferCallSettingsApi - `transferCallPhoneNumber` string, nullable — `🧩 May support variables` The destination phone number to transfer the call to. If a variable is used, it must resolve to a valid phone number, otherwise the transfer will fail. Max 25 characters only. - `triggerDescription` string, nullable — Instructions describing when the agent should transfer the call (for example, when the caller asks to speak with a human). Max 500 characters only. In a Simple Pearl, this field is required. In a Pearl (node graph), it depends on how the TransferCall node is reached: required when the node has no inbound transition (the agent fires the transfer based on this description), and not allowed when the node is reached by transitions (the flow decides when the transfer happens). - `warmTransferMessage` string, nullable — `🧩 May support variables` Optional warm transfer message spoken by the agent when the transfer starts. If empty, warm transfer is disabled. Max 2,000 characters only. - `handOffAction` NodeApi[], nullable — Notification actions fired when the conversation is handed off to a human. Allowed only on a HandoffChatToHuman node (text Pearls only). Each entry is a node object, with the same fields as the items of `nodes`, whose type is an action: SMS, Email, or API (with the matching settings object). These nested nodes are fire-and-forget actions: they cannot have transitions, nor nested lists of their own. - `postCallActions` NodeApi[], nullable — Actions executed after the conversation ends. Allowed only on a PostCallActions node, which acts as the container of these actions and is not connected to the rest of the graph. Each entry is a node object, with the same fields as the items of `nodes`, whose type is an action: SMS, Email, or API (with the matching settings object). These nested nodes are fire-and-forget actions: they cannot have transitions, nor nested lists of their own. - `agents` AgentConfigToAddApi[], nullable — Agents configured for the Pearl. - Each agent represents a language-specific entry point (based on the selected voice). - Configure multiple agents to support multilingual experiences and language-based transfers. Constraints: - Voice language must be unique across agents (no duplicates). - `name` string, nullable — The display name of the agent. Constraints: - Max length: 50 characters. - `voiceId` string, nullable — The ID of the voice to use for this agent. To retrieve available voices, see: [Get Voices](/api-reference/v2/pearlSettings/get-voices) Constraints: - The voice language must be unique across agents in the same Pearl (no two agents can use voices from the same language). - `speechRecognitionKeywords` VocabularyEntry[], nullable — Keywords configured to improve speech recognition accuracy (for example product names, acronyms, or domain-specific terms). - `word` string, nullable — The keyword to recognize in speech recognition. - Max length: 50 characters. - `pronunciations` string[], nullable — Alternative pronunciations for the keyword. Constraints: - Max elements: 3. - Each pronunciation max length: 50 characters. - `variables` DataSettingsApi[], nullable — Variables that can be defined, stored, and used by the agent during conversations. For details on variable groups and how to use variables in supported fields, see: [Flow Variables](/api-reference/flow_variables) - `id` string, nullable — Variable identifier. This is the ID you must reference when using the variable in scripts and templated fields. It must not contain spaces. Constraints: - Max 40 characters. - Allowed characters: letters (A–Z, a–z), digits (0–9), underscore (_), hyphen (-). - `name` string, nullable — Friendly display name for the variable. Max 40 characters only. - `group` integer — Variable group. - PreCall: Variables available before the call (used in pre-call contexts such as opening sentence or pre-call API). - InCall: Variables collected or updated during the call. - PostCall: Variables generated after the call by the platform (cannot be created via the API). `1 - PreCall` `2 - InCall` `3 - PostCall` - `type` integer — `1 - String` `2 - Long` `3 - Double` `4 - Boolean` `5 - DateOnly` `6 - TimeOnly` `7 - DateTime` - `isList` boolean — Indicates whether the variable can contain multiple values (list) or a single value. - `description` string, nullable — Guidance for the agent on how to collect or infer this variable during the conversation. Max 300 characters only. - `value` string, nullable - `options` OptionChoice[], nullable — Optional predefined choices for this variable (allowed/preset values). Notes: - Use Value for the human-readable label. - Use Code for an optional internal/normalized value to store or send to integrations. - `value` string, nullable — The option value (human-readable label). If Code is empty, this value is also used for display. - `code` string, nullable — Optional display/encoded value for the option. Use this to store a mapped value (for example a normalized code, an internal identifier, or a hex color). - `inbound` InboundVoiceSettingsApi — Inbound settings of a voice Pearl. - `totalAgents` integer — Total number of agents allocated to this inbound activity. - `transcriptOptions` integer — `1 - FullTranscript` `2 - SensitiveInfoRemoved` `3 - NoTranscript` - `callWebhookUrl` string, nullable — Optional webhook URL to receive call events (for example call started and call ended). - `phoneNumberId` string, nullable — The phone number ID to use for this Pearl. To retrieve available phone numbers, see: [Get Phone Numbers](/api-reference/v2/pearlSettings/get-phones) Constraints: - A phone number cannot be assigned to more than one active inbound Pearl at the same time. - `recordingOptions` boolean — Enables or disables call recording. - `isStopRecordingAfterTransferCall` boolean, nullable — Indicates whether recording should continue after a call is transferred. - `waitingSentence` string, nullable — Message played to the caller when no agent is available and the caller is waiting in the queue. Max 300 characters only. - `isSayQueueDetails` boolean — When enabled, the caller is informed about queue details (for example how many callers are ahead) while waiting. - `outbound` OutboundVoiceSettingsApi — Outbound settings of a voice Pearl. - `totalAgents` integer — Total number of agents allocated to this outbound activity. - `transcriptOptions` integer — `1 - FullTranscript` `2 - SensitiveInfoRemoved` `3 - NoTranscript` - `budgetTotal` integer, nullable — Total budget allocated for the outbound activity. If null, the outbound activity runs without a budget limit. - `timeZone` string, nullable — Default time zone for the outbound activity. Leads are called according to this time zone unless a lead-specific time zone is provided when adding leads. For accepted values, refer to the [Windows Time Zones list](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/default-time-zones?view=windows-11). Example: "Pacific Standard Time", "Romance Standard Time". - `callingHours` DayWorkingHours[], nullable — Allowed calling hours for the outbound activity. - `day` integer — `0 - Sunday` `1 - Monday` `2 - Tuesday` `3 - Wednesday` `4 - Thursday` `5 - Friday` `6 - Saturday` - `start` string, date-span — Start time of the allowed calling window (based on the campaign time zone). Constraints: - Must be before End. - `end` string, date-span — End time of the allowed calling window (based on the campaign time zone). Constraints: - Must be after Start. - `callWebhookUrl` string, nullable — Optional webhook URL to receive call events (for example call started and call ended). - `leadWebhookUrl` string, nullable — Optional webhook URL to receive lead events (for example lead created/updated). - `phoneNumberId` string, nullable — The phone number ID to use for this Pearl. To retrieve available phone numbers, see: [Get Phone Numbers](/api-reference/v2/pearlSettings/get-phones) - `recordingTrack` integer — `1 - Pearl` `2 - Inbound` `3 - Both` `4 - None` - `isStopRecordingAfterTransferCall` boolean, nullable — Indicates whether recording should continue after a call is transferred. - `maximumCallAttempts` integer — Maximum number of call attempts per lead. Constraints: - Max 5 attempts. - `minimumRetryIntervalHours` integer — `1 - Every6Hours` `2 - OnceADay` `3 - OnceEvery3Days` `4 - OnceAWeek` `5 - OnceAMonth` `6 - Every3Hours` - `voiceMail` string, nullable — `🧩 May support variables` Voicemail message left when a voicemail/answering machine is detected. If empty, the agent will not leave voicemails. - `bypassIVRInstruction` string, nullable — `🧩 May support variables` Instructions used to bypass IVR (Interactive Voice Response) systems. - `ringDuration` integer, nullable — Ringing duration (in seconds) before considering the call unanswered. Constraints: - Min 10 seconds. - Max 50 seconds. - `callTimeout` integer, nullable — Maximum call duration (in minutes). The call is ended when this limit is reached. Constraints: - Min 1 minute. - Max 120 minutes. ## Response `200` The ID of the newly created Pearl. - string ## Other responses - `400` — Error --- [API](https://skmtc.net/nlpearl/apis/nlpearl-client-api.md) · [All operations](https://skmtc.net/nlpearl/apis/nlpearl-client-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nlpearl/nlpearl-client-api/versions/52d64fc5d6e9/schema)