Skip to content

Latest commit

 

History

History
403 lines (312 loc) · 22.4 KB

installation.md

File metadata and controls

403 lines (312 loc) · 22.4 KB

Install and connect

Asterisk writes a line about every call to its call log and keeps each recording as a sound file, but it gives your AI agent no way to read them. Services that turn recordings into text usually send them to the cloud. pbx, a WireCat command-line tool, reads the call log and the recordings where Asterisk keeps them, changes nothing on the phone system, and turns the recordings into text on your computer. Cloud transcription is an option you turn on for one profile.

Once it is connected, you can ask your agent who called about an order last week and what was agreed, find every call from one number, or see a caller's calls next to their chats, mail and CRM card. pbx keeps each call in the local WireCat store, and Memo and the search of every WireCat tool find it there with the rest of your data.

You connect pbx once per phone system. It needs read access to the call log, as a file or as a database user that may only read, and to the recordings folder if you want the text of the calls. WireCat Desktop and pbx office setup in a terminal ask the same questions; a script sets each setting with config set.

On this page:

  1. How Asterisk keeps calls
  2. What you need
  3. Install
  4. Connect in WireCat Desktop
  5. Connect from the terminal
  6. Numbers, directions and people
  7. Import the history, then keep it current
  8. Transcribe
  9. Search the calls with everything else

How Asterisk keeps calls

Asterisk is a phone system (PBX): the company's phone numbers and its employees' phones run through it. FreePBX, Issabel and VitalPBX are Asterisk with a web admin panel, and keep calls the same way.

  • Extensions. Each employee's phone has a short internal number, such as 101. A ring group (600) rings several phones at once, and a queue (700) keeps a caller waiting until someone is free.
  • Call records (CDR). When a call ends, Asterisk writes a record of it: who called whom, when, how long, and whether someone answered. The records go to the file Master.csv, to a database table, or to both. FreePBX keeps them in its MySQL database asteriskcdrdb.
  • One call, several records. A ring group writes one record for each phone it rang, and a transfer one for each leg. pbx joins them back into one call and says what became of it: answered, voicemail, busy or not answered, who answered, how long the caller waited and how long they talked.
  • Recordings. When recording is on, Asterisk saves one sound file per call, usually under /var/spool/asterisk/monitor. pbx finds each call's file by its name and links it to the call. It never copies, moves or changes the file.

pbx only reads. It needs no change to the dialplan (the rules that route calls), no Asterisk Manager Interface (AMI) or REST Interface (ARI) account, and nothing installed on the phone system.

What you need

  • Asterisk 1.8 or later, or a system built on it: FreePBX, Issabel, VitalPBX. The record fields are those of the CDR specification.

  • The call records, readable from the computer where pbx runs:

    You have Records in You need
    Plain Asterisk, cdr_csv on Master.csv, usually /var/log/asterisk/cdr-csv/Master.csv read access to the file
    FreePBX, Issabel, VitalPBX MySQL or MariaDB (cdr_mysql, cdr_adaptive_odbc) a read-only database user
    Records in PostgreSQL PostgreSQL (cdr_pgsql) a read-only database user

    Not sure? On the phone system, asterisk -rx "cdr show status" lists the modules that write records.

  • The recordings, if you want the text of the calls: a folder this computer can read, a folder mounted read-only, or the phone system's own folder over SFTP. WAV, wav49 (.WAV), GSM, MP3, Ogg, Opus, FLAC and M4A are found.

Install

WireCat Desktop installs pbx for you: go on to connect in WireCat Desktop.

In a terminal, install it once on each computer where you or an agent use it. It needs Node.js 22.16 or a later 22.x, or 24 or later; Node 23 is not supported. Turning WAV and GSM recordings into text also needs ffmpeg on PATH.

npm install -g @wirecat/asterisk-cli
pbx --version
pbx doctor

The command is pbx, and wcat-pbx is the same tool. Neither is called asterisk, so it can run on the phone system too without hiding Asterisk's own program. pbx doctor needs no network and opens no keyring: it shows the version, where the settings live, the profiles that exist, and whether other users of the computer can read the settings.

