Sometimes the ready-made nodes are not enough: you need to look into your CRM, calculate an order’s cost, check warehouse stock or talk to a back-office system. For that, your own Python script is connected — a small program written by hand or by the AI agent. A script can become a step right in the conversation, or it can replace whole parts of the application: a communication channel, an AI provider, document preparation for the knowledge base.
How it looks
Scripts are plain files, arranged in the bots’ folders. You can edit them right in the interface, in the built-in editor, or on the server’s file system — whichever is more convenient. The files belong to you; taking them to another server is as simple as the scenario.
Besides the individual bots’ folders there is one shared folder — for scripts that concern the whole application at once: your own AI provider, document processing for knowledge bases, a channel shared by several bots.
Where a script can plug in
There are ten places to plug in. Some of them belong to a specific bot, some to the whole application.
- The Script node — your own step right in the conversation: a calculation, a CRM request, a stock check;
- Incoming message processing — the client’s text passes through a script before the scenario sees it: strip personal data, tag the contact, detect the topic;
- Webhook parsing — a non-standard message from an external system is turned by the script into data the scenario understands;
- Your own AI provider — the script itself answers requests to the model;
- Your own numbers provider for search — the same for turning text into sets of numbers (vectors) that the knowledge base searches by;
- Knowledge base document preparation — before splitting into fragments, the document’s text can be cleaned or rewritten;
- Knowledge base search refinement — after the search, the script can reorder the found fragments or drop the extra ones;
- Sending in your own channel — messages go out to clients through your SMS gateway, email, WhatsApp or the company’s internal system;
- Receiving from your own channel — replies and messages from that system likewise arrive in the conversation;
- A scheduled job — the script runs by itself on set days and hours: a night digest, an export, a reminder to clients.
Your own communication channel
If the built-in channels — Telegram, the public chat page and the widget — are not enough, a channel can be built with a script. One file describes both sending and receiving: for example, messages go out to clients through your SMS gateway, and their replies return into the same conversation.
For receiving, such a channel has a separate hidden address: an external system calls it, and the script turns its data into ordinary bot messages. The address is protected by a secret, and if the secret falls into the wrong hands, it is reissued — the old address stops working immediately.
Your own AI provider
Besides services compatible with OpenAI, a Python script can be made the provider. It receives the whole request — which model, which task, which messages — and returns a finished answer; when you like, it reports the token usage too. This is how a model that lives inside your network and cannot speak the common language of AI services gets connected. The same method sets the provider that turns text into numbers in knowledge bases.
If the script fails, the usual fallback model takes over, and the failure stays in the run journal — nothing breaks off or disappears silently.
Document and search preparation
Knowledge base work can be intervened with too — in two places. Before a document is split into fragments, its text can be cleaned or rewritten: useful when an export arrives with extra markup or junk. And after the search — refine the order of the found fragments: the script can swap them around or drop the extra ones, but it cannot add what is not in the documents.
Data exchange
A script receives information about the bot, the client, the conversation’s variables and the current message on input — the exact set depends on the place it is plugged into. On output it returns a reply to the client, variable changes, the next node or an error flag. All of it in JSON format — that is, as plain text with named fields.
The result is the last complete JSON in the output, so debug lines printed before it do not interfere, and empty output is a legitimate “nothing to do”. If the script ends with an error or returns the wrong thing, the conversation calmly goes down the error branch instead of breaking off.
Secrets and environment
Passwords and keys a script needs are set in the bot’s settings and substituted into the script automatically. They are never shown in the interface or in reports — not whole, not in part. By design, a script runs in a clean environment: neither the server’s settings nor the application’s own keys are visible to it. If a specific script needs a server variable, its name is listed in the script’s settings — it receives only what is listed.
Restrictions
- Time limit. A script gets 60 seconds by default; for long tasks the limit can be raised — up to 10 minutes. A hung script is stopped together with all the processes it started, and the conversation does not get stuck forever;
- Output size limit. An overly long result is trimmed, so the bot stays coherent; bulk data the script puts into its working folder;
- Concurrent run limit. No more than three scripts run at once per bot, and four on the whole server; the remaining jobs wait their turn. This protects the server from overload when there are many clients;
- The emergency switch. If something goes wrong, script runs are switched off with a single setting — it takes effect immediately, without a restart.
The working folder
Every script has its own working folder — a permanent place on disk where it stores what it alone needs: intermediate files, marks of what has already been processed, prepared exports. The folder survives both runs and application restarts, so the next run continues from where the previous one stopped.
Additional libraries
If scripts need libraries that are not in the standard Python set, their list goes into the scripts-requirements.txt file in the root of the settings folder. The application builds a separate environment for them and updates it when the list changes — nothing needs to be installed by hand.
The run panel and settings
Any script can be run right in the “Scripts” section with prepared data: you see what the script returned, what errors there were and how long it took. Convenient for debugging in parts — without embedding the script into the scenario and without touching the whole bot.
Next to it — the script’s settings: the time limit, the list of allowed server variables and its own variables. Secret values are shown hidden and cannot be erased by accident.
The run log
Every call — whether in a conversation, on a schedule or while processing incoming messages — leaves its own line: what came in, what was returned, how long it took and how it ended. The journal filters by status and by hook point, and new runs appear in it immediately, without refreshing the page. If something went wrong for a particular client, the journal shows what data the script worked with and what it returned.
Health
Scripts rely on the server’s Python environment, so the Health section has a separate block: whether Python is found, whether the environment with the libraries is ready, whether runs are enabled, how many there were over the last 24 hours and how many of them failed. If something is broken, the application does not pretend everything is fine — it shows directly what exactly is not working.
How to connect a script to a conversation — in the Flow Nodes section. How to configure models — in Models & Prompts, knowledge base documents — in the Knowledge Base section, and how to create the bot itself — in Bots.