How a workflow starts

Choose what starts a workflow by itself, when it stays quiet, how often and for whom it runs, and every way to start it yourself.

Where you set it

Open the workflow in the builder and click the first card on the canvas, headed Starts when. The panel How this workflow starts opens with these fields:

Starts when
select required
What starts the workflow by itself: one of the nine triggers below. A box under the list explains the chosen trigger, and the trigger's own fields (such as Minutes or Event name) appear right after it. If you pick another trigger and then switch back, what you had set comes back.
How often
select
How many times the workflow may start for the same visitor. Only some triggers have it. See How often.
Priority
number
Which workflow runs when two of this brand's workflows match the same moment. See Priority.
Only for identified visitors
switch
Off unless you switch it on. On: the workflow starts only for visitors your website signed in. See Only for identified visitors.
Starts per visitor per hour
number
How many times the workflow may start for one visitor within an hour. 0 = no limit. See Starts per visitor per hour.
Only start if
query
A filter the visitor must match. Leave it empty to start for everybody. See Only start if.

The card on the canvas sums up your choices: the trigger, Starts with, Only if, Frequency and Priority. When you set them, it also shows Starts for: identified visitors only and Limit: max 5 starts per visitor per hour (with your number). In small print it also says where the workflow starts by itself, when it stays quiet, and who else can start it. An unpublished workflow shows a warning there instead: nothing starts it, neither its trigger nor any of the ways to start it yourself, until you publish it. Your changes are stored when you press Save.

Everything else is in the top bar. The builder has two views, Editor and Runs, and:
  • The name: click it to rename the workflow.
  • The brand the workflow belongs to shows as a badge next to the name. To use the workflow on another brand, copy it from the brand's Workflows page.
  • Edit with AI is not a button in the bar: open Ask Yaplet while the editor is open and you find it there. It asks Yaplet to change the workflow. Its change lands on the canvas and waits for your Save — see Flow editor.
  • The ⋯ menu beside Publish / Unpublish and Save holds Rename, Duplicate and Delete.

If other workflows start this one through a Start a workflow step, Unpublish and Delete ask first and name them. While this workflow is off, or once it is deleted, those workflows apologize to the visitor and hand the conversation over to your team.

Publish is refused while a Call an API step has no address yet: "Fill in the address of every Call an API step before switching this workflow on."

The permission for all of this is Chat workflows.

The triggers

A trigger decides when the workflow starts by itself. They are listed in this order:

TriggerStarts whenWhere it can startHow often, unless you choose
User saysThe AI agent recognizes a request you describeWebsite chat, Facebook, Instagram, email, phone callsNo setting
No automatic startNever by itselfNowhereNo setting
Chat openThe visitor starts seeing the chatWebsite chatOnce per visitor
Nobody picked upA colleague was asked for and nobody answeredWebsite chat, Facebook, Instagram, emailNo setting (once per request)
Custom eventYour website reports that something happenedWebsite chatEvery time
Online sinceThe visit has lasted the minutes you setWebsite chatOnce per visitor
VisitA new visit beginsWebsite chatOnce per visitor
Rating givenThe visitor rates the conversationWebsite chat, Facebook, InstagramEvery time
Chat closedThe visitor stops seeing the chatWebsite chatEvery time

A workflow you build from scratch starts on User says. The workflow's steps can rule out more channels; see Where a workflow can run.

User says

Yaplet, the brand's AI agent, starts this workflow when a visitor asks for what you describe.

While Yaplet answers a visitor, it compares each message with your description. When the message is that request, Yaplet starts this workflow instead of answering on its own. It works wherever Yaplet answers: website chat, Facebook, Instagram, email and phone calls.

  • What the visitor is asking for: describe the request in plain words, for example "The visitor wants to know where their order is."
  • Values the AI picks out of the message (optional, up to 10): things Yaplet fills in from the visitor's sentence when it starts the workflow. Each value has a Name (letters, digits and underscore, for example order_id; later steps insert it as {{ order_id }}), a What it is line that tells the AI what to put there, and a Type: Text, or One of a few choices with the Choices the AI may pick from. Names of the visitor's own details, such as email or name, can't be used.

