In-conversation Actions

Design actions the agent can invoke on demand during a live conversation. Each action can launch a visual flow where you can respond to the customer (Say) and call external APIs (API Request), then pass results back to the agent.

​

Overview

• When it runs: On-demand based on what the customer asks for (e.g. “check order status”).
• Action definition: Provide name, description, and optional parameters the AI should collect from the customer.
• Flow: Each action can launch a flow composed of nodes that respond and call APIs, returning variables the agent can use to reply.

​

Create an In-conversation Action

1. Open Studio → Build → AI Agents → Actions tab → In-conversation.
2. Click “Create New Action” and configure:
   • Name and Description (clear, intent-focused wording helps the AI)
   • Parameters (optional):
     • Name, Description, Type (String, Number, List), Required flag
     • Use descriptions to specify format and examples the AI should gather
3. Save the action, then choose Save & Edit Flow to open the Flow Builder.

​

Flow Builder

The flow defines what happens when this action is invoked. Drag nodes from the sidebar and connect them starting from the Start node.

• Variables: You can reference variables from Pre-conversation Actions and from previous nodes in the same flow. Saved values become available to subsequent nodes and to the agent when it next replies.
• Filler messages: Use a Say node to keep the customer informed while an API request is in progress.
• Find a node: In a large flow, use the search box in the top-right of the canvas to jump to any node by name or type — see Find a Node on the Canvas.

​

Say Node

Deliver a message to the customer — spoken on a call, sent as a message in chat — with support for variables and language-specific content.

• Message (Default): Main text to deliver. Supports variables like {{firstName}}.
• Language-specific messages: Optionally tailor messages per language. If not provided, the default message is used.
• Variables support: Insert variables using the variable picker. You can use:
  • Pre-conversation variables (e.g. contact details)
  • Variables created earlier in the flow

Use cases:

• Provide confirmations, prompts, or interim updates while waiting on API calls.
• Share results from previous nodes (e.g. “Your order {{orderId}} is on the way.”)

​

API Request Node

Call an external HTTP API and map response fields to variables. Configuration (same capabilities as Pre-conversation API requests):

• Method: GET, POST, PUT, DELETE, PATCH
• URL: Static URL (e.g. https://api.example.com/orders/)
• Query Params: Key-value pairs, variable-aware
• Headers: Static or variable-aware (e.g. Authorization)
• Body: JSON body for non-GET methods; variables supported
• Auth Profile: Optional reusable credentials profile — see Auth Profiles for details. Also supports mTLS for APIs that require certificate-based mutual authentication.
• Test Request: Use “Send” to preview response in Data or Meta tabs

Response handling:

• Inspect the response preview, then map JSON paths to variables.
• Saved variables become available to downstream nodes and to the agent’s next turn.

Tips:

• Use a preceding Say node as a filler message while the request runs.
• Keep payloads minimal and map only the fields you need.

​

Set Variable Node

Assign or overwrite a variable value at any point in the flow without making an API call.

• Variable: Choose an existing variable or create a new one.
• Value: Enter a static value or reference another variable (e.g. {{orderId}}).

Use cases:

• Store a computed or default value mid-flow (e.g. set transferReason before a handoff).
• Overwrite a Pre-conversation variable with updated information gathered during the conversation.

​

Decision Node

Add conditional branching to your flow based on variable values or expressions.

• Condition: Define one or more conditions that evaluate variables (e.g. {{accountStatus}} == "active").
• Branches: The node provides True and False output paths. Connect each path to the appropriate downstream nodes.

Use cases:

• Route the flow differently based on customer data (e.g. VIP vs. standard customer).
• Skip an API call when a required variable is missing.
• Gate actions behind boolean checks from Data Transformers.

​

Find a Node on the Canvas

Large flows are easier to navigate with the search box in the top-right corner of the canvas.

• Search by name or type: Type any part of a node’s name, or a node type such as decision or api, to match every node of that kind. Matching is case-insensitive. Node contents — prompt text, URLs, variable values — are not searched.
• See every match at once: Every matching node on the canvas is ringed in amber while the search is active.
• Jump to a node: Pick a result to pan and centre the canvas on it. Moving through the results with the arrow keys previews each node the same way.
• Restore your view: Clearing or dismissing the search returns the canvas to exactly where it was.

​

Visibility & Logging

Every in-conversation action execution is automatically recorded:

• Live Transcript: Action invocations and results appear inline alongside the conversation, so you can follow along in real time.
• Action Logs: A detailed log of each action execution—including decision node outcomes—is kept with the conversation record for review after it ends. For calls you will find it in Call History.

​

Best Practices

• Start with simple flows: Say -> API Request -> Say.
• Use descriptive parameter names and clear descriptions to help the AI collect inputs reliably.