Connect in WireCat Desktop

  1. On the Tools page, choose Install beside Asterisk, then Manage.
  2. Under Accounts, add an account with a name for this phone system, such as office, and choose Sign in here.
  3. Under Where are the call records?, choose Master.csv file, MySQL or MariaDB or PostgreSQL. Then choose where Master.csv and the recordings are: On this computer or On the PBX, over SFTP.
  4. Over SFTP, fill in the Server, the User and the Password of the SFTP user. Leave the Server key empty the first time. The check then stops and shows the server's key. Compare it with the key on the phone system (see files on the PBX over SFTP), paste it, and check again.
  5. For Master.csv file, give its Path of Master.csv: on this computer a copy of the file or a shared folder that holds it, over SFTP its path on the phone system.
  6. For a database, fill in Database server, Database name, User and the Password of the database user. Port (optional) stays empty for the usual port. Turn on Encrypted connection when the database is not on your own network. When the database listens only on the phone system itself, as in FreePBX, open Through an SSH tunnel (optional) and fill in the SSH server, its user and password. The Database server is then 127.0.0.1, the database as the phone system sees it.
  7. Recordings folder (optional) is the folder of the call recordings. Calls come in without it too. Under Countries of your phone lines, choose the countries. The form explains: "Callers are matched to your contacts by phone number. Asterisk often writes a number without its country code, so pick the countries your phone lines serve. Calls from other countries arrive with their + code anyway." Names of the extensions (optional) names employees who never place a call (see names of the extensions).
  8. pbx reads the newest hour of calls to check the settings, and changes nothing. The settings and the passwords are saved only when that check works. When it refuses a password or a setting, the form goes back to the step that has it. The sync then brings in the calls of the last 30 days, with their recordings.

These questions come from pbx itself, so WireCat Desktop and the terminal always ask the same ones. An older WireCat Desktop shows its own shorter form, without SFTP and the SSH tunnel.

The time zone of the records and the recordings' file names are on the account's Settings page. To turn recordings into text, see transcribe.

Connect from the terminal

A profile is the name you give one phone system, such as office. It is the first word of every command that reads that system's calls. pbx office setup asks the questions of WireCat Desktop one by one, checks the answers by reading the newest calls, and saves the settings and the passwords only when that works:

pbx office setup

Answer a choice with its number, the countries as codes separated by commas (ru, es), and a password typed hidden. Press Enter to keep the value in brackets. Run it again to change a profile: a saved password is kept unless you ask to change it, but a changed server or user always needs its password typed again. When the check refuses a password or a setting, setup goes back to the step that has it.

A script, or a setting setup does not ask, uses config set and session start, as below. session start checks the settings by reading the newest calls, then keeps the passwords.

Master.csv

pbx office config set cdr_csv_path /var/log/asterisk/cdr-csv/Master.csv
pbx office config set cdr_timezone Europe/Moscow
pbx office session start

Master.csv has no header line. Which columns it has depends on loguniqueid, loguserfield and newcdrcolumns in cdr.conf ([csv]), and pbx tells them apart by each line's count, so lines written after you turn one on are read beside the older ones. Turn on loguniqueid and newcdrcolumns if you can: without the uniqueid, a recording cannot be found by its name, and without linkedid and sequence the records of one call are joined by their content only. If the guess is wrong, name the columns:

pbx office config set cdr_csv_columns "accountcode,src,dst,dcontext,clid,channel,dstchannel,lastapp,lastdata,start,answer,end,duration,billsec,disposition,amaflags,uniqueid"

Times in Master.csv are the phone system's local time unless usegmtime=yes. Set cdr_timezone to its zone, or to UTC when usegmtime is on. Without it, this computer's zone is used.

When pbx runs on another computer, read Master.csv over SFTP, or mount the log folder read-only, for example with sshfs pbx:/var/log/asterisk/cdr-csv ~/pbx-cdr -o ro.

A CDR database

Create a user that may only read the records table. On MySQL or MariaDB:

CREATE USER 'wirecat_reader'@'10.0.0.%' IDENTIFIED BY 'a long random password';
GRANT SELECT ON asteriskcdrdb.cdr TO 'wirecat_reader'@'10.0.0.%';

On PostgreSQL:

CREATE ROLE wirecat_reader LOGIN PASSWORD 'a long random password';
GRANT SELECT ON cdr TO wirecat_reader;

Then set the profile up and sign in. The password is asked hidden and checked before it is kept:

pbx office config set cdr_source mysql
pbx office config set db_host 10.0.0.5
pbx office config set db_name asteriskcdrdb
pbx office config set db_user wirecat_reader
pbx office config set cdr_timezone Europe/Moscow
pbx office session start

cdr_source postgres reads PostgreSQL. db_port changes the port (3306 for MySQL, 5432 for PostgreSQL), db_table the table (cdr), and db_tls true asks for an encrypted connection with a checked certificate. The session is opened read-only, and the only statement sent is a SELECT of the records that started after the last sync, in pages of 5,000.

A database behind the phone system's SSH

FreePBX's database listens on the phone system itself only. Do not open it to the network. pbx reaches it through an SSH tunnel (a secure connection through the phone system's remote login service) that it opens for each command and closes at the end. The tunnel only forwards to the database: it runs no command on the phone system and opens no port on your computer.

