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:
- How Asterisk keeps calls
- What you need
- Install
- Connect in WireCat Desktop
- Connect from the terminal
- Numbers, directions and people
- Import the history, then keep it current
- Transcribe
- Search the calls with everything else
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 databaseasteriskcdrdb. - One call, several records. A ring group writes one record for each phone it rang, and a transfer one for each
leg.
pbxjoins 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.pbxfinds 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.
-
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
pbxruns:You have Records in You need Plain Asterisk, cdr_csvonMaster.csv, usually/var/log/asterisk/cdr-csv/Master.csvread 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.
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 doctorThe 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.
- On the Tools page, choose Install beside Asterisk, then Manage.
- Under Accounts, add an account with a name for this phone system, such as
office, and choose Sign in here. - Under Where are the call records?, choose Master.csv file, MySQL or MariaDB or PostgreSQL. Then
choose where
Master.csvand the recordings are: On this computer or On the PBX, over SFTP. - 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.
- 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.
- 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. - 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).
pbxreads 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.
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 setupAnswer 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.
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 startMaster.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.
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 startcdr_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.
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 startdb_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 startBoth are checked by reading the newest call records, then kept in one keyring entry of the profile.
pbx office config set recordings_path /var/spool/asterisk/monitorA call's recording is found in this order:
- the record's
recordingfilecolumn, which FreePBX fills, under the date folderYYYY/MM/DDor the folder itself; a name that leads outsiderecordings_pathis ignored; - 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_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 startThe 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.
phone_regionis the country of numbers written without+, such asrufor89161234567. 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+or00are 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, as612345678fits Spain, Germany and France, is kept as written and linked to no one, since a wrong country would join a stranger's contact;meetings syncsays how many callers that left. List only the countries your phone lines serve: a call from anywhere else comes with its+or00. extension_patternis 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-pstnorfrom-didcontext, 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 asmanagerthe extension that placed it and each extension that answered. A hidden number (anonymous,Restricted) or a dialplan name such assis 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.
An extension gets its name from three places. The first one that has a name wins:
-
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 setupand WireCat Desktop ask for it on the recordings step too. -
FreePBX's own list of extensions, the table
asterisk.users, when the CDR is in FreePBX's MySQL.pbxreads it with the same database user, and reads only two columns:extensionandname. 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 startandsession status --checkprints one note that the names were not read fromasterisk.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. -
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.
pbx office meetings sync --since-time 2024-01-01T00:00:00Z # once: everything since then
pbx office meetings sync # later: what is newEach 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.
pbx models download gigaam-v3 # Russian; models list shows the others
pbx office meetings transcribe --max-meetings 50Recognition 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 --replaceEach 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.
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 transcribeThe 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.
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.