Configure the TextBotExchange Action

The TextBotExchange action sends the contact's messages to AI Agents (Cognigy) and receives the bot's responses. It also provides output variables and branch conditions that your script uses to determine what happens next. Configure the action properties as described in this task.

Required permissions: Studio Script View, Create/Edit

In the Studio script, click Actions in the right panel.
Expand the Web Editor URL category.
Drag the TextBotExchange action onto the script canvas. Place it after the action that collects the contact's input.
If your script requires more than one turn, add a second TextBotExchange action and connect it into the conversation loop. A minimum of two TextBotExchange action is required for most implementations.
Before the first TextBotExchange action, add a Snippet action and configure it with the Bot Session State snippet code. This snippet initializes the botSessionState variable that maintains conversation context across turns.

Input Properties

Select the TextBotExchange action and configure the following input properties in the Properties panel. Use the table below to understand each property:

Property	Acceptable value or FORMAT	Description
Caption	Short, descriptive label. Example: TextBotExchange_CognigyStart	Identifies this specific action on the Studio canvas. The default is "TEXTBOT EXCHANGE". Enter a unique caption when your script contains more than one TextBotExchange action.
Virtual Agent ID	Auto-populated after you assign the bot in the Virtual Agent Hub. Value equals the Virtual Agent (Bot) Name from Virtual Agent Hub.	Identifies the Virtual Agent Hub configuration to use. This field is populated automatically when you assign the bot to the action in Virtual Agent Hub. You can override this value by using a Studio variable, for example, {virtualAgentId} if you need to dynamically select the bot configuration at runtime. This approach is commonly used when switching between multiple bot configurations.
Automated Intent	Standard string: Welcome. Used only on the first turn.	Triggers a specific intent in AI Agents (Cognigy) instead of sending the contact’s typed input. This field can be used to invoke predefined intents such as Welcome or any other supported intent in the bot. While it is commonly used on the first turn to trigger a welcome message, it can also be used on subsequent turns to invoke other intents dynamically. Leave this field empty when you want to pass the contact’s actual message instead.
User Input	Studio variable that holds the contact's typed message. Example: {customerMessage}	The text message typed by the contact, passed to AI Agents (Cognigy) for intent recognition and response generation. On the first turn, this field can be empty if automatedIntent is set to Welcome. On each subsequent turn, this field must contain the contact's latest utterance.
Custom Payload	JSON object converted to string. Example: {customPayload.asJSON()}. Optional.	Passes custom contextual data from the Studio script to AI Agents (Cognigy). Examples include contact name, account ID, or CRM data. You must define the custom payload object in a Snippet action. Don't use this property if you need to process data that the virtual agent returns to the script. Instead, use the customPayloadVarName (out) variable.
Bot Session State	Variable populated by botSessionStateVarName (out) from the previous turn. Example: {botState}	Maintains conversation context across turns by passing a session identifier back to AI Agents (Cognigy) with each request. AI Agents (Cognigy) creates this identifier on the first turn. On all subsequent turns, the script must pass the value stored in Don't use this property if you need to process data that the virtual agent returns to the script. Instead, use the customPayloadVarName (out) variable back into this field. If you do not configure this correctly, AI Agents (Cognigy) creates a new session on every turn and loses context.

Output Properties

The following output properties are available after the TextBotExchange action executes. Reference these variables in subsequent actions in your script.

Property	Acceptable value or FORMAT
Next Prompt Var Name (out)	Holds the behavior settings that control how NiCE CXone prompts the contact on the next conversational turn. This variable can be modified in a Snippet action before the next TextBotExchange call to customize per-turn behavior.
Custom Payload Var Name (out)	Returns custom JSON data from AI Agents (Cognigy) back to the Studio script. Use this property to process fulfillment data or routing instructions sent by AI Agents (Cognigy). Common values include: escalat or any intent starting with escalat, such as "escalate" or "escalation" — Routes the contact to a live agent. The Studio script detects this prefix to handle escalation reliably across different bot intent names. end — Ends the interaction. The Studio script uses this value to terminate the contact session cleanly. Do not confuse this with the customPayload input property.
Error Details Var Name (out)	Contains error information when the OnError branch is taken. Inspect this variable in the OnError branch to log or handle the error. The _ERR system variable is also populated with a condensed error description.
Intent Info Var Name (out)	Contains details about the intent identified by AI Agents (Cognigy) for the current turn. Use this variable in your script to log intent data or make routing decisions based on the identified intent.
Bot Session State Var Name (out)	Holds the session state identifier returned by AI Agents (Cognigy) after each turn. You must pass the value of this variable into the botSessionState input property on the next turn to maintain conversation context. This property is required for correct operation.