chatleadr Docs
Open Chatleadr

Why Descriptions Beat Keywords

Keyword configuration works one way: list the words, and when the visitor types one, do the thing. AI mode does not work that way.

What Your Visitors Actually Type#

Take a garden furniture shop with a workflow that should fire on delivery questions, and a keyword list to match:

text
delivery, deliver, shipping, ship

A week of visitor messages, against that list and against a written description of the same workflow.

Five messages a real week produced Keyword list delivery, deliver, shipping, ship how long till I get it? do you bring it to the house im in bloem, is that a problem whats the lead time on the 6 seater can I return the chairs? 0 of 4 delivery questions reached the workflow. Written description USE WHEN … DO NOT USE for returns how long till I get it? do you bring it to the house im in bloem, is that a problem whats the lead time on the 6 seater can I return the chairs? All 4 matched. The return question correctly did not.
The same five real messages, put to a keyword list and to a description.

Not one of the four delivery questions contains a word on the list. Adding words does not fix it: the next phrasing is one you did not think of, and a word broad enough to reach it starts firing on messages that were never about delivery. Matching is whole-word, so "ship" leaves "township" alone and still fires on "can I ship it back for a refund?". Widening the list trades a miss for a false trigger.

What a Description Does Instead#

The same workflow, described:

text
Answers questions about delivery of furniture orders: timeframes, areas we
deliver to, and delivery costs. USE WHEN the visitor asks how or when their
order will reach them, or whether we deliver to their area. DO NOT USE for
questions about returns or collection from the warehouse.

All four delivery questions match, because the assistant matches on meaning and not on spelling. "Can I return the chairs?" does not, because the description says so.

When Keywords Are the Right Tool#

Keyword mode still exists in Chatleadr and has two uses:

  • Deterministic routing. A competition entry where "ENTER" must always start the same workflow and nothing may interfere with it.
  • Running without a model. Keyword matching makes no model call, so it keeps working after the workspace has spent its monthly conversations.

Both want one exact word to do one exact thing. Keywords do that, and descriptions cover the phrasings you did not anticipate.

Using Both#

Mode is set once per bot, and a bot in AI mode can still route exactly: a conversation starter bound to a workflow runs it directly when clicked, skipping selection. Use a starter for the two or three paths that must never be missed, and leave the description to catch everything else.

Common Questions#

Is AI Mode More Expensive Than Keyword Mode?#

Conversations are charged at the same rate in both modes. Keyword workflows keep running once an allowance is exhausted, so an AI bot falls back to keyword mode instead of stopping.

Can One Workflow Have Both a Description and Keywords?#

Yes. The description drives selection in AI mode, the keywords drive matching in keyword mode, and the same workflow runs either way. Fill in both on the workflows that must keep working after an allowance runs out.

Do Misspellings Still Match?#

Usually, because matching is on meaning and not on characters. "delivary" in a sentence about an order arriving reads the same way to the assistant, where a keyword list would miss it entirely.