Yaplet does not start it while a colleague is in the conversation or has been asked for. It also never starts a workflow whose What the visitor is asking for is empty. A new workflow starts on User says with that field empty, so write it before you publish.

No automatic start

The workflow never starts by itself. It runs only when someone starts it.

Use it for workflows you start from the inbox, from another workflow, from a Home button or conversation starter, or from your website. See Starting a workflow yourself. Older workflows that were never given a trigger show as No automatic start here, and carry a Draft — no trigger badge in the brand's Workflows list.

Chat open

Starts when the chat screen of your website widget becomes visible to the visitor.

It starts when the visitor opens the launcher onto the chat, comes back to the chat screen, or moves to it from another screen of the widget. It does not start when the visitor got to the chat by one of these, because they already asked for something specific:

  • writing a message on the Home screen
  • tapping a Home button of type Send Message or Start Workflow
  • your website calling Yaplet.startBot
  • an Engagement banner or chat message whose action starts a workflow

Website chat only. Unless you change How often, it runs once per visitor.

Nobody picked up

Starts when a visitor asked for a colleague and nobody answered in time.
  • Minutes: how long to wait after the visitor asked for a colleague. Unset means 5; anything above 45 counts as 45.

When the time is up, the workflow starts if nobody has taken the conversation and no colleague has written to the visitor since the request. It starts once per request. If the visitor asks again, the clock starts again. Use it to apologize, ask for an email address or offer a callback.

It works in written conversations: website chat, Facebook, Instagram and email. There is no How often setting.

Custom event

Starts in the visitor's chat when your website reports that something happened, such as a failed payment or an abandoned cart.

Your developer adds one line of code where it happens, on a page that has the Yaplet widget:

JavaScript
Yaplet.trackEvent('customEvent', { name: 'payment_failed', order_id: '1234', amount: 59 })
  • Event name: the name your website sends, here payment_failed. Capital letters and spaces at either end don't matter. While this field is empty, the workflow never starts.

Everything else the website sends arrives as values the workflow can use: write {{ order_id }} in a message, or test a field under Event data in Only start if. Fields named like the visitor's own details (name, email, phone, plan, value, country and so on, or anything starting with custom_) are left out, so pick other names for your own data.

Website chat only. Unless you change How often, it runs every time the event arrives.

Online since

Starts when a visitor's visit has lasted the number of minutes you set.
  • Minutes: how long the visit must last. Unset means 10.

The workflow starts when the visit has lasted that long and a page with your widget is open. Every new visit starts the count again. If the visitor closes the page before the time is up and comes back later in the same visit, it doesn't start: they were not there the whole time. Website chat only. Unless you change How often, it runs once per visitor.

This is the one for engaged visitors: someone still on your site after several minutes is telling you something.

Visit

Starts when a visitor arrives on your website for a new visit.

A new visit is the visitor's first one, or a return after at least 3 hours without activity on pages that have your widget. Reloading the page or opening another tab within those 3 hours is still the same visit. Website chat only. Unless you change How often, it runs once per visitor.

Rating given

Starts when the visitor rates the conversation.

It fires on a rating in the website widget and on a rating chip in Facebook Messenger or Instagram. The workflow starts with two values:

  • rating: the score, a number from 1 to 5. A Conditions step can answer a low score differently from a high one.
  • comment: what the visitor wrote with the rating, if anything. Ratings from Facebook and Instagram never carry a comment.
Also start while a colleague is still in the conversation
switch
Off (the default): the workflow starts only when no colleague is in the conversation, for example after they left. On: a rating starts it even when the colleague who asked for it is still there.

Unless you change How often, it runs every time.

Chat closed

Starts when the visitor stops seeing the chat.