On FreePBX, make the database user on the phone system, as above, but for localhost:

CREATE USER 'wirecat_reader'@'localhost' IDENTIFIED BY 'a long random password';
GRANT SELECT ON asteriskcdrdb.cdr TO 'wirecat_reader'@'localhost';

Then point db_host at the database as the phone system sees it, and set the SSH server:

pbx office config set cdr_source mysql
pbx office config set db_host 127.0.0.1
pbx office config set db_name asteriskcdrdb
pbx office config set db_user wirecat_reader
pbx office config set db_ssh_host pbx.example.lan
pbx office config set db_ssh_user wirecat
pbx office config set db_ssh_key_path ~/.ssh/wirecat_pbx     # or leave it out to sign in with a password
pbx office session start

db_ssh_port changes the SSH port (22). The SSH user needs no shell: an account that may only forward a port is enough. The first session start connects only far enough to see the SSH server's key, and stops. It prints the key's fingerprint and the command that pins it (config set db_ssh_host_key SHA256:…). Compare it with the phone system's own, from ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub there, before you run that command.

Without a key file, session start asks two passwords: the database user's, then the SSH user's. Piped in, they go one per line in that order:

printf '%s\n%s\n' "$DB_PASSWORD" "$SSH_PASSWORD" | pbx office session start

Both are checked by reading the newest call records, then kept in one keyring entry of the profile.

Recordings

pbx office config set recordings_path /var/spool/asterisk/monitor

A call's recording is found in this order:

  1. the record's recordingfile column, which FreePBX fills, under the date folder YYYY/MM/DD or the folder itself; a name that leads outside recordings_path is ignored;
  2. a file whose name holds the call's uniqueid, in {yyyy}/{mm}/{dd}/ and then in the folder itself.

A dialplan that names files another way sets its own pattern, with {uniqueid}, {linkedid}, {yyyy}, {mm}, {dd} and *:

pbx office config set recordings_pattern "calls/{yyyy}-{mm}-{dd}/*{linkedid}*"

A file changed in the last two minutes may still be being written, so it waits for the next sync. A call without a recording is imported all the same. When the folder is on the phone system, read it over SFTP, or mount it read-only, for example sshfs pbx:/var/spool/asterisk/monitor ~/pbx-monitor -o ro, and set recordings_path to the mount.

Files on the PBX over SFTP

files_from sftp reads Master.csv and the recordings on the phone system itself, through its SSH server. Nothing is copied to a folder of its own and nothing is written there. Make a user that may only read those folders, for example one in the pbx group, then:

pbx office config set files_from sftp
pbx office config set sftp_host pbx.example.lan
pbx office config set sftp_user wirecat
pbx office config set sftp_key_path ~/.ssh/wirecat_pbx      # or leave it out to sign in with a password
pbx office session start

The first session start connects only far enough to see the server's key, and stops. It prints the key's fingerprint and the command that pins it. Compare the fingerprint with the phone system's own, from ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub there, and only then run that command (config set sftp_host_key SHA256:…). No password or key is sent to a server whose key is not pinned, and a server whose key changes is refused. Then session start asks the SFTP password, if there is no key file, checks it by reading the newest call records, and keeps it in the keyring.

Paths are the phone system's: cdr_csv_path /var/log/asterisk/cdr-csv/Master.csv, recordings_path /var/spool/asterisk/monitor. A profile that reads its records from a database and its recordings over SFTP with a password asks both passwords, the database's first; with an SSH tunnel too, the order is the database's, the SSH user's, then the SFTP user's. A dropped connection is opened again and the file is read on from where it stopped; a wrong password, a changed key or a missing file is not tried again.

Numbers, directions and people

  • phone_region is the country of numbers written without +, such as ru for 89161234567. Numbers are then kept as +79161234567, the form the other WireCat tools use, so the caller is the same person in calls and chats. Without it, only numbers written with + or 00 are made international.
  • An office that takes calls from several countries lists them: es,ru. A number is read in the country it fits. A number that fits two of them, as 612345678 fits Spain, Germany and France, is kept as written and linked to no one, since a wrong country would join a stranger's contact; meetings sync says how many callers that left. List only the countries your phone lines serve: a call from anywhere else comes with its + or 00.
  • extension_pattern is a regular expression for your internal extensions; the default, ^\d{2,5}$, takes numbers of two to five digits. A side of the call is internal when its channel (PJSIP/101-…) or its number matches.
  • A call is incoming when an outside number reached an extension or came in through a from-trunk, from-pstn or from-did context, outgoing when an extension called an outside number, internal between two extensions. Otherwise its direction is left empty.
  • A call's people are the outside number as client, with the caller ID name when the phone system had one, and as manager the extension that placed it and each extension that answered. A hidden number (anonymous, Restricted) or a dialplan name such as s is no person.
  • A ring group or queue reaches its members through Local/<extension>@… channels; the extension in that channel, not the group's number, is the member who answered.

