diff --git a/cspell.json b/cspell.json index f06c126..6f12883 100644 --- a/cspell.json +++ b/cspell.json @@ -5,6 +5,7 @@ "words": [ "asterisk", "Bitrix", + "Deepgram", "whatsapp-cli", "tg-cli", "max-cli", diff --git a/docs/index.md b/docs/index.md index 6b7c8f4..f4ba610 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,69 +1,154 @@ # Asterisk -A company's phone calls hold what clients asked for and what employees promised, but on an Asterisk phone system -they sit in a call log and a folder of recordings that no AI agent can read. `pbx`, the WireCat command-line tool for -Asterisk, reads them where they are and keeps each call on your computer, with what became of it and what was said. +Know what every client asked for on the phone and which calls nobody returned, without listening to a single +recording. `pbx` gives the AI agent you already use, such as Claude Code or Codex, the calls of your Asterisk phone +system: each call on your computer, with what became of it and what was said, turned into text there. -Your agent can then prepare you for a callback, list the calls nobody returned, report a week of calls by employee, -find the calls where a client was unhappy, and quote the call behind every answer. Each call sits next to the same person's chats, mail and CRM deals, because -all WireCat tools keep their data in one local store. +Your agent can then prepare you for a callback, list the missed calls, report a week of calls by employee and find +the calls where a client was unhappy, quoting the call behind every answer. It works with plain Asterisk, FreePBX, +Issabel and VitalPBX, and installs nothing on the phone system. **On this page:** -1. [What you can do](#what-you-can-do) -2. [How it fits with the rest of WireCat](#how-it-fits-with-the-rest-of-wirecat) -3. [What it does not do yet](#what-it-does-not-do-yet) -4. [Where to start](#where-to-start) +1. [What you get](#what-you-get) +2. [Things a newcomer would not guess](#things-a-newcomer-would-not-guess) +3. [How it looks](#how-it-looks) +4. [Why pbx](#why-pbx) +5. [What it can do](#what-it-can-do) +6. [With your other WireCat tools](#with-your-other-wirecat-tools) +7. [How it works](#how-it-works) +8. [Start](#start) +9. [Limits](#limits) +10. [Find a guide for your task](#find-a-guide-for-your-task) -## What you can do +## What you get -- **See each call as one call.** A ring group, a queue or a transfer writes several records; you get one call with - its outcome (answered, voicemail, busy, not answered), who answered, how long the caller waited and talked. -- **Read what was said.** Recordings are turned into text on your computer. No recording or transcript leaves it, +- **Each call as one call.** A ring group, a queue or a transfer writes several records. You get one call with its + outcome, who answered, and how long the caller waited and talked. +- **Calls you can read.** Recordings become text on your computer. No recording or transcript goes to a speech service, unless you turn on cloud transcription for one profile. -- **Count the calls.** `stats calls show` gives the calls by direction and outcome, per employee, by hour and by day, - and the missed calls with whether the client was called back. -- **Find a call by what was said.** `search meetings` finds the calls by their words, or by their meaning with a text - model on your computer: "a client unhappy with the delivery" finds a call where nobody said those words. -- **Mark calls.** `tags add complaint --matching "refund"` marks every call the search finds. Run it again after new - calls are transcribed, and it marks only those. -- **Know who called.** A caller whose mobile number is in your CRM or your chats is the same person there. An office - that serves several countries lists them, and a number that could belong to two of them is never guessed. -- **Hand the work to an agent.** Callbacks, missed calls and the day by employee become requests in plain words; the - agent answers from the local store and shows its sources. [Use it](usage.md) has the requests. -- **Keep the phone system untouched.** `pbx` only reads: a database user that may only read, a file, or a folder over - SFTP with a pinned server key. Nothing is installed on the phone system, and it works with plain Asterisk as well as - FreePBX, Issabel and VitalPBX. - -## How it fits with the rest of WireCat - -- **Memo** answers questions about one person or project across calls, chats, mail and notes. -- **The CRM tools**, such as Bitrix24's `b24`, bring contacts and deals, so a caller's calls appear beside their - deal. -- **The messenger tools** (`tg`, `max`, `wa`) bring the chats with the same people. -- **WireCat Desktop** connects the phone system in a form, keeps the sync on a timer and shows the calls with their - recordings. -- **Your agent** reaches it from a terminal with the tool's skill, or from an app over MCP, with each command allowed, - asked or denied per profile. Words said on a call reach the agent as data, never as instructions. - -## What it does not do yet - -- **Summaries.** Your agent reads a transcript and writes the summary. `pbx` writes none of its own. -- **Playing a recording over SFTP.** WireCat Desktop plays a call's recording on the call's card when the - recordings folder is on this computer. When `pbx` reads the recordings over SFTP, the file stays on the phone - system, and the card cannot play it. There is no link that plays a recording in a browser. +- **No missed client forgotten.** Missed calls come with whether someone called back, next to the calls by employee, + hour and day. +- **A call found by what was said.** "A client unhappy with the delivery" finds a call where nobody said those words. +- **Calls marked for you.** Mark every call about refunds once, and the next run marks only the new ones. +- **The caller recognised.** A caller whose mobile number is in your CRM or your chats is the same person there. +- **The phone system untouched.** `pbx` only reads: a database user that may only read, a file, or a folder over + SFTP. + +## Things a newcomer would not guess + +- **`office` is a name you choose.** It names one phone system, and it is the first word of every command. No command + picks a phone system for you. +- **It reads the call log, not live calls.** Asterisk writes a record of each finished call, the call detail record + or CDR. `pbx` reads those records and the recordings. +- **The first sync reads 30 days back.** Each later sync reads only what is new, and a call is never stored twice. + Ask for an earlier date when you want more. +- **Recordings become text on your computer** with a speech model you download once. Cloud transcription is a choice + you make for one profile. +- **Over MCP, "ask" goes ahead.** MCP is the way apps such as Claude Desktop call a tool, and nobody sits there to + answer a question. Set what an agent must not do to read only or refuse before you connect it. + +## How it looks + +```text +You: Which calls did nobody return on 31 October? +Agent: (runs pbx office stats calls show --since-time 2026-10-31 --until-time 2026-10-31) + One: +7 900 000-00-03 at 14:00, call 3. It rang Oleg Operatorov on 101, and nobody called back. +You: Mark every call about a refund as a complaint. +Agent: (runs pbx office tags add complaint --matching "refund") + Done. The next run marks only the new calls. +``` + +## Why pbx + +- **Recordings stay with you.** Speech is recognised on your computer. FreePBX's Scribe module sends recordings to + Deepgram, a cloud speech service, as the [comparison](compare.md) shows. +- **No root login, nothing installed on the phone system.** Frogman's MCP setup connects to the PBX over SSH as root. + `pbx` runs on your computer with a user that may only read. +- **One caller across calls, chats, mail and the CRM.** No other tool on the comparison documents it. +- **Works without FreePBX.** FreePBX's own tools and Frogman need FreePBX. `pbx` reads plain Asterisk too. +- **A permission on every command.** Allow, ask, read only or refuse, for each profile. +- **Free and open source.** Apache 2.0. + +Another tool fits better when you want summaries and sentiment inside FreePBX's own portal and a cloud service is +fine (FreePBX with Scribe), or an agent that changes the phone system itself, such as ring groups and routes +(Frogman). + +## What it can do + +- **List and read calls:** by time, duration or number, one call with its recording and transcript, and an export to + Markdown or WebVTT subtitles. [Use it](usage.md) +- **Transcribe:** every new recorded call, newest first, with each line named by caller or employee when the recording + is stereo. [Install and connect](installation.md) +- **Count:** calls by direction and outcome, per employee, by hour and by day, and the missed calls with their + callbacks. [Use it](usage.md) +- **Search and mark:** by words or by meaning, and a tag on every call the search finds. [Use it](usage.md) +- **Agents:** a skill for agents with a terminal, and an MCP server for Claude Desktop, Cursor and other apps. + [Use it](usage.md) + +## With your other WireCat tools + +- **Memo** answers questions about one person across calls, chats, mail and notes. +- **The CRM tools**, such as Bitrix24's `b24`, bring contacts and deals, so a caller's calls appear beside their deal. +- **WireCat Desktop** connects the phone system in a form, keeps the sync on a timer and plays a call's recording when + the recordings folder is on your computer. + +## How it works + +- **A copy on your computer.** `meetings sync` reads the call records and links their recordings in the WireCat local + store that every WireCat tool shares. +- **Three places Asterisk keeps calls.** `Master.csv`, MySQL or MariaDB, and PostgreSQL. A database password is kept + in your system keyring. +- **Made for scripts and agents.** `--json` gives a JSON answer. Words said on a call reach the agent as data, never + as instructions. +- **What is stored, and the consent a recording may need.** [Security](security.md) + +## Start + +Connect it in [WireCat Desktop](https://wirecat.dev/en/docs/desktop) with a form, or paste this into your agent: + +```text prompt +Install pbx with npm install -g @wirecat/asterisk-cli. Help me connect our Asterisk call log and recordings as the profile office, sync the last 30 days and transcribe the new calls. +``` + +Or in a terminal, on a computer that can read the call log and the recordings: + +```sh +npm install -g @wirecat/asterisk-cli +pbx office config set cdr_csv_path /var/log/asterisk/cdr-csv/Master.csv +pbx office config set recordings_path /var/spool/asterisk/monitor +pbx office config set cdr_timezone Europe/Moscow # the phone system's time zone +pbx office config set phone_region ru # the country of numbers written without + +pbx office session start # checks the source +pbx office meetings sync # the last 30 days of calls +pbx models download gigaam-v3 # the local Russian speech model, once +pbx office meetings transcribe # up to 20 recorded calls +``` + +You need Node.js 22.16 or a later 22.x, or Node.js 24 or later, and `ffmpeg`. A database or SFTP connection instead +of local files: [install and connect](installation.md). + +## Limits + +- **No summaries of its own.** Your agent reads a transcript and writes the summary. +- **Playing a recording.** WireCat Desktop plays it when the recordings folder is on your computer. A recording read + over SFTP stays on the phone system, and no link plays a recording in a browser. - **Who said what in a mono recording.** A stereo recording names the caller and the employee on each line when you - set [`recordings_channels`](installation.md#transcribe). A mono recording, one mixed track, gives the text without - names. + set [`recordings_channels`](installation.md#transcribe). A mono recording gives the text without names. - **Long recordings.** A recording longer than one hour is not transcribed. The call is listed with the reason, and the rest go on. -- **Recognition quality.** The result depends on the recording and the model. A noisy line or a call in two - languages gives weaker text. - -[Compared with other tools](compare.md) puts these next to FreePBX's own tools, Frogman and asterisk-ai-call-notes. +- **Recognition quality** depends on the recording and the model. A noisy line or a call in two languages gives weaker + text. -## Where to start +## Find a guide for your task -- **New here:** [install and connect](installation.md), in WireCat Desktop or from a terminal. -- **Already connected:** [use it](usage.md), with requests for your agent and a schedule. -- **Something went wrong:** [troubleshooting](troubleshooting.md). +| Task | Guide | +|---|---| +| Install and connect, in WireCat Desktop or a terminal | [Install and connect](installation.md) | +| Requests for your agent, and a schedule | [Use it](usage.md) | +| Every command and option | [Commands](commands.md) | +| Settings and permissions | [Settings](configuration.md) | +| Something does not work | [When something goes wrong](troubleshooting.md) | +| What is stored, and recordings and consent | [Security](security.md) | +| How pbx differs from other Asterisk tools | [Compared with other tools](compare.md) | +| What comes next | [Roadmap](roadmap.md) |