It fires once each time the visitor closes the widget or leaves the chat screen for another screen of the widget. Moving between other screens doesn't count. Website chat only. Unless you change How often, it runs every time.

When a workflow stays quiet

Some moments are wrong for a workflow even though its trigger happened. These rules keep it quiet:

The workflow does not start when…Applies to
The visitor is blockedEvery trigger, and every way of starting a workflow yourself
A colleague is in the conversationEvery trigger, except Rating given with its switch on
A colleague was asked for and nobody has taken the conversation yetChat open, Visit, Online since, Custom event, Rating given, Chat closed
Another workflow, started in the last 3 hours, is waiting for the visitor's answerEvery trigger except User says
The visitor wrote, or a colleague replied, in the last 3 hoursChat open, Visit, Online since

User says follows its own rule: Yaplet stays out of a conversation while a colleague is in it or has been asked for, so it doesn't start the workflow either.

The workflow's own settings must allow the start too: its steps must be able to run in the conversation's channel, the visitor must match Only start if, How often must allow another start, and, when you set them, Only for identified visitors and Starts per visitor per hour must let the visitor in.

Held-back starts are written down. Open the workflow's Runs view: Starts held back lists each time the trigger matched but the workflow stayed quiet, with the reason. The one exception is a start held back only by How often (the workflow already ran as often as it may): that is the normal case for a returning visitor, so it is not listed. Held-back starts are kept for 30 days.

How often

Chat open, Custom event, Online since, Visit, Rating given and Chat closed have a How often field. User says, No automatic start and Nobody picked up don't.

Once per visitor (default) / Every time it matches (default)
select
What happens if you don't choose. Chat open, Visit and Online since start once per visitor; the other triggers start every time they match.
Send once for a unique visitor
select
The workflow starts once per visitor, however often the trigger happens.
Unlimited (send on each click)
select
The workflow starts every time the trigger happens.
Send once per 24 hours
select
The workflow starts at most once a day for the same visitor.

It is counted per visitor, across all of their conversations. Runs you start yourself count too: after a colleague starts a "once" workflow from the inbox, its trigger won't start it again for that visitor.

Priority

A whole number, 0 unless you change it. When two workflows of this brand match the same moment, exactly one runs: the one with the higher number. With equal numbers, the older workflow wins.

The order is only about who goes first. If the higher-priority workflow is held back, for example by its filter or by How often, the next one runs instead. The ones that lost show "Another workflow won" in their Starts held back list. Priority doesn't matter for User says, because Yaplet picks the workflow itself.

Only for identified visitors

Let the workflow start only for customers your website has signed in. Use it when the workflow shows or changes something that belongs to one customer, such as their orders or their account.
Only for identified visitors
switch
Off (the default): the workflow starts for every visitor. On: the workflow starts only for identified visitors.

The switch is off for every workflow until you turn it on, so nothing changes by itself. It works with every trigger.

Who counts as identified: a visitor in your website chat whom your website signed in through Yaplet.identify, with a signature made from the widget's identity secret. The secret and code samples are under Brand → Chat widget → Install; the setup is explained in Identity Verification. Visitors on Facebook, Instagram, email and phone calls never count, because a sender or a phone number can be faked. The panel shows the same explanation under the switch.

For everyone else, the workflow does not start:

  • User says: the AI tells the visitor how to get identified instead, in its own words and in the visitor's language. It uses the text How visitors get identified from Brand → AI agent → Answers. While that is empty, it uses the standard sentence: "To use this, please sign in to your account on our website and open the chat from there, then ask again." On a phone call, the voice agent says it.
  • The other triggers (Chat open, Visit, Custom event and so on): the workflow is skipped, and the visitor sees nothing.
  • The visitor's own starts (a Home button, a conversation starter, the SDK, a link or an Engagement action): nothing happens.

Each of these shows up as Not identified under Starts held back in the Runs view.

