Chat Flows
How a Chat Flow starts, which CRM record it creates or binds to, who it assigns the record to, what happens when the customer goes quiet, and how the flow editor works.
A Chat Flow is a scripted WhatsApp conversation. It sends messages, asks questions and saves the answers, branches on them, fills in CRM fields, moves the record to a stage, assigns it to a colleague and hands the chat to a person. It runs on numbers connected through WASync, both QR connections and the official WhatsApp Business API ones.
Flows live in the WASync app in Bitrix24: choose Chat Flows in the left menu. The list shows each flow with its on/off switch; opening one opens the editor. This page describes how flows behave and what the controls do.
When a flow starts
The Start card of a flow says in plain sentences when it starts. The button Change when it starts opens the trigger panel, where How the flow starts has two choices:
| Choice | What starts the flow |
|---|---|
| Bitrix24 automation rule | A rule you add to a pipeline stage in Bitrix24. The lead or deal already exists; the flow does not create one. |
| Customer writes first | A WhatsApp message arrives on the number you choose under WhatsApp number. |
With Bitrix24 automation rule, the phone on the lead or deal must include its country code (for example +52 …). WASync does not guess a missing code: the flow does not start, and the record gets a timeline comment that says why. Add the prefix in Bitrix24, or set the Default country in Settings.
For Customer writes first, Which first message narrows it:
- Any message: any message that starts a conversation.
- Keywords: only when the first message contains one of the words you list, separated by commas.
- From a specific ad: only when the customer arrives from one of the Meta Click-to-WhatsApp ads you list, by ad id (from Ads Manager). For a campaign, list all of its ad ids. An empty list matches any ad.
A customer who sends several messages in a row before the bot answers ("hi", "good evening", "where are you?") starts one run, not one per message: the first message is the trigger, the rest are read as part of the same conversation, and the opening sequence goes out once.
A number can have several inbound flows. When more than one matches, the most specific wins: the flow for the customer's ad first, then keywords, then Any message. A flow bound to the number beats a workspace-wide one, and at the same level the older flow wins. A message from an unlisted ad, or from no ad, falls back to the keywords or Any message flow.
A few rules keep a flow from starting when it should not:
- A reply to your team is not a new conversation. If a colleague wrote to the customer in the last 72 hours, from the CRM widget, WASync Chat, the Open Channel or the business phone, the customer's answer does not start the flow. Messages sent by flows, automations and robots do not count. The option Don't start when we wrote first turns this off or sets the window to between 1 and 168 hours.
- An Any message flow waits for a new conversation. It does not start while another flow on that conversation ended inside the same window. A flow that was completed, handed to a person or cancelled counts; one closed for inactivity does not. Flows started by an ad or by keywords are explicit intent and still start. Pressing Allow the flow again on the conversation in WASync Chat clears this wait too, so the next message starts the flow at once, which is handy when you retest a flow from your own phone.
- A message delivered twice is ignored. WhatsApp sometimes delivers the same message again, for example after a session re-sync. The copy never starts a flow or makes a running flow move on.
The Start card also says whether the flow runs Once per customer or Can run again for the same customer, and whether it Stops when a colleague replies.
Only customers who never wrote to you before
On a Customer writes first flow, the switch Only customers who never wrote to you before limits the flow to brand-new numbers. With it on, the flow skips any phone number that has ever exchanged a message with any of your WhatsApp numbers in WASync, on this number or another, in either direction. An existing customer who writes again gets no greeting and no new record; the message simply reaches your team.
The switch is off by default. Off, the flow starts for anyone when no other rule holds it back, and the Start card reads Any message that starts a conversation.
Which record a flow creates or binds to
Under When it starts, a Customer writes first flow is attached to a lead, a deal or a Smart Process item (a deal flow also picks the pipeline and stage). The flow finds the contact by phone number. It never creates a duplicate of a contact you already have.
| Flow type | What happens at the first message |
|---|---|
| Lead | Binds to the contact's open deal, else to the contact's open lead, else to an open lead that holds the number without a CRM contact, else creates a contact (if needed) and a lead. |
| Deal | Binds to the contact's open deal in the chosen pipeline, else creates a contact (if needed) and a deal. |
So a customer who is already being worked never gets a second lead from a flow. With Each number creates its own lead switched on, "already being worked" means on this number: a first-time contact gets the number's own lead, and an older lead that merely holds the phone (another tool's lead) is not reused. The deal is checked first. A lead that carries the customer's number but is not linked to any CRM contact, such as a lead imported from another tool, counts too: the flow binds to it instead of creating a lead next to it.
- Contact has an open dealYesBind to the dealNo
- Contact has an open leadYesBind to the leadNo
- OtherwiseCreate a lead
Two settings from WASync Chat → Chat rules apply to the records a flow creates:
- Who is responsible. Bitrix24 puts a record without a responsible on the user who installed the app. To avoid that, a contact, lead or deal created by a flow takes its responsible from the rule New chats from unknown numbers (a fixed person or round-robin). With that rule Off, the flow leaves Bitrix24's default.
- Each number creates its own lead. With this option on, "already being worked" means on the number the customer wrote to: the flow reuses only the record created or linked from that number. An open deal or lead the contact has from another channel, for example an import or another WhatsApp tool, is left alone and the flow creates the number's own lead.
- Re-contact window after a closed lead. A flow that creates a lead uses the same window as the rule. A customer who writes back inside the window lands on the lost lead, not on a second one. See Leads from WhatsApp chats.
The CRM source of the record
For lead and deal flows, the Source selector under When it starts lists your CRM sources. The source you pick is written on the contact, lead or deal the flow creates. You can, for example, leave a placeholder such as "not selected" for your team to fill in later, or stamp a campaign source of its own.
The default, Automatic — the WhatsApp line's source, gives the record the source of the WhatsApp Open Channel it came through. A record the flow reuses instead of creating keeps its own source; the flow never rewrites it.
Create only the lead, without a new contact
A lead flow normally creates a CRM contact for a customer it does not know yet and links the new lead to it. If your own automation rules create contacts later, or a lead that already has a contact is treated as a repeat customer in your portal, tick Create only the lead (no new contact) under the Source selector on the Start card.
With the option on, the lead is created without a CRM contact. It still gets the phone number, the name, the source and the responsible as usual. If a contact with this phone already exists, the lead is linked to it. An open lead that already holds the number is reused, so a customer who writes again does not get a second lead. Deal flows do not have this option, because a deal always needs a client.
Assign to a person or rotate within a group
The Assign to a colleague step makes someone the responsible of the lead or deal, then the flow continues to the next step. Who gets the record has two modes:
| Mode | What happens |
|---|---|
| One person | The record goes to the person you choose by name. |
| Rotate within a group | You tick up to 50 employees. Each new conversation that reaches the step goes to the next person in the list. |
Every Assign step keeps its own rotation, and saving the flow again does not restart it. Employees deactivated in Bitrix24 are skipped. If nobody in the group is active, the record keeps its current responsible and a note on the timeline says why. A customer who passes the same step twice in one conversation stays with the same person. A test run shows who is next without using up a real turn.
Notify this person in Bitrix24 sends the chosen person a Bitrix24 notification.
Messages built from CRM fields
A message step can be made only of CRM fields, for example just
{{UF_CRM_PROMO_TEXT}}. If those fields are empty on a lead or deal, the step is
skipped and the flow continues with the next step, instead of stopping the
conversation; the editor warns you under the text when a message is made only of
fields. A step that also has files still sends the files, without a caption, and a
question with options still sends its options.
Fill in a field
A Fill in a field step writes a value into a CRM field of the lead, deal or
contact: a fixed value, a variable, or the answer to an earlier question. By default
it replaces whatever the field holds. Tick Only if the field is empty to keep an
existing value instead, which is what you want for origin fields such as Source or
the UTM fields, so a later flow never changes where a lead came from. When the field
already has a value the step writes nothing and the flow simply continues. A list
field that shows no choice counts as empty; for other fields, including numbers, a 0
is a value and is kept.
Save the origin when there is no lead yet
Some flows should record where a customer came from without creating a lead, for
example a keyword flow for a code like (OR) that only writes UTM source
or Source, while a supervisor decides later whether the conversation deserves
a lead. Tick If there is no CRM record yet, save as pending origin (no record is
created) on a Fill in a field step that writes to the lead or deal.
- When the conversation has no lead or deal, the field and its value are saved on the contact as a pending origin. Nothing is created in the CRM.
- WASync Chat shows a line under the conversation header, for example Pending origin: UTM_SOURCE=OR · will be applied when a lead is created.
- When someone creates the lead from the chat (Create lead), or a flow or the rule for unknown numbers creates one, the pending values are written into the new lead or deal and the line disappears. A field the new record already gets (for example the description WASync sets) keeps its value, and a Source that is not in your CRM source list is skipped.
- Linking the conversation to an existing lead or deal writes nothing on it: an existing record's origin is never changed. The pending values stay for a record created later.
- When the conversation already has a record, the step writes to it as usual.
A later save of the same field replaces the earlier value. Up to 20 fields are kept per contact, and a pending value older than 30 days is ignored.
Showing the options as buttons
A question step can show its options to the customer, so nobody has to guess what to type. Turn on Show the options to the customer under the options of the step.
- WhatsApp Business API numbers: up to 3 options arrive as buttons under the question; 4 to 10 options arrive as a list behind one button. The customer taps instead of typing, and the flow continues on that option.
- QR numbers, and whenever buttons are not possible (more than 10 options, two options that look the same once shortened, a question over 1,024 characters): the options arrive as a numbered list under the question, and the customer can answer with the number.
WhatsApp limits the text of a button to 20 characters and of a list row to 24; a longer option is shortened on the button with "…", and the editor shows how it will look. Keywords keep working: a customer who types the answer instead of tapping still reaches the right option.
Buttons are a reply inside the 24-hour window: a question step always follows a message from the customer, so this is met by itself.
Keywords of an option are separated with commas or semicolons
(continuar, 1, si).
WhatsApp forms
The WhatsApp form step (group Ask) sends a message with a button; the customer opens a native form inside WhatsApp, fills it in and sends it. Each answer can be written to a field of the lead or deal (or of its contact or company), and all answers are available to the next steps of the flow.
- Up to 8 fields: short text, long text, email, phone, number, date, single choice and multiple choice (up to 10 options each), each optional or required.
- Set the text above the button, the button label (up to 20 characters) and the form title. When the flow is saved, WASync creates and publishes the form on your WhatsApp Business account; a changed form is published again as a new form.
- The step has two exits: Submitted and Not submitted (no answer within the step's inactivity time).
- WhatsApp Business API numbers only. On a QR number, or when the customer has not written in the last 24 hours, the form is not sent and the flow continues on Not submitted, with a note on the record.
- Choice answers are written as the option text.
HTTP request step
The HTTP request step asks an external system over HTTPS and uses the answer in the next steps: look up an order, check a balance, fetch a delivery date. The step has a success line and an error line. The request is made under a fixed safety policy, not from your browser.
Method, headers, response mapping and limits are covered in HTTP request step in Chat Flows.
The AI assistant tab
Everything the AI step needs is set up in one place: Chat Flows → AI assistant (administrators). From top to bottom:
- AI provider, key and model — your own key. It is shared: the AI robots in Automations use the same one. (Settings only keeps a card that points here.)
- Knowledge — the texts, PDFs and web pages the AI may answer from.
- Try a question — type a question a customer might ask and see the answer, the passages of your knowledge it used and the model that replied. It runs the same checks as a real answer, sends nothing to WhatsApp, saves nothing, and uses your provider's credit like a real answer (up to 20 tries a minute). If it fails, the message says why: no key, key rejected, model not found, provider account out of credit or at its limit, or the AI took too long.
AI step
The AI reply step (group Talk) asks your own AI for an answer and sends it to the customer: questions about opening hours, delivery or your products that do not fit a fixed menu. It uses the AI provider, key and model you set in Chat Flows → AI assistant, so the cost is on your AI account, not on WASync. It works on Pro (paid) numbers only.
At the top of the step's panel a short checklist shows what is missing: the AI key and model, a paid licence on the flow's number (only for a flow bound to one number) and, for information, how many knowledge sources are selected. Set up the key opens the key card over the editor, so you do not lose the changes you have not saved yet. Test this step at the bottom of the panel runs one question through the step as it is now, saved or not (reply steps).
What you set in the step's panel:
- Instructions — who the AI speaks for, what it may answer and what it must leave to a person (up to 4,000 characters). Facts it may quote, such as your hours or a link to your site, go here. Start from an example writes a starting text for you.
- What the AI reads — the last messages of this conversation (0–20, 10 by default), the AI's own earlier answers in this conversation, and the CRM fields you pick with Insert field. Only those fields of this customer's record are sent to your AI provider; never other customers, never keys.
- Knowledge — the texts, PDFs and pages from your knowledge base this step may answer from, and whether it should answer only from them.
- The answer — send it to the customer (on by default) or only store it.
The answer is saved in a variable,
ai_replyby default, which later steps use as{{AI_REPLY}}. Maximum length 50–1,000 tokens (400 by default). - Safety — what happens when the AI fails, takes longer than 10 seconds or
a limit is reached: hand the conversation to a person (default),
continue to the next step, or end the flow.
{{AI_ERROR}}holds the reason. And what happens when a message looks like an attempt to give the AI orders (prompt injection): do not answer and use the fallback (default), or leave that message out and answer the rest.
How WASync protects the conversation:
- The AI takes no actions. It only writes a text: it does not change the CRM, assign the lead, check anyone's identity or confirm anything. Steps you configure do that.
- The customer's messages and the CRM fields reach the AI as data in separate blocks, after a fixed instruction that tells it to treat them as information, never as orders, and never to claim it did something.
- Messages that look like an attempt to give the AI orders (in several languages), role tags, long encoded blocks or messages over 4,000 characters are caught before the AI is called.
- The answer is checked before it is sent: role tags are removed, links to any site other than your Bitrix24 portal and wasync.app are removed, and the length is capped.
- Limits: 10 AI answers per flow run and 500 per day per portal. Each call is logged with its outcome and token count.
Answers written by the step appear in the chat with a WASync Bot · AI label.
The Preview shows (AI answer) in place of the answer and never calls your AI.
These protections reduce the impact of prompt injection and make every incident visible; they do not eliminate it. A customer can still push the AI to say something you would not have written. What limits the damage is that the AI step never performs an action and that, by default, anything suspicious goes to a person. Write instructions that tell the AI what to leave to your team, and test the flow before you switch it on.
Choose from a list
At the top of the step's panel, What the AI does switches between Write a reply (above) and Choose from a list. In this mode the AI writes nothing to the customer: it only picks one of the options you list, and the flow continues on that option's line. Use it to route a free-text message: "Price", "Book an appointment", "Complaint", each with its own next steps.
- Options — 2 to 12, each with a name and, optionally, When to choose it (a short description that helps the AI). Every option gets its own exit on the card; reorder or remove them in the panel and the exits follow.
- Anything else — on by default: an extra exit taken when no option fits.
- Ask the customer first — optional. When filled in, the step sends this text, waits for the reply like a question and has the AI classify the reply. Left empty, the AI classifies the latest messages of the conversation.
- Instructions are optional here: add context that helps the AI choose.
- The chosen option's name is saved in
{{AI_CHOICE}}and its id in{{AI_CHOICE_ID}}(nonefor Anything else). You can rename the variable.
The AI must answer with exactly one of your options; WASync checks the answer
strictly. An answer that names no option, or one that is not in the list, goes
to Anything else when it is on, otherwise to the step's fallback, with
{{AI_ERROR}} set. Errors, timeouts, limits and suspected prompt injection
always take the fallback: hand to a person (default), end the flow, or continue
on the If the AI fails exit, which appears on the card when you choose it.
The same protections, limits and Pro requirement as Write a reply apply.
In the Preview, the flow stops at the step and you pick which option the AI "chose", so you can test every branch without calling your AI.
Knowledge base
Give the AI step your own documents to answer from: an FAQ, a price list, delivery and return terms, a product page. You add them once, in Chat Flows → AI assistant → Knowledge, and pick them in each AI step that should use them.
Adding knowledge (administrators):
- Paste text — plain text or Markdown. It is ready as soon as you add it. You can also do this from inside the AI step's panel (Paste text): the new source is added and selected without leaving the editor.
- Upload PDF — up to 10 MB. Only the text layer is read, so a scanned PDF (pictures of pages) has nothing to read; export it with text instead.
- Add a web page — an
https://address. WASync fetches the page once, keeps only its text (no scripts, no images) and does not follow it to another site. When the page changes, press Re-index to fetch it again. Of a very long page only the beginning is kept (the source says so); a page slower than 10 seconds cannot be added; a page behind a login only gives the login form — paste its text instead.
Each source shows its state (Indexing…, Ready or what went wrong), its size, how many passages it was split into and when it was last indexed. Untick Used by flows to stop every step from using a source without deleting it; Delete removes the source and everything stored from it. Limits: 100 sources and 5,000 passages per portal.
Using it in a flow. In the AI step's panel, Knowledge lists your sources; tick the ones this step may use (up to 20) and set Passages per answer (3–8, 6 by default). Before each answer, WASync looks up the passages closest to the customer's latest messages and gives them to the AI as reference data. In Choose from a list mode they help the AI pick the right option.
Answer only from the knowledge (Write a reply mode): the AI is told to
answer only from those passages. When they do not contain the answer, or no
passage matches, nothing is sent to the customer and the step takes its
fallback (hand to a person by default) with {{AI_ERROR}} set to
no_knowledge_answer. Use it when a wrong answer would be worse than a
person's answer a few minutes later.
How matching works: by the words of the customer's message, tolerant of word endings and small typos. With an OpenAI or Google key in Chat Flows → AI assistant, WASync also compares the meaning of the passages (embeddings, computed with your key) to pick the best ones; with other providers it matches on words only.
Where your text goes: it is stored only in WASync. The few passages chosen for an answer are sent to your own AI provider inside the request, and nowhere else. Text from a page or a PDF is treated like a customer's message — as information, never as instructions: a passage that looks like an attempt to give the AI orders is left out of the request. Everything is deleted with the source, and with your portal.
Inactivity reminders and closing
When a question waits for an answer the customer never gives, the flow can remind them and then close. Two places set this:
- Flow settings → If no reply holds the default for the whole flow. Switch on Remind, then close questions that get no reply. It applies to every question without its own setting.
- Each question has its own If no reply section: Use the flow default, Own setting for this question, or Off for this question.
An own setting has four parts:
| Setting | Meaning |
|---|---|
| Wait without a reply | Minutes before the reminder. |
| Then send this reminder | The reminder text. Leave it empty to close right after the wait, with no reminder. |
| Still no reply? Close the run (inactivity) after another | Further minutes before the run closes. |
| When the run closes, send this message | Optional. A last text the customer receives when the run closes, for example "We didn't hear back, so this conversation was closed. Whenever you want to continue, just send us a new message here." Leave it empty to close silently. |
Times are whole minutes, from 1 to 1,440. A question with no default and no setting of its own simply waits, for up to 24 hours, and then the run is cancelled.
The reminder and the closing message are sent by the flow, and WASync records them as the flow's own messages. They do not count as a colleague taking over (Stop when a colleague replies) and they do not count as "you wrote first" (Flows do not start on a reply to your team), so the customer's next message is treated as a new conversation.
When a run closes for inactivity, a comment is added to the bound lead or deal. A run closed this way does not block the customer. If they write again later, the flow starts over as a new conversation. Every other way of ending a flow still counts as "already done" for flows set to run once per customer.
The editor
The editor shows the flow as cards joined by lines, with a side panel for the selected step.
- Start step. There is exactly one, and it cannot be deleted. It describes in plain sentences when the flow starts, for example Starts when a customer writes first to +…, with any message. Change when it starts opens the trigger panel.
- Side panel. Clicking a step opens its settings beside the canvas, so the flow stays visible while you edit. There is no modal.
- Pickers with names. People, stages, pipelines, sources and CRM fields are chosen by name from lists, never by typing an ID. A Branch takes conditions as Field, Condition, Value.
- Step palette. The palette is grouped (Talk, Decide, Do in the CRM, Hand over, Finish) and searchable with Search for a step….
- Top bar. An editable flow name, a live problems pill (N problems) that jumps to the step to fix, Undo and Redo, and Flow settings.
Insert a step on a connection line
Hover a line between two steps and a + appears next to the ×. It opens the same step picker as the + on a step and puts the new step in between, keeping the branch or answer option the line carried. The new step lands halfway along the line with its panel open.
Find a step
The Find a step… box in the top bar searches every step by name, message text, question options and keywords, branch names, assignee and step type. Press Enter to jump to the next match and Shift+Enter to the previous one; the step is selected, centred and flashes for a moment. Ctrl+F (Cmd+F on a Mac) while on the canvas focuses the box, and Esc closes it.
Highlighted lines
When a step is selected, its incoming and outgoing lines turn green and come to the front while the other lines fade. A long connection is easy to follow on a large canvas.