Chatbot (answers your customers)

Chatbot

A chatbot answers the people who write to your business on WhatsApp, Instagram and Telegram. It is connected through ChatApp and it says only what its knowledge base holds: every price, time or figure in an answer is checked against one entry of that base before anything goes out, and an answer that cannot be checked is not sent.

It is turned on in Settings → Beta features → Chatbot. Then the space's bots appear on the Agents page under Answering customers, and each bot has its own page there holding all of its settings.

Setting one up

1. Add a chatbot — a name, a scenario (Clinic, Salon, Support or Other) and a sentence about the business. A new bot is a Draft: it reads nothing yet.
2. Connect ChatApp (owner or admin). Enter the ChatApp account's email, password and App ID. Plank exchanges them for a token and keeps only the token, encrypted. Never type these into a chat — the assistant has no access to them and does not need it.
3. Add a line — each WhatsApp number or Instagram account on the ChatApp account is a line. One line belongs to one bot; a space can run several bots on different lines.
4. Route to Plank on each line, so ChatApp sends its messages here. This replaces whatever webhook the line had in ChatApp.
5. Fill the knowledge base (below), then switch the bot to Shadow.

Connecting ChatApp, choosing lines, the mode and sending to customers are for an owner or admin of the space. Members can read the bot, test it and decide its changes.

Modes

Write to customers itself is the master switch for sending without a manager. While it is off, the bot only leaves notes. With it on, each line's Auto-send decides what goes out on its own: Replies (only ready texts from the base), + questions (also clarifying questions with no figures), or All (any answer that passed the check, prices included). Start with Replies. Whatever the mode, an answer stays a note for a manager when a manager has already replied or is writing in that chat, when the conversation reads as urgent or as a complaint, when the answer would only repeat a question the bot already asked, or when the customer themselves raised a health topic (see below). Answers go out in the language the customer wrote in, with prices written the way your knowledge base writes them.

A customer's question about health is never answered by the bot — it goes to a person. For a clinic or a salon bot, when the customer themselves asks about or reports pregnancy, breastfeeding, contraindications or symptoms, the answer is held whatever the auto-send mode says, including a ready reply: the chat is tagged «needs a person» and your manager gets the draft as a note, so they can take the question to a doctor. Answering your own script's health question does not count — «no» to «any pregnancy or breastfeeding?» is history, while «no, but I have a rash» is a question. A support or custom bot is not held: health is not its subject, and its owner asks us to turn this on.

The bot never sends the same text twice in one chat within 7 days. If it would, it stays silent and your manager gets a note with the patient's question and the draft. A repeated goodbye is simply dropped, with no note.

What the bot knows

Four kinds of entry:

• Fact — a statement it may quote: a price, an address, a duration.
• Policy — business-wide and quotable: prepayment, opening hours, cancellations.
• Rule — how to conduct the conversation ("ask which procedure before quoting a price"). Followed, never quoted.
• Reply — a ready text sent word for word at a social moment ("thank you, see you on Saturday"). No figures.

Generic bots also have How the bot speaks: tone, standing instructions, what to call the customer and when to hand over to a person. These shape the wording; they can never override the fact check.

Changes, tests and versions

Every edit — a new fact, a removed one, a new tone — is a change. A change is first proposed, then tested: the bot answers your sample questions twice, as it is now and as it would be after the change, through exactly the same check it uses with real customers, and nothing is sent. Then it is applied — or rejected. Every applied change becomes a new version and can be reverted, unless the same entries were edited since.

The assistant applies tested changes decides who presses Apply: on, the assistant may apply a change once its test ran; off, the assistant only proposes and you decide under Changes.

The chatbot manager

A chatbot is not an agent: it answers each message as it arrives and has no runs of its own. What looks after it is an agent — the Chatbot manager, one per bot, listed on the Agents page with your other agents and linked from the bot's page under Who looks after it.

Plank adds it when the bot is created. Every evening at 19:00 (Almaty time; change it on the agent's page) it reads how the bot did, looks into the conversations where it stayed silent, proposes and tests fixes, and posts what it found and what it suggests to your Inbox. It runs only while the bot is in Shadow or Live; turning the agent off on its own page stops it whatever the bot's mode.

A bot created before managers existed has none. An owner or admin presses Assign under Who looks after it, and the inbox posts go to whoever pressed it.

---

For the assistant

Tools: plank_chatbot_list, plank_chatbot_get, plank_chatbot_health, plank_chatbot_knowledge, plank_chatbot_activity, plank_chatbot_propose, plank_chatbot_test, plank_chatbot_apply, plank_chatbot_changes, plank_chatbot_revert, plank_chatbot_reject.

You cannot create a bot, add or route a line, change its mode, turn on sending to customers, change who may apply, or touch the ChatApp account. Those are the person's, on the bot's page in Agents. If they are needed, say which switch and where.

The loop, every time:

1. Look first. plank_chatbot_health gives the counts for the last days — drafts by outcome, why answers were held, what was delivered and what managers did with it, urgent messages (how many, how many still have no reply from a person, the median time to a reply; these stay out of the manager's report), changes waiting. plank_chatbot_activity shows what the bot actually said and why it stayed silent (no_knowledge, ungrounded_number, escalate …). plank_chatbot_knowledge finds the entry to update — do not add a second entry for a fact that exists. It also prints a weekly slice, counted by code over one finished week (week_start names another): customer waits and those with no reply, waits the bot stayed out of by reason, customer questions and handoffs with no reply within 48 hours, the bot repeating an earlier message word for word per day, refusals by reason, a person stepping in right after the bot, the bot writing into a manager's conversation, and reply times. Numbers only, with no customer text. A wait is not a question, and until a definition of a good answer is connected the slice says nothing about whether answers were good.
2. Propose with plank_chatbot_propose: a one-line summary and the ops. Put every figure the bot will need for one answer into one fact — an answer is checked against a single cited entry, and a true sentence assembled from two is thrown away. Add a fact only when the user or their own document stated it. Never infer a price.
3. Test with plank_chatbot_test and the change id. Give questions the change should alter (expect: "change") and questions it must not (expect: "keep"). Read the before/after answers and every warning.
4. Show the user the answers and warnings in plain words, then apply with plank_chatbot_apply. If the test raised warnings, pass acknowledge_warnings: true only after the user accepted them. On a bot set to human approval, ask the user to press Apply under Changes instead.
5. If something went wrong, plank_chatbot_revert the change.

In a space with several bots, a change to a shared entry moves every bot, so you cannot apply it yourself — a person does. Prefer bot-scoped entries.

How the bot talks is changed the same way: a profile.update op (tone, instructions …) on generic bots, or a Rule entry (kind: "playbook") on a bot that runs the legacy clinic prompt — plank_chatbot_get says which.

Answers vary between test runs because the model samples: judge the meaning and the outcome, not the exact words. A test never sends anything to a customer.