Not checked when someone else decides. A colleague starting the workflow from the inbox, and a Start a workflow step in another workflow, start it whoever the visitor is: the colleague or the other workflow made that decision. To protect one sensitive call inside such a run, or inside a workflow open to everyone, switch on Only for identified visitors on the Call an API step itself — see Flow editor.

Starts per visitor per hour

Starts per visitor per hour
number
How many times this workflow may start for one visitor within an hour. 0 = no limit (the default), 1000 at most.

It counts this workflow's starts for the same visitor in the last hour, phone calls included. A signed-in visitor is counted by their user ID, so opening a fresh browser session does not reset the count. Over the limit, the workflow does not start; when the AI was asked for it (User says), it answers the visitor on its own instead. Each of these shows up as Visitor limit under Starts held back.

The same rules apply here as for Only for identified visitors: the visitor's own starts obey the limit, while starts from the inbox and from a Start a workflow step skip it.

Only start if

Aim the workflow at one group of visitors instead of everyone who trips the trigger.

The filter is checked when the trigger fires, before any step runs. Combine rules with AND / OR from these groups:

  • Visitor: Country, Email, Name, External ID, Identified, Plan, Value, Language, Current page, Device, Browser, Operating system, Last seen, First session, Sessions, Banned, and Custom attribute (you type the attribute's name). Current page also offers Matches pattern (use * for any text) and Matches regex.
  • Widget: Online status (online or offline).
  • Conversation: Channel (chat widget, Facebook / Instagram, email, phone).
  • Event data: only for the Custom event trigger. You type the name of a field your website sends, for example amount, and compare it as text or as a number.
Email, name and custom attributes come from the visitor's browser. They are fine for targeting, but they are not proof of who someone is. Only the external ID is verified.

Starting a workflow yourself

Whatever its trigger, a published workflow can also be started on purpose:

  • From the inbox: the Start menu in a conversation's reply box, then Workflows — or the same picker in the mobile app. It lists the published workflows of the conversation's brand.
  • From another workflow: a Start a workflow step. See Flow editor.
  • From the widget's Home screen: a button of type Start Workflow. See Home Screen Cards.
  • From a conversation starter that starts a workflow. See Conversation starters.
  • From an Engagement banner or chat message whose action starts a workflow. See Engagement.
  • From your own website, on a page that has the Yaplet widget, with the SDK or a link:
JavaScript
Yaplet.startBot('<workflow id>')
HTML
<a href="yaplet://bot/<workflow id>">Track my order</a>

The workflow's ID is the part of the builder's address after /dashboard/automation/custom/. The call and the link both open the widget on the chat and start the workflow.

yaplet://bot/ links work only on your own pages where the widget runs. Inside the chat widget and in knowledge base articles they do nothing.

These deliberate starts work differently from a trigger:

  • They ignore Only start if and How often. Someone asked for this workflow by name. They still count towards How often for the trigger's own later starts.
  • The visitor's own starts still obey Only for identified visitors and Starts per visitor per hour. A Home button, a conversation starter, the SDK, a link or an Engagement action does nothing for a visitor who is not identified or has reached the limit. Starts from the inbox, the mobile app or a Start a workflow step skip both rules.
  • The workflow must be published and belong to the conversation's brand.
  • They replace a waiting workflow. If another workflow in the conversation is waiting for the visitor's answer, the new one takes over and the old buttons disappear from the visitor's screen.
  • Blocked visitors never start a workflow, not even this way.
  • A colleague in the conversation stops the visitor's own starts. A Home button, a conversation starter, the SDK, a link or an Engagement action doesn't start the workflow while a colleague is in the conversation. Starting from the inbox or the mobile app is the only way that works then.

When a visitor taps a Home button or a conversation starter, its label is posted as the visitor's own message, so the conversation reads as a question and its answer. While a colleague is in the conversation, that message goes to the colleague instead, and the workflow doesn't start. The SDK, links and Engagement actions post nothing.

© 2026 Yaplet. All rights reserved.