# VS Code Extension

Use the Bots.Business VS Code extension to develop and maintain your bots directly from the file system, with automatic synchronization to the Bots.Business platform.

### What this extension does

This version of the extension is **file-first**:

* The bot is downloaded into your workspace as normal files.
* All bot commands live in `commands/**/*.js` – these files are the **source of truth**.
* When you save a file, the extension automatically sends the updated command to Bots.Business.
* You can use all VS Code features (AI assistants, Git, search, refactoring, etc.) on your bot code.

### Installation

You can install the extension from:

* **Visual Studio Marketplace** – search for `Bots.Business` in the Extensions view, or use the direct link from the Bots.Business site.
* **Open VSX** (for VSCodium and compatible editors) – search for `bots-business`.

After installation, reload VS Code if it doesn’t prompt you automatically.

### Requirements

* A Bots.Business account.
* Your **BB API Key** from the Bots.Business app (Profile section).
* VS Code / VSCodium with JavaScript support enabled.

### Connecting VS Code to Bots.Business

1. Open VS Code with any folder as your workspace (it can be empty for a new bot).
2. Open the **Command Palette** (`Ctrl+Shift+P` / `⌘+Shift+P`).
3. Run **`BB:login`** (or **“Bots.Business: Login”** depending on your UI).
4. Paste your **BB API Key** from the Bots.Business Profile page and confirm.
5. Optionally, you can also set the key in VS Code settings:
   * `File → Preferences → Settings → Extensions → Bots.Business`
   * Or directly in `settings.json` via `"bots-business.apiKey"`.

Once the API key is saved, the extension can access your bots.

### Downloading a bot to the file system

1. Make sure you are logged in via `BB:login`.
2. Open the Bots.Business view or run the relevant command from the Command Palette (for example, a bot install / download command).
3. Select the bot you want to work with.
4. The extension will create a local structure in your workspace, including a `commands/` folder with one `.js` file per command.

Each command now appears as a regular JavaScript file in the VS Code Explorer.

### File-first workflow

#### Editing existing commands

1. Open any file under `commands/`, e.g. `commands/start.js`.
2. Change the code as needed.
3. **Save the file** (`Ctrl+S` / `⌘+S`).

On save:

* The extension detects the change.
* The corresponding command is automatically updated on Bots.Business via the API.
* The file in your repository / project remains the primary source.

You can now freely use:

* AI code assistants in VS Code
* Refactoring tools
* Multi-file search and replace
* Git / other VCS tools

#### Creating new commands

There are two main options:

1. **Via extension command (recommended)**
   * Use the Command Palette and run the “new command” action (e.g. `BB:newCommand`).
   * The extension creates a new file in `commands/` with the correct internal metadata.
2. **From a new file**
   * Create a new `.js` file under `commands/`.
   * Use the extension’s command to register / sync this file as a new command (exact command name depends on the current version).
   * After the first sync, the command will exist on Bots.Business and will be linked to this file.

#### Deleting commands

Typical flow:

* Delete the corresponding file in `commands/`.
* Run the relevant extension command or refresh (e.g. `BB:refresh`) so the tree and remote state are updated.

If deletion behavior is critical for your workflow, check current release notes or test on a non-production bot first.

### CMD-blocks and metadata

Each command file contains an internal **CMD-block** – a special comment block with metadata, including the command ID on Bots.Business.

* The CMD-block is used by the extension to match a file to a remote command.
* Do **not** remove this block.
* Do **not** manually edit its contents unless you know exactly what you are doing.

If the CMD-block is broken or removed, the extension may not be able to sync the file with the existing command and can treat it as a different/new command.

### Synchronization rules (summary)

* **Source of truth**: `commands/**/*.js` in your workspace.
* **Direction**: local file → Bots.Business on every save.
* **Initial import**: when you first download a bot, its current commands are written into files.
* **Conflicts**: if you edit commands both in the web UI and in VS Code, the last saved version wins. For consistent workflow, prefer editing through the extension once the bot is file-based.

### Typical quick-start scenario

1. Install the extension from Marketplace/Open VSX.
2. Get your BB API Key from the Bots.Business Profile.
3. Run `BB:login` in VS Code and paste the key.
4. Download a bot into an empty folder.
5. Open `commands/start.js`, change a reply, save the file.
6. Test the bot in Telegram – the reply is updated.

### Troubleshooting

* **Nothing happens on save**
  * Check that you are logged in (`BB:login`).
  * Confirm the workspace contains the bot files and `commands/` folder.
  * Make sure the file is under `commands/` and has a CMD-block.
* **Bot tree looks outdated in VS Code**
  * Use the refresh command (e.g. `BB:refresh`) to reload data from Bots.Business.
* **API errors**
  * Verify the API key is valid and not expired.
  * Check that you still have access to the selected bot in the web interface.

For advanced usage, refer to the extension’s changelog and repository, or test changes on a non-production bot first.

## Links

You can istall extension from the Stores or from VSCode.

{% embed url="<https://marketplace.visualstudio.com/items?itemName=bots-business.bots-business>" %}

{% embed url="<https://open-vsx.org/extension/bots-business/bots-business>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.bots.business/vs-code.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.