Names of the extensions

An extension gets its name from three places. The first one that has a name wins:

  1. extension_names, which you set. Use it for employees who only answer calls and never place one:

    pbx office config set extension_names "101=Anna Smirnova,103=Vera Orlova"

    pbx office setup and WireCat Desktop ask for it on the recordings step too.

  2. FreePBX's own list of extensions, the table asterisk.users, when the CDR is in FreePBX's MySQL. pbx reads it with the same database user, and reads only two columns: extension and name. That table also keeps each phone's password, so give the user only those two columns, never the whole table:

    GRANT SELECT (extension, name) ON asterisk.users TO 'wirecat_reader'@'10.0.0.%';

    Without this grant the sync still works. The check in pbx office setup, session start and session status --check prints one note that the names were not read from asterisk.users. A sync prints no note, so a sync that cron runs stays quiet. A plain Asterisk without FreePBX has no such table, and the check shows the same note. Give the grant later, and the next sync reads the names.

  3. The caller ID of a call the extension placed, such as "Oleg Petrov" <101>. An employee who never calls out has no name from here.

A sync that reads a call again keeps the name the call already has, even when this time no call of that extension named it.

Import the history, then keep it current

pbx office meetings sync --since-time 2024-01-01T00:00:00Z   # once: everything since then
pbx office meetings sync                                     # later: what is new

Each sync reads again the six hours before the last one, since a call is written to the records only when it ends. A call already imported is updated, never doubled. A record that cannot be read is skipped and counted on stderr; the rest are imported. Run the sync by hand, or from cron or a systemd timer.

Transcribe

pbx models download gigaam-v3       # Russian; models list shows the others
pbx office meetings transcribe --max-meetings 50

Recognition runs on this computer, and the recordings are not sent anywhere. A recording already transcribed is not read again unless the file changed; --replace transcribes again. A recording on the phone system is copied over SFTP into a private temporary file for the time it is read, and deleted after.

A recording can be up to one hour long. A WAV, GSM or M4A file can be of any size; an MP3, Ogg or FLAC file can be up to 64 MB, which is more than an hour at usual phone quality. A call that is not transcribed is listed with the reason, and the rest go on. WAV, GSM and M4A need ffmpeg.

Each line of a transcript can name who said it. Your dialplan records the two sides of a call either as one mixed track (mono) or on two channels (stereo). A stereo recording keeps the channels apart, in every format. Tell pbx which side is on the first channel:

pbx office config set recordings_channels employee,caller    # or caller,employee
pbx office meetings transcribe --replace

Each line then names the caller by name and number, such as Ivan Testov +79000000001, or the employee by extension and name, such as 101 Oleg Operatorov. Without the setting, the lines say Channel 1 and Channel 2. To find out which side is on which channel, transcribe one call and read it. A mono recording gives the text without names. A call between two extensions keeps Channel 1 and Channel 2, since it has no caller from outside.

Cloud transcription

A profile can send its recordings to OpenAI's speech-to-text service in place of the local model. It is off unless you turn it on for that profile; a setting in the shared defaults does not turn it on.

pbx office config set transcribe_engine openai
pbx office config set transcribe_model gpt-transcribe        # optional; gpt-transcribe when not set
OPENAI_API_KEY="$(secret-tool lookup service openai)" pbx office meetings transcribe

The key is given for that one run, read from your keyring, so it never lands in the shell history. On macOS, security find-generic-password -s openai -w reads it in place of secret-tool. Keep it under whatever name your keyring uses.

What leaves your computer: the speech of each recording, in pieces of at most ten minutes, sent to api.openai.com, or to the OpenAI-compatible address of WireCat's shared AI model when another WireCat tool set one. The call's number, names, times and the file name are not sent. Before the first piece goes, the run says on stderr where the audio goes. The text comes back and is kept in the local store, as a local transcript is.

The run still needs one local speech model downloaded (pbx models download gigaam-v3): the voice detector that cuts the speech into pieces comes with it. Without the key, the run stops before it reads a recording. PBX_READ_ONLY=1 refuses cloud transcription, and so does WireCat's shared local-only switch when it is on. Recording a call and sending it to a service may need the consent of the people on it; see security. config set transcribe_engine local turns it off again.

Search the calls with everything else

The calls are in the WireCat store every WireCat tool reads. An agent with memo asks about one person across calls, chats and mail; search all in any WireCat CLI searches them together. Next: use it, how commands are built and how an agent reads the calls.