> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squawkvoice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pre-conversation Actions

> Fetch and prepare context before the conversation begins, powered by flows

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.

> [!WARNING]
>
> The **Greeting message** (voice and chat) and Guidelines are filled in once, after the pre-conversation actions have run. An email agent has no **Greeting message**, so this applies to its Guidelines. They can use variables set by pre-conversation actions, the built-in call variables (`{{interaction.ANI}}`, `{{interaction.DNIS}}`, `{{interaction.CALL_SID}}`, `{{interaction.CURRENT_DATE}}` and `{{interaction.CHANNEL}}`), agent-level variables, campaign contact variables, chat widget variables, and any variable that has a [Default value](/build/ai-agents#default-values). A value that an In-conversation or Post-conversation Action sets later isn't added to them.
>
> In the variable picker for the voice **Greeting message** and Guidelines, a variable you created yourself on the agent appears once a pre-conversation action sets it. Each field offers only the built-in variables that make sense there — see [Built-in variables](/build/ai-agents#built-in-variables).

## 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](/build/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](/build/ai-agents/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](/build/ai-agents/in-conversation-actions#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](/build/ai-agents#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](/build/ai-agents/in-conversation-actions#api-request-node).
* **Auth**: Either tick **Use Auth Profile** and pick a reusable credentials profile — see [Auth Profiles](/manage/auth-profiles) for details, including [mTLS](/manage/auth-profiles#mtls-client-certificate) 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.

> [!NOTE]
>
> The URL must be a publicly reachable `http://` or `https://` address. Addresses on a private or internal network, such as `localhost`, `10.x.x.x` or `192.168.x.x`, and link-local addresses are refused, and so are hostnames that can't be resolved. This applies to **Send** as well as to the request when the action runs.

### 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](/build/data-transformers) 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](/build/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.

> [!NOTE]
>
> A **Decision** the [Co-pilot](/build/squawk-copilot) adds arrives with its **Otherwise** path unconnected, because these flows can't hold a **Say** step to fill it. Connect it yourself in the editor, or ask the Co-pilot to.

> [!NOTE]
>
> Pre-conversation flows do not support **Say** nodes, because they run before the customer reaches the agent. The **AI Context** node isn't offered here either.

## 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`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.