Step reference

Overview

Playbooks use structured steps to guide AI Agents through multi-step workflows. Each step represents a discrete action the Agent performs during a conversation — sending a message, setting a variable, asking a question, running an action, branching on a condition, or jumping to another step.

Steps are organized into sections, which represent stages of the end user journey (for example, “Verify identity” or “Process refund”). Within each section, steps execute sequentially unless redirected by an IF/ELSE branch or a GO TO jump.

A Playbook also has General Guidelines that apply across all sections, providing the Agent with global context, tone guidance, and knowledge references.

Step types

The following step types are available when authoring Playbooks.

Step details

SEND

Sends a message to the end user. Use SEND steps to communicate information, provide instructions, confirm actions, or acknowledge end user input.

SEND has two modes:

Fixed message

Sends the exact message you author. The authored text is fixed — the Agent delivers your wording verbatim rather than generating new content. This is the key difference from Contextual AI-generated mode, where the Agent composes a new message from an instruction.

Contextual AI-generated

The Agent generates a response based on the instruction you provide and the conversation context. Use this mode when the message should adapt to the situation rather than follow a fixed script.

Usage guidance:

• Use SEND to provide context between backend operations (SET, RUN) so end users are not left waiting in silence.
• Reference variables inline to personalize messages (for example, “Your order @order_id has been submitted.”).
• Attach images inline using the @ menu. Images are delivered deterministically — the Agent sends the exact image you select at authoring time. Supports JPEG, PNG, and GIF. See Media for supported channels and details.

SET

Assigns a variable value without prompting the end user. SET operates in one of two modes: Exact value or Use reasoning. Neither mode asks the end user anything.

Exact value

Assigns a literal value, a reference to another variable, or a math expression. Select the target variable, then provide the value.

• The value is known at build time.
• Setting one variable equal to another variable.
• Computing a value with a math expression.
• Use the value "NONE" to clear a variable (not an empty string).

Use reasoning

Silently extracts a value from the conversation using AI reasoning. The Agent reads the transcript and infers the value based on the instruction — it does not prompt the end user.

Select the target variable and provide an instruction describing what to extract. Optionally configure:

• Accepted values: A list of allowed values. Constrains extraction to only these values. Pair with accepted values whenever the variable is used in a downstream IF/ELSE branch.
• Fallback value: The value written when extraction fails or no accepted value matches. Set a fallback whenever the variable is used downstream.

When to use reasoning mode:

• Classifying or inferring a value from the conversation without prompting the end user.
• Pair with accepted values whenever the result feeds into an IF/ELSE branch.
• Set a fallback value at all times if the variable needs to exist downstream.
• Start with normal reasoning effort; switch to high effort if adherence drops.

Example — extracting data from an Action response:

1. RUN @get_order_details to retrieve order information.
2. SET (Use reasoning) @order_status with instruction: “Extract the order status from the action response” and accepted values: ["shipped", "processing", "canceled", "returned"], fallback: "unknown".
3. IF/ELSE branch on @order_status.

ASK

Asks the end user for a value during the conversation. The Agent prompts the end user, extracts their response, and saves it to a variable. ASK has two modes:

Capture exact response

Captures direct input from the end user and saves it verbatim to one or more variables. Use this mode for straightforward inputs where you need the end user’s exact words — for example, first name, last name, email address, or order number.

This mode can set multiple variables at once from a single end user response. Each variable is configured as an input with its own extraction instructions and capture mode.

Input fields:

Map the answer using reasoning

Uses AI reasoning to interpret the end user’s response and map it to a value. Use this mode for inferred intents, preferences, or situations where the value is not a direct transcription — for example, mapping “I’d like a two-hour appointment” to a preference variable.

This mode sets one variable per step.

Retry behavior: By default, the Agent re-asks up to 4 times. If the end user does not provide a valid value after all attempts, the variable is set to the author-configured fallback value if one is set, otherwise the variable is left untouched. You can change the number of attempts using the Max re-ask attempts field.

Configuration options:

• When to ask: only_when_needed (default) — extract from the transcript first and ask only if the value is missing. always — skip extraction and always prompt the end user.
• Question phrasing: contextual (default) — the Agent phrases the question naturally based on context. exact_words — the Agent uses the verbatim text you provide.
• Accepted values: A list of allowed values. Restricts extraction to these values.
• Max re-ask attempts: The maximum number of times the Agent re-asks the end user for a valid response before giving up. Accepts an integer from 1 to 20. When left empty, the system default of 4 attempts is used.

When to use each mode:

• Capture exact response: For simple, direct inputs where you don’t know the value in advance — first name, email, account number.
• Map using reasoning: For complicated inferred intents or preferences, or when setting a variable to a known value based on interpretation (for example, mapping a preference to “two-hour appointment”).

Example — verifying end user identity:

1. ASK (Capture exact response) @account_email — “Ask for the email address associated with their account.”
2. RUN @verify_identity with @account_email as input.
3. IF/ELSE branch on verification result.

RUN

Executes an Action, Handoff, linked Playbook, or Exit. RUN connects the Playbook to external systems and escalation paths. Each RUN step targets exactly one of:

• Action: Execute an API call or integration.
• Handoff: Escalate the conversation to a human agent.
• Linked Playbook: Call another Playbook. The parent pauses, the child runs to completion, then control returns.
• Exit: Deterministically end the Playbook.

Action error handling

When an Action returns a 4xx or 5xx HTTP status code, you can build custom fallback behavior.

Pattern:

1. RUN the Action.
2. SET (Exact value) a variable from the Action response’s HTTP status code.
3. IF/ELSE to check the status code.
4. In the error branch, add recovery steps (retry, send a message, handoff).

Example:

1. RUN @submit_refund.
2. SET @refund_status_code = action response status.
3. IF/ELSE: if @refund_status_code is 200, SEND “Your refund has been processed.” Otherwise, SEND “We’re having trouble processing your refund. Let me connect you with a specialist.” then RUN @handoff_to_support.

IF/ELSE

Branches the flow based on conditions. Each branch contains its own sequence of steps that execute when the branch’s conditions evaluate to true. An optional default (else) branch handles cases where no conditions match.

Flat conditions

The simplest form — a list of conditions evaluated together with a single logical operator.

Example — branching on subscription status:

• IF @subscription_status is active: SEND refund options.
• ELSE IF @subscription_status is canceled: SEND reactivation instructions.
• ELSE: RUN @handoff_to_support.

Multi-group conditions (nested AND/OR)

For complex logic that requires mixing AND and OR operators, branches support nested condition groups. Each group contains its own operator, conditions, and optionally nested sub-groups.

Condition group fields:

Example — (A AND B) OR (C AND D):

groups: [
  { operator: "AND", conditions: [A, B] },
  { operator: "AND", conditions: [C, D] }
]
operator: "OR"

This evaluates to: (condition A AND condition B) OR (condition C AND condition D).

Example — VIP escalation with multiple criteria:

• IF (@account_tier is vip AND @issue_severity is high) OR (@account_tier is enterprise): RUN @escalate_priority.
• ELSE: continue standard flow.

GO TO

Jumps to a specific step by its ID, redirecting the flow within or across sections. Use GO TO to create loops, retry patterns, or non-linear workflows.

When to use GO TO:

• Redirecting to a shared error-handling section.
• Retrying a step after a failed validation.
• Implementing loops (for example, re-asking after invalid input).
• Skipping ahead when early conditions are met.

Condition operators

The following operators are available in IF/ELSE conditions.