Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
357 changes: 238 additions & 119 deletions README.md

Large diffs are not rendered by default.

40 changes: 29 additions & 11 deletions docs/calls.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,25 @@
# Calls

Read this page if your company's phones run through Bitrix24 telephony. It shows how to copy the portal's calls into
the local WireCat store, turn their recordings into text on this computer, and find a client's calls beside their
deals, messages and mail. By the end, `memo context` shows a client's calls in their history.
Keep your calls on Bitrix24's phones on your computer, with what was said as text, in the same local store as the
client's deals, messages and mail. The portal keeps its calls in its call history (Telephony → Call history), and
`b24` copies them from there.

Words this page uses:
An agent then tells you when a client last called, how the call ended and what was said on it. Calls from another
phone system can also land on the client's contact in Bitrix24, so the CRM shows them too.

- **Call history**: the list of calls the portal keeps under Telephony → Call history. b24 reads it with the
`voximplant.statistic.get` method.
- **Profile**: the name of one portal's sign-in, such as `work`. It is the first word of a command.
`meetings sync` copies the calls into the WireCat local store, and every `sync` does it too. `meetings transcribe`
turns the recordings into text with a speech model that runs on this computer. `calls export` writes other phone
systems' calls into Bitrix24. You need the webhook's `telephony` scope.

**On this page:**

