Pre-conversation Actions

Configure visual flows that run before your agent says or writes anything. Use flow nodes to fetch CRM data, initialize variables, or run conditional checks before the conversation begins.

​

Overview

• When it runs: Before the agent’s first message.
• Execution order: Multiple pre-conversation actions run sequentially in creation order.
• Variable scope: Variables created here are available through the entire interaction. They can also personalize the Greeting message (voice and chat) and Guidelines, which are filled in after pre-conversation actions have run.

​

Create a Pre-conversation Action Flow

1. Open Build → AI Agents, open your agent, then select the Pre-conversation Actions card under Actions & Integrations.
2. Select Create New Action and fill in:
   • Name: Short, descriptive identifier. It must be different from every other action on the agent, across its pre-, in- and post-conversation actions, ignoring capital letters and surrounding spaces. A name that’s already taken is refused with a message naming the action that has it.
   • Description: What the action does and why
   • Execute on channels: Which channels the action runs on — Voice, Chat or Email, in any combination (at least one must be selected). New actions start with Voice only.
3. Select Save & Edit Flow to save the action and open the Flow Builder in one step. Create (or Save Changes when you’re editing an action) saves the action and closes the drawer instead.

To open a flow again later, select Go to Flow on the action’s card. Each card also shows the channels the action runs on, and its menu lets you edit, duplicate, copy to another agent or delete the action — see AI Agents for duplicating and copying.

​

Channel Scoping

Pre-conversation actions can be scoped to run only on specific channels. An action runs only on the channels ticked under Execute on channels. An action scoped to Voice is skipped for chat and email conversations, and an action scoped to Email runs for email agents but is skipped on calls and chats — useful when a CRM lookup only makes sense for callers, or a chat conversation needs different preparation.

• Existing and newly created actions default to Voice only. If your agent also handles chat or email, tick Chat or Email under Execute on channels on each action that should run there; otherwise it’s skipped on that channel.
• On an email thread, pre-conversation actions run once, on the customer’s first email and before the agent writes its first reply. See Email Agents.
• To branch within a shared flow instead, use the built-in interaction.CHANNEL variable (resolves to voice, chat or email) in a Decision node.

​

Flow Builder

The flow defines what happens before the conversation starts. Drag nodes from the node palette on the left, grouped as Flow Control (Decision) and Actions (API Request, Set Variable), and drop each one on the Drop to connect area under the node it should follow, starting from the Start node. You don’t draw connections by hand. A node dropped in the middle of a chain is inserted there. Dropping a Decision node opens its settings first, and the nodes under a Decision are chosen in its Go To Node fields. Click a node to change its settings, or right-click it to edit or delete it (the Start node can’t be deleted). The flow saves automatically when you add, change or delete a node, and shows Flow saved. Save Flow at the top right saves it again. In a large flow, use the search box in the top-right of the canvas to jump to a node by name or type — see Find a Node on the Canvas. A saved action and its flow are part of the agent’s draft. On an agent you’ve published, live calls, chats and emails keep running the flow as it was published until you Publish again, while Talk and Chat use your latest changes (see What Waits for Publish).

​

API Request Node

Call an external HTTP API and map response fields to variables:

• Method: GET, POST, PUT, DELETE, PATCH
• URL: The endpoint. You can include variables, e.g. https://api.example.com/crm/{{customerId}}.
• Query Params: Key-value pairs, variable-aware (the Params tab)
• Headers: Static or variable-aware (e.g. Authorization)
• Body: Choose a Body Type of None, JSON, Text, XML or x-www-form-urlencoded (a table of key-value pairs). Variables supported. Body Type is locked to None when the method is GET. When you change the type, Studio adds, updates or removes the matching Content-Type header for you and shows a message, so check the Headers tab afterwards. For how variables are sent in a JSON body, see API Request Node.
• Auth: Either tick Use Auth Profile and pick a reusable credentials profile — see Auth Profiles for details, including mTLS for APIs that require certificate-based mutual authentication — or leave it unticked and set up Bearer Token, API Key, Basic Auth or OAuth 2.0 right in the node (None sends no credentials).
• Test Request: Use Send to preview the response in the Data or Meta tabs
• JSON Path Expressions: Under the response, click a value in the Data or Meta view to add its path, or type one such as $.data.user.name. Pick a Variable for each path (e.g. save firstName to {{firstName}}). Built-in variables such as interaction.ANI or agent.TIMEZONE, and campaign variables, can’t be used as the target, and every path needs a variable before the node can be saved. An optional Default Value is used when the path isn’t found in the response or is empty.

​

Set Variable Node

Assign or overwrite variable values at any point in the flow without making an API call. One node can set several variables.

• Add Variable: Adds another assignment to the node. Each assignment has a Variable and a Transformation Logic.
• Variable: Choose an existing variable or create a new one. Built-in call variables, system variables and campaign variables can’t be set with this node, so they aren’t offered.
• Transformation Logic: Choose how the value is worked out.
  • Static Value: Enter a fixed value or reference another variable (e.g. {{status}}). It can’t be left empty.
  • A data transformer: Every saved Data Transformer is listed after Static Value. Pick one, then fill in each of its inputs, which can include variables. The result is saved to the variable.

​

Decision Node

Add conditional branching to your flow based on variable values:

• Condition: Select Add Condition for each one. A condition has a Condition Rule, the Input Values to test, and a Go To Node. The Condition Rule is one of your saved Data Transformers, and the condition matches when that transformer returns true. Create the transformer you need first, because the list shows only saved ones.
• Branches: Each condition routes to its own downstream node, and Otherwise catches everything that matches none of them. Conditions are checked from top to bottom, and the first one that returns true wins. Otherwise also needs a Go To Node, and the node can’t be saved without one.

For example, to treat VIP customers differently, create a Data Transformer called Is VIP with one Compare step: set its Input to {{input1}}, Operator to Equal To and Value to true. In the Decision, add a condition, choose Is VIP as the Condition Rule, and enter {{vipStatus}} as the value for input1. Then choose the node that handles VIP customers under Go To Node. Compare is case sensitive by default, so a vipStatus of True doesn’t equal true. Untick Case sensitive on the step if your system’s capitalization can vary.

​

Best Practices

• Keep pre-conversation flows minimal and optimized, so the agent’s first message is not held up.
• Map only the fields you need from your backend to simplify variable usage.
• Use consistent, readable variable names (e.g. customerFirstName, orderId).