Connect your Asterisk — Asterisk

pbx reads two things from your PBX: the call records (CDR) and, when there are any, the recordings. This page says where to find each, what access to give, and how to set a profile up. It needs no change to the dialplan and no Asterisk Manager Interface (AMI) or REST Interface (ARI) account.

What is supportedCopy Anchor Link

• Asterisk 1.8 and later, and the systems built on it: FreePBX, Issabel, VitalPBX. The CDR fields are those of the CDR specification.
• Call records from one of:
  • Master.csv, written by the cdr_csv module, usually /var/log/asterisk/cdr-csv/Master.csv;
  • a MySQL or MariaDB table (cdr_mysql, cdr_adaptive_odbc; FreePBX keeps it in asteriskcdrdb.cdr);
  • a PostgreSQL table (cdr_pgsql).
• Recordings in a folder this computer can read, a folder mounted read-only, or the PBX's own folder over SFTP. WAV, wav49 (.WAV), GSM, MP3, Ogg, Opus, FLAC and M4A are found; WAV and GSM need ffmpeg to be transcribed.

Checked so far with the made-up records and recordings in examples/, built from the CDR specification and the cdr_csv source, not yet with a live PBX.

Choose a sourceCopy Anchor Link

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

Master.csvCopy Anchor Link

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

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 legs of a transfer are told apart 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 PBX's local time unless usegmtime=yes. Set cdr_timezone to the PBX's 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 on the PBX over SFTP (below), or mount the PBX's log folder read-only, for example with sshfs pbx:/var/log/asterisk/cdr-csv ~/pbx-cdr -o ro.

A CDR databaseCopy Anchor Link

Create a user that may only read the CDR 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

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 rows that started after the last sync, in pages of 5,000.

FreePBX's database listens on the PBX itself only. Do not open it to the network; reach it through SSH instead, and point db_host at the tunnel:

ssh -N -L 3306:127.0.0.1:3306 [email protected] &
pbx office config set db_host 127.0.0.1

RecordingsCopy Anchor Link

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

A call's recording is found in this order:

1. the CDR'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 written by MixMonitor, so it is left for the next sync. A call without a recording is imported all the same. The recording is linked by its path: it is never copied, moved or changed. When the folder is on the PBX, read it over SFTP (below), 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 SFTPCopy Anchor Link

files_from sftp reads Master.csv and the recordings on the PBX 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 PBX'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 PBX's: cdr_csv_path /var/log/asterisk/cdr-csv/Master.csv, recordings_path /var/spool/asterisk/monitor. A profile that reads its CDR from a database keeps that database's password, so its SFTP side signs in with a key file. A dropped connection or a timeout is tried again; a wrong password, a changed key or a missing file is not.

Numbers, directions and peopleCopy Anchor Link

• 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.
• 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.
• Each call has two people: the extension as manager, the outside number as client, with the caller ID name when the PBX had one. A hidden number (anonymous, Restricted) or a dialplan name such as s is no person.
• A Local/ channel, which queues, ring groups and follow-me use, names what was dialled, not who is on the line, so the number decides that side.

Import the history, then keep it currentCopy Anchor Link

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 CDR only when it ends. A record already imported is updated, never doubled. A row 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.

TranscribeCopy Anchor Link

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

Recognition runs on this computer. A recording already transcribed is not read again unless the file changed; --replace transcribes again.

Search the calls with everything elseCopy Anchor Link

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.