1. [Before the first sync](#before-the-first-sync)
2. [Copy the calls](#copy-the-calls)
3. [The client and the employee](#the-client-and-the-employee)
4. [Recordings](#recordings)
5. [Turn calls into text](#turn-calls-into-text)
6. [Permissions](#permissions)
7. [Write other phone systems' calls into Bitrix24](#write-other-phone-systems-calls-into-bitrix24)

## Before the first sync

Expand All @@ -26,7 +37,7 @@ example because the webhook has no telephony scope, it says why in a note and th
the calls out of `sync`: `b24 work config set sync_calls false`. `meetings sync` copies only the calls:

```sh
b24 work meetings sync # calls since the last sync; the first reads 30 days
b24 work meetings sync # calls since the last sync, the first reads 30 days
b24 work meetings sync --since-time 2026-11-01T00:00:00Z # calls from a date on
b24 work meetings list # newest first, from the store, offline too
b24 work meetings show 12 # one call: who, when, how it ended
Expand Down Expand Up @@ -95,7 +106,7 @@ b24 work meetings transcribe # calls of five seconds or more with no tex
b24 work meetings transcript 12 # one call's text
```

A recording kept by `download_recordings` is read from this computer; any other is downloaded for the
A recording kept by `download_recordings` is read from this computer. Any other is downloaded for the
transcription, and kept only when `download_recordings` is on. Bitrix24 does not say which side of a stereo
recording is the employee, so the text names the channels "Channel 1" and "Channel 2". A call of more than an hour
is skipped.
Expand All @@ -117,8 +128,15 @@ b24 work config set permissions.meetings.sync deny
Calls from another phone system, such as pbx, can land on the client's contact in Bitrix24, so the CRM shows them
beside the portal's own calls. It is off until you turn it on, and it writes each call once.

Bitrix24 lets only an application write a call, not a webhook. Sign the profile in as a local application first:
`b24 work session start --portal <portal> --client-id <id>`. Then turn it on and allow its two methods:
Bitrix24 lets only an application write a call, not a webhook. Sign the profile in as a local application first
([with a local application](usage.md#with-a-local-application)), with your portal's host and Application ID in place
of these examples:

```sh
b24 work session start --portal example.bitrix24.ru --client-id local.0123abcd.45678901
```

Then turn it on and allow its two methods:

```sh
b24 work config set export_calls true
Expand Down
13 changes: 11 additions & 2 deletions docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,22 @@

# Commands

Every command, option and exit code, generated from the program itself. For the same list as JSON, run
`b24 commands --json`.
Look up any `b24` command: what it does, its arguments and options, what it answers and
how it can fail. Every entry is generated from the program itself, so it matches that release of `b24`.

You or your agent find the exact words for a task here, such as the query fields of `deals list` or the options
of `deals move`. For the same list as JSON, an agent runs `b24 commands --json`.

**The first word is the profile**, a name you choose: `b24 work config show`. `B24_PROFILE`
does the same for a whole shell session. No profile is assumed: a command that uses an account stops without one and
lists the profiles on this computer.

**On this page:**

1. [Options for every command](#options-for-every-command)
2. [The commands](#b24-commands), one section for each group, from `commands` to `runs`
3. [Exit codes](#exit-codes)

## Options for every command

| Option | What it does |
Expand Down
22 changes: 19 additions & 3 deletions docs/configuration.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,23 @@
# Settings

Settings live in one file, `config.json`, in the folder `b24 doctor` shows. Each profile has its own part,
and `defaults` apply to every profile. This page lists how to see and change them.
Change how `b24` works for one portal, or for every portal on this computer, with one command, and see where each
value came from. You change only the few that matter to you, and the rest keep their defaults or stay unset.

You decide, for example, what an agent may do, or whether call recordings are copied. Only you can loosen a
permission: an agent that tries is refused.

Settings live in one file, `config.json`, in the folder `b24 doctor` shows. Each profile has its own part, and
`defaults` apply to every profile. `b24 work config` shows and changes them.

**On this page:**

1. [See and change a setting](#see-and-change-a-setting)
2. [Permissions](#permissions)
3. [Calls](#calls)
4. [CRM relationships](#crm-relationships)
5. [Run records](#run-records)

## See and change a setting

```sh
b24 work config show
Expand Down Expand Up @@ -35,5 +51,5 @@ type means). [Who is who](usage.md#who-is-who) shows both.

A command that fails is kept as a run, for `b24 runs list` and `runs show`. A command that calls the portal is kept
when it succeeds too, with the requests it made, unless `record` is `false` (then only failures) or it ran with
`--no-record`. `record_input` decides whether a run keeps the words you typed; it is `true` unless you set it to `false`. Secrets are masked either way; see
`--no-record`. `record_input` decides whether a run keeps the words you typed. It is `true` unless you set it to `false`. Secrets are masked either way. See
[Security](security.md).
Binary file modified docs/images/social-preview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
42 changes: 32 additions & 10 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,37 @@
# b24

`b24` is a WireCat command-line tool for a Bitrix24 portal's sales data, for the terminal, for scripts and for AI
agents. It reads and changes deals, leads, contacts (`people`) and companies (`organizations`), and reads pipelines,
stages, products and employees (`users`). `sync` copies pipelines, companies, contacts, deals and leads into the
local WireCat store, which `deals`, `leads`, `pipelines` and `stages` read, offline too; contacts, companies,
products and employees are read from the portal.
Know where every deal stands and what a client said on the phone, without opening Bitrix24. Ask your AI agent in plain
words, in Claude Code, Codex or any app that speaks MCP. The portal keeps your deals in the cloud, and every question
to it is a live request, at about two a second for all its apps together. `b24` reads them through the portal's REST
API and keeps a copy on your computer, so most answers need no request at all.

If the company's phones run through Bitrix24 telephony, `meetings sync` copies its calls too, and `meetings
transcribe` turns their recordings into text on this computer: see [Calls](calls.md).
An agent with `b24` tells you which deals are stuck in a stage and what changed overnight. It moves a deal, closes it
or updates a contact when you ask, as far as the permissions you set allow.

It signs in with an incoming webhook of the portal, and acts with the rights of the employee who made that webhook.
`b24 work session status --check` says who that is, for the profile `work`.
`b24` is a WireCat command-line tool, a program you or your agent run in a terminal. `sync` copies your deals and
leads with their clients into the WireCat local store, the one file on your computer that the WireCat tools share.
`search all` then finds a deal beside your messages, notes and meetings from the other tools. You need one inbound
webhook in Bitrix24, which `b24 work setup` helps you make.

Start with [installation](installation.md), then [usage](usage.md).
**On this page:**

1. [Start](#start)
2. [Every page](#every-page)

## Start

[Install](installation.md) takes you from nothing to a signed-in profile and the first sync. Then [use it](usage.md)
shows the everyday commands and how to give `b24` to an agent.

## Every page

1. [Install](installation.md): install, make the webhook or a local application, sign in.
2. [Use it](usage.md): profiles, the sync, reading and changing deals, the morning digest, agents.
3. [Calls](calls.md): the portal's calls in the store, and their recordings as text.
4. [MCP](mcp.md): give `b24` to an agent that cannot run commands.
5. [Permissions](permissions.md): what an agent may read, change or must ask about.
6. [Commands](commands.md): every command, option and exit code.
7. [Settings](configuration.md): where settings live and how to change them.
8. [When something goes wrong](troubleshooting.md): symptoms and what to do.
9. [Security](security.md): where the webhook is kept and what never reaches a log.
10. [Roadmap](roadmap.md): what comes next.
47 changes: 34 additions & 13 deletions docs/installation.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,53 @@
# Install

Install `b24` once on each computer where you or an agent use it. You need Node.js 22.16 or a later 22.x, or 24 or
later; Node 23 is not supported.
Get `b24` running on your computer and connected to your Bitrix24 portal in a few minutes. Bitrix24 lets a program
in only through an inbound webhook or an application you create in the portal, and this page sets up one of them.

```sh
npm install -g @wirecat/bitrix24-cli
b24 --version
```
Once it is done, an agent on this computer reads your deals, leads and clients, and changes them when you ask.

npm installs `b24` as a command, and `b24 skill install` teaches your agent to use it. `b24 work setup` shows where to
make the webhook in Bitrix24 and which permissions (scopes) to tick, checks the webhook's address against the portal
and keeps it in the system keyring. `b24 doctor` shows what is set up, without the network. You need Node.js 22.16 or
a later 22.x, or 24 or later. Node 23 is not supported.

**On this page:**

1. [Install the tool](#install-the-tool)
2. [Sign in](#sign-in)

## Install the tool

Check the installation, then pick a profile name for your account, such as `work`:
Install `b24` once on each computer where you or an agent use it.

```sh
npm install -g @wirecat/bitrix24-cli
b24 --version
b24 skill install # the agent skill, for Claude Code, Codex, Gemini CLI and OpenClaw
b24 doctor
```

`doctor` needs no network and opens no keyring. It shows the version, where settings live, the profiles that
exist, and whether other users of the computer can read the settings. Next: [use it](usage.md).
An agent with no terminal, such as Claude Desktop, uses `b24` over [MCP](mcp.md) instead. `doctor` needs no network
and opens no keyring. It shows the version, where settings live, the profiles that exist, and whether other users of
the computer can read the settings. Then pick a profile name for your portal, such as `work`.

## Sign in

The quick way is an inbound webhook. `b24 work setup` walks you through it step by step, the same steps WireCat
Desktop shows; `b24 work session start` just asks for the address. The steps and the scopes to tick are in
Desktop shows. `b24 work session start` just asks for the address. The steps and the scopes to tick are in
[sign in](usage.md#sign-in).

With a local application, `b24` acts with the rights of the employee who signs in, not of the one who made a
webhook. Create it once in the portal (Developer resources → Common use cases → Other → Local application), in
**Server** mode, with **Your handler path** `https://wirecat.dev/webhooks/apps/b24-callback`, an empty **Initial
installation path**, no menu item text, and the access permissions `crm`, `user_basic` and `department`, `task` for
tasks, `telephony` for calls, and `disk` and `documentgenerator` for files and documents. Then run
`b24 work session start --portal example.bitrix24.ru --client-id <Application ID>` and give it the Application key
when it asks. The steps are in [with a local application](usage.md#with-a-local-application).
tasks, `telephony` for calls, and `disk` and `documentgenerator` for files and documents. Then run `session start`
with your portal's host and the Application ID Bitrix24 shows. Here the host is `example.bitrix24.ru` and the ID
`local.0123abcd.45678901`, so put your own in their place:

```sh
b24 work session start --portal example.bitrix24.ru --client-id local.0123abcd.45678901
```

Give it the Application key when it asks. The steps are in [with a local application](usage.md#with-a-local-application).

Next: [use it](usage.md).
24 changes: 17 additions & 7 deletions docs/mcp.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,22 @@
# MCP

Use this page to give an AI agent your CRM over MCP (Model Context Protocol), the way an agent asks a program what it
can do and then calls it. An agent with a terminal, such as Claude Code or Codex, does better with the commands and
the skill (`b24 skill install`). MCP is for a client that cannot run commands: a chat app, a remote agent, ChatGPT or
Claude in the browser.
Give your Bitrix24 CRM to an AI agent that cannot run commands, such as Claude Desktop, or ChatGPT and Claude in the
browser. MCP (Model Context Protocol) is the way such an agent asks a program what it can do and then calls
it, and `b24` serves its commands that way.

Before you start, sign the profile in (`b24 work session start`, with a webhook or a local application) and read
[Permissions](permissions.md): over MCP a write at `ask` goes ahead.
The agent then reads your deals, leads and clients, and changes them as far as the profile's permissions allow.

`b24 work mcp add` adds the server to Claude Code or Codex, and `b24 work mcp config` prints the entry for any other
client. An agent with a terminal, such as Claude Code or Codex, does better with the commands and the skill
(`b24 skill install`). You need a signed-in profile, and a look at [Permissions](permissions.md) first: over MCP a
write at `ask` goes ahead.

**On this page:**

1. [Add b24 to an agent](#add-b24-to-an-agent)
2. [What the agent sees](#what-the-agent-sees)
3. [Keep writes yours](#keep-writes-yours)
4. [ChatGPT and Claude in the browser](#chatgpt-and-claude-in-the-browser)

## Add b24 to an agent

Expand Down Expand Up @@ -35,7 +45,7 @@ The server has three tools:

A command is named as on the command line, without the profile, and checks the same permission key. These are never
offered over MCP: `api call`, `session start` and `session end`. The agent asks you to run them in a terminal. Of
`schedule`, MCP runs `list`, `run` and `exec`; the commands that add, change or remove a timer are refused unless
`schedule`, MCP runs `list`, `run` and `exec`. The commands that add, change or remove a timer are refused unless
`permissions.mcp.authority` is `allow`.

Text from the portal comes marked `untrusted`: deal and lead titles, pipeline and stage names, the names of contacts,
Expand Down
Loading
Loading