How do I set up the Loop step?

What is it for?

“Loop” runs the same steps for each item in a list. The step has two exits: “For each item” and “When done”.

Visitors don't see this step and the avatar doesn't say anything; the agent carries on without waiting for the visitor.

To add it, click “Add step” on the “Flow” tab, then click “Loop” in the “Logic” category; the step is added in the middle of the canvas. Its settings are on the “Content” tab of the step panel that opens on the right when you click the step.

This step has no “On-screen text”; instead there's a “Step note” at the bottom of the panel. The note is just for you: visitors don't see it, and it isn't spoken or translated.

In values you use variables from earlier steps, like {city}. For a field inside an answer, add the field's name after a dot: {order.status}. The “Insert variable” button in the boxes lists the variables you can use at that point. A variable that hasn't been filled yet counts as empty text.

Setting up the step

1. Choose a source in “Where the items come from” and enter the items (see below).
2. Enter a “Variable name” (e.g. service). Each round, that round's item is written to this variable.
3. Connect the steps to run for each item to the “For each item” exit. Leave the exit of the last step on the branch empty: when the branch ends, the next item starts. You can also connect the last step back to the Loop step yourself.
4. Connect the step to go to once the items run out to the “When done” exit.

Where the items come from

• “List in a variable”: write a list variable in “List”: a multiple-choice answer, a tool's or action's list, or an Edit List result.
• “Items you type”: one round per row; add rows with “Add item”. Rows can include variables too.
• “Number range”: “Start”, “End” and “Step” (1 if empty). The end is included; use a negative step (-1) to count down. The values can be variables too: {guests}.
• “Split text”: the “Text” is split at the “Separator”: “Comma”, “Semicolon”, “Each line”, “Vertical bar (|)” or “Other” (a character of your own). Each part is one round; empty parts are skipped. “Trim spaces” removes the spaces at the start and end of each part.

Variables written each round

If the variable name is service, each round writes: {service} the item, {service.field} a field of the item, {service_index} the round number, {service_total} the number of items, {service_last} whether it's the last round (true/false). These variables are removed when the loop ends. “Counter starts at” sets the value of {service_index} in the first round (1 by default), and “Maximum rounds” the most items processed; a number range has neither setting.

Rounds and the steps on the branch

A loop runs at most 100 rounds; the rest of a longer list isn't processed. If the list is empty, the agent goes straight to “When done”. If you connect a step on the branch to a step after “When done”, the agent leaves the loop early; an End step on the branch ends the conversation. Loops can be nested: if the inner loop's “When done” exit is empty, the outer loop moves on to its next item.

You can put steps the visitor sees on the branch too (Message, Question, Form). An Integration Action or Tool Call on the branch runs separately each round: “create a card for each item” creates one card per item. The answer to a question on the branch is written to the same variable every round; each new answer replaces the previous one.

Example

In a “Multiple” Selection step, the visitor ticked the services they're interested in, and the answer is in {services}. In the Loop, “Where the items come from” is “List in a variable”, “List” is {services} and “Variable name” is service. An Integration Action on the “For each item” exit sends your team a separate notification for each service (“New application for {service}”); the “When done” exit goes to a thank-you Message.

Things to watch out for

The editor warns you when: the items aren't set; the number range is invalid (start, end and step must be numbers, and the step can't be 0); the variable name is invalid (up to 50 characters); “For each item” isn't connected (the loop won't run anything); or “When done” isn't connected (the flow ends once the items run out). Empty exits of steps on the branch don't raise a warning: they lead back to the loop.

Variable names can only use the letters a–z, digits and underscores (_); accented letters and spaces drop out as you type. “system” is reserved for system variables, so pick another name.

Logic steps don't wait for the visitor. If you connect them (or other steps that don't wait, such as Message, Tool Call or Integration Action) in a ring, the agent keeps going round: the editor warns “In a loop that never waits for the visitor; the flow gets stuck here.”, and in the conversation the agent ends with an error. To repeat something, use the Loop step, or put a step that waits for the visitor (Question, Selection, Form) in the ring.

Problems don't stop you saving: the agent is saved, but the incomplete step won't work as expected in the conversation. Fix the flagged steps, then try the agent with “Preview”. To find flagged steps, see the flow editor.