How a workflow starts

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:

The card on the canvas sums up your choices: the trigger, Starts with, Only if, Frequency and Priority. 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.

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 Workflows.

The triggers

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

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

While Vex answers a visitor, it compares each message with your description. When the message is that request, Vex starts this workflow instead of answering on its own. It works wherever Vex 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 Vex 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.

Vex 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

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. This trigger used to be called Start manually. Older workflows that were never given a trigger show as No automatic start here and as "No trigger yet" in the brand's Workflows list.

Chat open

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

• 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

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

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

• 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.

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

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.

Unless you change How often, it runs every time.

Chat closed

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. This trigger used to be called Chat minimize.

When a workflow stays quiet

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

User says follows its own rule: Vex 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, and How often must allow another start.

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.

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 Vex picks the workflow itself.

Only start if

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.

Starting a workflow yourself

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

• From the inbox: the Workflows button in a conversation, 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:

Yaplet.startBot('<workflow id>')

<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.

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 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.