Workflows

A workflow is a set of instructions the AI follows when it recognizes a specific situation. Think of it as a playbook — when a customer asks to cancel an order, track a shipment, or report a damaged product, the workflow tells the AI exactly what to do.

Workflows are different from Articles and Bot Rules:

• Articles provide information the AI can reference (like an FAQ)
• Bot Rules set short behavioral guidelines (like "always greet in Spanish")
• Workflows define structured, step-by-step processes — often with actions that connect to your systems

Priority: When a workflow, article, and rule all apply to the same situation, the workflow always wins.

---

When to use a workflow

Use a workflow when the AI needs to:

• Follow a defined process (e.g., "Customer reports a damaged order")
• Trigger an action (e.g., cancel an order, fetch tracking info, process a refund)
• Make decisions based on data (e.g., check order status before responding)

Don't use a workflow if:

• You just want to add information the AI can reference → use an Article
• You need a short behavioral rule → use a Bot Rule

---

How the system works

When a customer sends a message, here's what happens:

1. The AI recognizes the situation matches a workflow's trigger
2. If the workflow has a condition provider, it runs to evaluate external state (e.g., is the order shipped? is the subscription active?)
3. The system picks the first matching variant based on the conditions
4. The AI follows that variant's instructions, calling actions as needed

Most workflows are simple — one set of instructions, no condition provider. You only add variants and condition providers when the same situation needs different handling depending on external state.

---

Structure of a workflow

Title

Give the workflow a short, descriptive name — something anyone can understand at a glance.

• Order tracking
• Cancel order
• Damaged product
• Shipping cost inquiry

Avoid vague names like "Order issue" or "Customer request."

---

Trigger — "When should this flow be followed?"

Describe when the AI should use this workflow. Write it like you're giving directions to a teammate — short, plain, and based on what the customer says or does.

• When a customer asks to cancel their order.
• When a customer reports receiving a damaged product.
• When a customer wants to check their shipping cost.

Keep it to a few sentences. Be specific, and avoid overlaps with other workflows.

---

Actions (optional)

Actions let the AI do things — not just reply. They connect your workflow to external systems so the AI can fetch order details, process refunds, check stock, calculate shipping costs, and more.

When creating a workflow, select the actions you want the AI to use. In the instructions, reference actions by name where they should run.

Actions come in two types: API actions for simple HTTP calls, and Python actions for anything that needs logic.

→ Learn about Custom Actions

---

Bot instructions

This is the playbook the AI follows. Write it like directions to a teammate — short, explicit, step-by-step.

How to write great instructions:

• Be linear. Number each step. One action or decision per step.
• Confirm first. Collect the minimum details before acting (e.g., email, order ID).
• Name actions. On the step where work happens, include the action name (e.g., getOrderDetails).
• Handle branches. Use clear if/else for common cases (found/not found, in/out of policy).
• Close the loop. Tell the customer what you did or what will happen next.
• Fail safe. If blocked or facing a policy exception, hand off with transferConversation.

---

Variants

By default, a workflow has one variant — one set of instructions that always runs. This is enough for most use cases.

But sometimes the same situation needs different handling depending on external state. For example, a "Cancel Order" workflow might need different responses depending on whether:

• The order has already shipped
• The order was already refunded
• The payment was through a specific provider

Variants let you define multiple instruction sets within a single workflow. Each variant has a set of required conditions — boolean flags that must all be true for that variant to be selected.

Variants are ordered by priority. The system checks them top to bottom and picks the first match. The last variant typically has no conditions and acts as the fallback.

Example: Cancel Subscription

To power variants with real data, you need a condition provider — a script that evaluates external state and returns the boolean conditions the system uses to pick a variant.

→ Learn about Condition Providers

---

Examples

Simple: Escalation to a human

A minimal workflow — no actions, no condition provider, just instructions.

• Trigger: Customer explicitly asks to speak to a person
• Variants: 1 (default)
• Instructions:
  1. Collect the customer's email address
  2. Ask for a brief summary of their issue
  3. Call transferConversation

---

Medium: Order tracking

A workflow that calls an external API to fetch data.

• Trigger: Customer asks about their order status
• Variants: 1 (default)
• Actions: getOrderDetails
• Instructions:
  1. Ask for the order ID (or email if no ID available)
  2. Call getOrderDetails with the order ID
  3. Share the order status, items, and tracking link
  4. If no tracking info is available yet, explain that the order is being processed
  5. If the order can't be found, ask the customer to double-check the ID

---

Advanced: Cancel order with retention

A multi-variant workflow that adapts based on order state.

• Trigger: Customer wants to cancel their order
• Condition provider: Checks order status via your API
• Actions: cancelOrder, processPartialRefund
• Variants: