--- title: "Update Text Pearl" method: PUT path: "/v2/Pearl/Text/{pearlId}" tags: ["Pearl"] --- # Update Text Pearl `PUT /v2/Pearl/Text/{pearlId}` Updates a text Pearl. Only the provided parts are updated: pearl replaces the whole conversation flow (send the complete node graph), inbound/outbound partially update the channel settings (only the fields present in the JSON are applied; when TextChannelId is omitted, the current channel is kept). Omitted parts are kept unchanged. The Pearl must be a text Pearl (AgentType = Text). The update applies to the published version of the Pearl: if several versions exist on the platform, only the currently published one is modified. For more details, click [here](/api-reference/building_a_flow). ## Path parameters - `pearlId` string, required ## Request body - UpdateProjectTextApiRequest - `name` string, nullable — The updated name of the Pearl. - `pearl` AdvancedTextPearlApi — Configuration of a text Pearl: a graph of nodes driven by a text agent over a messaging channel (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. - `agentName` string, nullable — The display name of the agent in the conversation. - `variables` DataSettingsApi[], nullable — Variables that can be defined, stored, and used by the agent during conversations. Used together with Pearl. 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` InboundTextSettingsPatchApi — Partial update of the inbound settings of a text Pearl: only the fields present in the JSON are applied. - `totalAgents` Int32OptionalType - `hasValue` boolean - `value` integer - `transcriptOptions` ETranscriptOptionsOptionalType - `hasValue` boolean - `value` integer — `1 - FullTranscript` `2 - SensitiveInfoRemoved` `3 - NoTranscript` - `callWebhookUrl` StringOptionalType - `hasValue` boolean - `value` string, nullable - `textChannelId` StringOptionalType - `hasValue` boolean - `value` string, nullable - `maxTurns` Int32NullableOptionalType - `hasValue` boolean - `value` integer, nullable - `autoCloseAfterInactivityHours` Int32NullableOptionalType - `hasValue` boolean - `value` integer, nullable - `inactivityFollowUps` InactivityFollowUpListOptionalType - `hasValue` boolean - `value` InactivityFollowUp[], nullable - `delayMinutes` integer — Delay (in minutes) of customer inactivity before this follow-up is sent. - `message` string, nullable — Optional custom follow-up message. When empty, the agent generates one from the conversation context. Max 1000 characters only. - `outbound` OutboundTextSettingsPatchApi — Partial update of the outbound settings of a text Pearl: only the fields present in the JSON are applied. - `totalAgents` Int32OptionalType - `hasValue` boolean - `value` integer - `transcriptOptions` ETranscriptOptionsOptionalType - `hasValue` boolean - `value` integer — `1 - FullTranscript` `2 - SensitiveInfoRemoved` `3 - NoTranscript` - `budgetTotal` Int32NullableOptionalType - `hasValue` boolean - `value` integer, nullable - `timeZone` StringOptionalType - `hasValue` boolean - `value` string, nullable - `callingHours` DayWorkingHoursListOptionalType - `hasValue` boolean - `value` DayWorkingHours[], nullable - `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` StringOptionalType - `hasValue` boolean - `value` string, nullable - `leadWebhookUrl` StringOptionalType - `hasValue` boolean - `value` string, nullable - `textChannelId` StringOptionalType - `hasValue` boolean - `value` string, nullable - `maxTurns` Int32NullableOptionalType - `hasValue` boolean - `value` integer, nullable - `autoCloseAfterInactivityHours` Int32NullableOptionalType - `hasValue` boolean - `value` integer, nullable - `inactivityFollowUps` InactivityFollowUpListOptionalType - `hasValue` boolean - `value` InactivityFollowUp[], nullable - `delayMinutes` integer — Delay (in minutes) of customer inactivity before this follow-up is sent. - `message` string, nullable — Optional custom follow-up message. When empty, the agent generates one from the conversation context. Max 1000 characters only. ## Response `200` The Pearl was updated successfully. - boolean ## 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)