CallerHub – Help

What CallerHub does

When someone calls, your phone system asks CallerHub: “Who is +49 711 1234567?” CallerHub looks up the phone number in your data sources (CRM, ERP, CSV file, Active Directory, Microsoft 365, Exchange, REST API) and returns the name within a few milliseconds. The phone system shows it on the phone.

Quick start

1. Copy the CallerHub program folder to the server, e.g. to C:\CallerHub (see Installation).
2. Start CallerHub.exe. On the first start, the setup wizard opens.
3. Step 2: apply the sample phone book Samples\customers.csv (or choose your own CSV file; for other layouts such as a DATEV export, use Map columns later). Step 3: select the phone system, enter the port (e.g. 8080) and the IP address of the phone system (e.g. 192.168.10.20). Step 4: run a test lookup with 030 1234560 – the result is “Testkunde GmbH - Frau Beispiel”.
4. Enter the displayed address and the API key in the phone system (instructions for each phone system under Interfaces → Phone system, see Setting up phone systems).
5. Later: on the Data sources page, use Add data source to create the real data source (e.g. SQL Server), click Test connection, then Save and apply. To find the right query, see Finding the query for your database.

Installation (CallerHub folder only)

CallerHub needs neither an installer nor a .NET installation: CallerHub.exe contains the .NET 10 runtime; the database drivers are in the Drivers subfolder. The CallerHub program folder from the delivery is sufficient. Everything the program writes is stored in subfolders of this folder.

Requirements

Folders and files

If the program folder is not writable (e.g. under C:\Program Files without permissions), CallerHub falls back to %LOCALAPPDATA%\CallerHub and shows this in the system health. Recommendation: use a dedicated folder with write permission for the service user, e.g. C:\CallerHub or D:\Dienste\CallerHub.

Steps

1. Copy the program folder to C:\CallerHub (extract the ZIP archive or run einrichten.cmd from the delivery). For a ZIP archive, first select “Unblock” in the file properties or run in PowerShell: Get-ChildItem -Recurse C:\CallerHub | Unblock-File. The program is not signed; Windows SmartScreen may show a warning on the first start.
2. Start CallerHub.exe → wizard. Without the wizard: choose “Add first data source” under Data sources, set up the phone system under Interfaces and click Save and apply.
3. Open the port: Administration → System health shows a missing port reservation or firewall rule with a button to fix it (prompt for administrator rights).
4. Optional (advanced mode, Full edition): Administration → Operation → Install as service (runs without sign-in, service name CallerHub).

Update to a newer version (from 3.0.0.0)

• Exit CallerHub or stop the service, copy the new folder content into the existing program folder and start CallerHub or the service again. Settings, logs and statistics are kept.
• Copy the complete folder content, including the Drivers subfolder: the Oracle driver and the native libraries are now there instead of directly next to CallerHub.exe. Leftovers of earlier versions – the folder native and a file Oracle.ManagedDataAccess.dll directly next to CallerHub.exe – are no longer needed and can be deleted once CallerHub has exited.
• The sample phone book is now called Samples\customers.csv (previously kunden.csv). Settings that still refer to kunden.csv use the new file automatically.
• Display name replacements now use the semicolon as separator (search;replace), like the block list and the VIP list. Existing lines with => keep working.

Uninstallation

Remove the service (Administration → Operation → Remove service), turn off Start at Windows sign-in (minimised), exit the program (Menu → Exit (interface stops) or notification area → Exit), delete the folder. Optionally remove the firewall rule CallerHub, the URL reservation (netsh http delete urlacl url=http://+:8080/) and the HTTPS certificate (netsh http delete sslcert ipport=0.0.0.0:8443).

Where data is stored – and how administrators verify it

Commitment: CallerHub stores data exclusively in its own program folder (subfolders Logs, Statistics, Backups, Help, Temp and the file CallerHub.settings.xml) and in the memory of the running process. It creates no database and does not write to your data sources. Everything can be viewed under Administration → Privacy (overview) and with Menu → Open folder → Program folder.

Verification steps for administrators

1. File access: start Sysinternals Process Monitor, set the filters Process Name is CallerHub.exe and Operation is WriteFile, make a few test calls and save once. All paths are in the program folder (exception: the fallback folder %LOCALAPPDATA%\CallerHub if the program folder is not writable – the system health reports this).
2. Open files: handle.exe -p CallerHub.exe (Sysinternals) or Resource Monitor → CPU → Associated Handles → search for “CallerHub”.
3. Network connections: PowerShell Get-NetTCPConnection -OwningProcess (Get-Process CallerHub).Id; older systems: netstat -ano | findstr <PID>. Expected: CallerHub's own port (listening), connections to the configured data sources and, for notifications, to the SMTP server or webhook. Discovery connections appear only after an explicit start.
4. Registry and Windows objects: reg query HKCU\Software\Microsoft\Windows\CurrentVersion\Run /v CallerHub, sc.exe query CallerHub, netsh http show urlacl, netsh http show sslcert, Get-NetFirewallRule -DisplayName CallerHub.
5. No database: CallerHub opens data sources with the configured user in read-only mode (SELECT, LDAP search, GET). Recommendation: create a database user with read permission only on the required tables or views; writing is then technically impossible.
6. Retention: CallerHub deletes older files in Logs and Statistics according to the settings when the interface starts and then once a day (on the first request of a day). Verify: Get-ChildItem C:\CallerHub\Logs | Sort-Object LastWriteTime | Select-Object -First 3.

Privacy (GDPR) and EU legal framework

This section is a technical description and not legal advice. Whether processing is permitted, and on which legal basis, is assessed by the controller – if in doubt, together with the data protection officer. The legal situation and its interpretation may change; check the current status.

Show current settings … on the same card shows the saved settings file with all passwords, keys and credentials replaced by ***, together with the encryption state (e.g. “Encryption: passwords and API keys encrypted (Windows DPAPI).”). This lets you check what is stored without opening the file.

Where personal data is processed

Relation to regulations

Note on the AI assistant: CallerHub does not call any AI interface. The text is anonymised before copying (phone numbers masked, email addresses replaced, IP addresses shortened, passwords and keys removed) and shown in the dialog for review. You paste it into the chat yourself; the terms of your chat account apply.

Data paths per setting

The Data flow (compact) tile on the start page and its button Details … show the paths for the current settings (even before saving); the full diagram is also available as the tile Data flow (detailed), which Print … prints, e.g. for the system documentation. The following examples show typical setups; arrow = direction in which the connection is established.

A · STARFACE Cloud, database in your own network

B · Phone system in your own network, Active Directory and CSV

C · Cloud sources, notifications, browser and monitoring

All connections

User interface and menu

The screenshots show sample data (test numbers, IP addresses from the documentation ranges 192.0.2.0/24, 198.51.100.0/24 and 203.0.113.0/24, generated statistics). Fonts may differ slightly under Windows.

Start page (dashboard)

There is no “Start” tab: click the CallerHub logo or name in the title bar to show the start page. The tabs next to it are Interfaces, Data sources, Statistics, Call analysis (only with the module) and Administration. Unsaved changes show a contrasting bar at the bottom with Discard and Save and apply; without changes the bar is hidden. Messages appear in CallerHub's own dialog without a system sound (Ctrl+C copies the text). When maximised, the window fills the work area of its monitor and leaves the taskbar free.

The start page is a dashboard of tiles in two columns: a wide one on the left and a narrow one on the right. In a window narrower than about 1100 px, the tiles of the right column follow below the left column; if the window is short, the page scrolls.

Customise … at the top of the start page opens the panel Show tiles: a check box per tile shows or hides it, Restore default returns to the layout above and Done closes the panel. While the panel is open, every tile has a grip ⠿ in the middle of its top edge: drag it to move the tile to another position or into the other column; a line shows where it will be placed. CallerHub saves the layout immediately – Save and apply is not needed.

• Status indicator at the top right: Running (green), Listening (green: the interface is running, but no phone system has sent a request since the start), Data error (amber: the interface is running, a data source reports an error), Error (red), Stopped, Not configured. A click shows the cause and a suggestion.
• System health at the top (in advanced mode with Start, Stop, Reload, Clear cache): short version of the Administration traffic light; a click opens the details.

Menu

The button ☰ at the top left opens the menu. Its items are grouped by task (settings, operation, view, help), separated by lines; in this help, “Menu → …” refers to it.

Command search (Ctrl+K)

Ctrl+K opens a search field across all pages, cards and actions. Examples: https → HTTPS wizard, block → Block list, plugin → Plugins, port → Server (port and start). The arrow keys select an entry, Enter jumps to it.

Inputs are validated immediately

Empty fields show a grey example (e.g. “e.g. dc01.company.local”). Invalid inputs turn the field red; the tooltip states the reason, e.g. “'192.168.10' is not an IP address. Example: 192.168.10.20 or 203.0.113.0/28”. Save jumps to the first invalid field and marks all missing fields of the same function. The mouse wheel does not change drop-down lists and number fields; it scrolls the page. Collapsed cards open with the Tab key, not when a button disables itself.

Exit

Closing the window leaves the interface running in the notification area. Menu → Exit (interface stops) or notification area → Exit stops the interface, timers, plugins and all background tasks and ends the process completely; afterwards the program folder can be deleted or replaced.

Simple and advanced mode

In simple mode (default), every page shows only what is needed for operation. Show advanced settings (menu group View, or the switch of the same name in the save bar) shows the remaining options; the choice is saved immediately. Hidden values remain in effect. The advanced mode is part of the Full edition and the trial.

Languages

English (default) and German are built in. Further languages are text files in the Languages folder of the program folder (e.g. lang_fr.txt, lang_ru.txt, lang_zh.txt). Every file lang_xx.txt appears automatically in the submenu Sprache / Language (menu group View) after a restart. The submenu has the heading “Select Language” and lists English first, then German and the other languages in alphabetical order, each with its flag and its English name in brackets, e.g. “Deutsch (German)”. Open the folder via Menu → Open folder → Languages.

A new language (or appearance) takes effect after a restart of the program. CallerHub asks in the dialog “Select Language” – in English and in the selected language – whether to Restart now or Later. Languages written from right to left (e.g. Arabic or Hebrew) are displayed from right to left.

• New language: copy an existing file (e.g. to lang_es.txt), adjust the header lines # Language: (name in the menu), # Culture: (date and number format, e.g. es-ES), # Source: en and optionally # Font:, and translate the text to the right of the tab in every line. The English text on the left is the key and stays unchanged; keep placeholders such as {0} and \n. Web addresses, paths, file names and technical names are not translated. Save the file as UTF-8. Details are in Languages\README.txt.
• If a translation is missing, the English text appears.
• lang_de.txt contains the German texts (English on the left, German on the right); changes on the right improve the German display.
• The help is currently available in English only; the German help follows once the English text is final. All languages open the English help.

French, Russian and Chinese are machine-translated and should be reviewed by native speakers before use with customers. Chinese uses the Windows font Microsoft YaHei UI.

Start page tiles

Customise … at the top right of the start page switches tiles on and off and moves them (drag the handle ⠿). Tiles added in version 3.0:

• Statistics: requests of the last 7 days – bars per day (dark: hits) and the link Detailed statistics …. With Administration → Module: Statistics → Show as a tile on the CallerHub page instead of a menu item, the tab Statistics disappears and this tile is switched on.
• Log (compact, live) – the latest 12 information, warning and error lines, updating itself every second; no search, reload, folder or detail buttons (the full log viewer is in the menu). Accesses are listed in “Recent requests”, not here.

Administration and system health

Everything technical is on the Administration page. The search field with the magnifying glass at the top filters as you type: only cards whose title, description, captions or options contain the text remain visible and open (e.g. port, e-mail, plugin; Esc clears the search). Collapsed cards show a large icon for orientation. At the very top is the System health (also at the top of the start page): all services, permissions and other concerns as a traffic light. It is checked at startup, after saving, with “Check again” and every 5 minutes.

For an incomplete or invalid setting, the system health shows an entry such as “Data source 'CRM' incomplete – skipped”, “Interface incomplete” or “Module incomplete – not active” with the button Open: it opens the page and card concerned and frames the field in red. After saving, CallerHub also frames all fields with a problem in the open card.

System health checks

The system health checks every 5 minutes and after saving; the display updates in place without flickering. Entries with a button can be fixed directly:

Actions that need administrator rights cannot be done by CallerHub alone: Windows shows a confirmation (UAC). On servers without a local administrator account, ask your IT to run the action or to create the firewall rule (see Firewall examples).

Other cards

In simple mode, the page shows the cards System health, Server, Notifications, Licence, Modules and Privacy, followed by the card More settings with the button Show advanced settings. The advanced mode adds the remaining cards (see Simple and advanced mode).

• Server: port, HTTPS, automatic start, start at Windows sign-in and (advanced mode) trusted reverse proxies for all interfaces, plus Start and Stop. All phone systems use the same port; CallerHub recognises them by their API key.
• Notifications: email and webhook on faults (see Notifications).
• Licence: enter and check a licence key (see Licence key).
• Modules: enable and disable functions. For each enabled module with settings, a card Module: … appears – statistics, call analysis, display name, block list and VIP list (global rules), notifications, browser access, plugins, network discovery.
• Privacy: storage locations according to the current settings and Show current settings … (see Privacy).
• Operation (advanced mode): five sections with a short explanation – Windows service, HTTPS, Windows event log, error analysis, back up settings (see Operation).
• Security (advanced mode): see Security and standards.
• Advanced (advanced mode): country code, name length, cache, log.

Data sources with sample values

In a new installation, no data source exists yet; the Data sources page then shows only Add first data source. Every data source is a card of its own; collapsed, it shows its type, target and state. Click a card to open it (the others close). The header row of the open card holds Label, Query (active), the state, Test connection (Check CSV file for a CSV file), up and down (order of the queries) and Remove. To change the order, you can also drag a card by its header to another position. Below are the steps: Step 1: Connection, Step 2: Phone number list (not for CSV files) and, in advanced mode, Step 3: Display and link (optional) and Step 4: Rules for this data source (optional). The counter at the top shows how many data sources exist, e.g. “2 of 10”. At most 10 data sources are possible (the Basic edition allows one); more are possible with a special licence (callerhub.de). Add data source at the top first asks for the source type (e.g. Microsoft SQL Server, Oracle, CSV file, REST API, LDAP) and the label; then the new card opens. The type can be changed in the Source field of step 1 only as long as no connection data is entered; for another type, add a new data source. Only the matching fields appear. When saving, all missing required fields of a data source are marked together. Test connection checks the values in the form (even unsaved), Save and apply activates them. All sample values below are fictitious and serve as examples.

Fields for all sources

Microsoft SQL Server

-- Number list (the column aliases nummer, anzeigename, rang, land and id are essential):
SELECT c.phone AS nummer, c.company + ' - ' + c.name AS anzeigename, 0 AS rang, c.country AS land, c.id AS id
FROM dbo.contacts c WHERE c.phone IS NOT NULL

Oracle

MySQL / MariaDB, PostgreSQL, other ODBC databases

The driver names depend on the installed version; the selection list shows the 64-bit drivers installed on this computer.

CSV file (also DATEV, Excel and CRM exports)

Standard format (without mapping): UTF-8, semicolon, no header row, lines starting with # are ignored.

# Phone number;Display name;Country (optional);Link (optional)
030 1234560;Testkunde GmbH - Frau Beispiel;DE;https://crm.example.com/kontakt/1001
+41 44 123 45 67;Beispiel AG Zürich;;
044 765 43 21;Muster Treuhand AG;CH;

Map columns reads CSV files with any layout, e.g. a debtor/creditor export from DATEV, an Excel list or a CRM export. When opened for the first time, CallerHub suggests a mapping based on the column names (phone, mobile, company, first/last name, country, account); Suggestion repeats this, Standard format removes the mapping. The preview shows the first rows of the file and the result.

"EXTF";700;16;"Debitoren/Kreditoren";…          ← DATEV header line, skipped
"Konto";"Name (Adressatentyp Unternehmen)";"Name (Adressatentyp natürl. Person)";"Vorname (Adressatentyp natürl. Person)";"Land";"Telefon";"Mobil"
10001;"Müller und Söhne GmbH";"";"";"DE";"0711 4561230";""
10002;"";"Schäfer";"Jürgen";"AT";"01 5551234";"0664 1234567"

Result with the suggestion: 0711 4561230 → “Müller und Söhne GmbH”, +43 664 1234567 → “Jürgen Schäfer”. Quoted fields may contain delimiters, doubled quotes and line breaks. If the export is written to the same place regularly, CallerHub picks up the changes automatically.

Column names and layout of a DATEV export depend on the program, version and export settings. The example is reconstructed and has not been tested with a real DATEV export; check the preview in the dialog. CallerHub only reads the exported file and does not access DATEV itself.

REST API (HubSpot, Salesforce, Pipedrive, SuiteCRM, SugarCRM, Zoho, Odoo, SAP, Dynamics 365, custom API)

The REST templates (HubSpot, Salesforce, SuiteCRM, SugarCRM, Zoho CRM, Odoo, SAP S/4HANA, Microsoft Dynamics 365, Business Central online, Finance & Supply Chain, Infor ION API, bexio, HERO, Clio, Jobber) are examples and have not been tested with real accounts; ServiceTitan has no template because its contacts interface returns no names; the sign-in flows have been tested with a test server. Compare field names and API versions with the provider's documentation. There is no template for Oracle NetSuite yet because its sign-in requires a JWT certificate.

LDAP / Active Directory

Microsoft 365 (Graph)

Exchange (EWS)

Microsoft has announced that EWS will be switched off in Exchange Online; for Microsoft 365, use the “Microsoft 365 (Graph)” source instead. Check the current status with Microsoft.

Number list and direct query

Number list (recommended): loads all phone numbers at startup and at the interval; every call is answered from memory. If a refresh fails, the previous list stays active.

Direct query on every call: parameters (written the same way in all databases; CallerHub translates them into @name or ?):

Phone numbers are normalised: spaces, hyphens, slashes, parentheses and “(0)” are removed; + and 00 mark international phone numbers. The SQL field highlights keywords, strings, numbers, comments and parameters in colour; Draft with AI prepares a question for the chat.

Creating the read-only user CALLERHUB (Oracle, SQL Server)

SQL assistant: step 2 of a database source has the button SQL assistant …. It reads the database catalogue (read-only, changes nothing), suggests tables with phone number and name columns (pre-selected: the most likely ones, with the number of entries), builds the query for the phone number list (also excluding deleted or inactive records where a matching column exists) and shows a preview of the first rows. After Apply it shows a script for a read-only user limited to the selected tables (SQL Server, Oracle, MySQL/MariaDB, PostgreSQL) to hand to the database administrator. Many CRM and ERP systems keep phone numbers in a separate communication table (one row per phone number, fax number or email address). The assistant recognises such tables and proposes a joined query: it links the table via its key columns – also via intermediate tables – to the tables with company and person names (LEFT JOIN where a person is optional) and adds a comment if a column distinguishes phone, fax and email, so that you can filter by it.

CallerHub only needs read permissions on the tables or views that the SQL query reads. Do not use an administrative account (e.g. SYSTEM or sa): a dedicated account limits the permissions, and a lockout does not affect database administration. CallerHub therefore suggests the user CALLERHUB.

All names below are examples: schema or database CRM, tables KONTAKTE and FIRMEN, container ORCLPDB1. Replace them with the names of your system and have the database administrator review and run the statements.

Oracle

Connect as DBA to the service of the database that contains the schema. In a container database (CDB) this is the pluggable database, not the root (CDB$ROOT).

-- container database only: switch to the correct PDB
ALTER SESSION SET CONTAINER = ORCLPDB1;

CREATE USER CALLERHUB IDENTIFIED BY "Secure#Password1";
GRANT CREATE SESSION TO CALLERHUB;

-- read only (READ from Oracle 12c; older versions: SELECT)
GRANT READ ON CRM.KONTAKTE TO CALLERHUB;
GRANT READ ON CRM.FIRMEN   TO CALLERHUB;

Optionally, create a dedicated profile so that the password does not expire after the default period (otherwise ORA-28001). The administrator decides whether this fits your security rules:

CREATE PROFILE CALLERHUB_PROFILE LIMIT
  PASSWORD_LIFE_TIME    UNLIMITED
  FAILED_LOGIN_ATTEMPTS 10
  PASSWORD_LOCK_TIME    1/24;   -- locked for 1 hour after 10 failed attempts
ALTER USER CALLERHUB PROFILE CALLERHUB_PROFILE;

Check (connected as CALLERHUB): SELECT COUNT(*) FROM CRM.KONTAKTE;

Microsoft SQL Server

SQL logins require mixed mode (server properties → Security → “SQL Server and Windows Authentication mode”). Alternatively use Windows authentication with the service account of CallerHub (see below).

USE master;
CREATE LOGIN CALLERHUB WITH PASSWORD = N'Secure#Password1',
       CHECK_POLICY = ON, CHECK_EXPIRATION = OFF;

USE CRM;
CREATE USER CALLERHUB FOR LOGIN CALLERHUB;

-- read only the tables needed ...
GRANT SELECT ON dbo.KONTAKTE TO CALLERHUB;
GRANT SELECT ON dbo.FIRMEN   TO CALLERHUB;
-- ... or read all tables of the database
-- ALTER ROLE db_datareader ADD MEMBER CALLERHUB;

Check: EXECUTE AS LOGIN = 'CALLERHUB'; SELECT TOP 1 * FROM dbo.KONTAKTE; REVERT;

Windows authentication instead of a password: CREATE LOGIN [COMPANY\svc-callerhub] FROM WINDOWS;, then CREATE USER and GRANT as above with this name; run CallerHub as a service under this account and select Windows authentication in the Database card.

Account lockout protection

If the database rejects the login (Oracle ORA-01017/ORA-28000, SQL Server 18456, MySQL/MariaDB 1045, PostgreSQL 28P01), CallerHub makes no further automatic login attempts – neither when refreshing the phone number list nor for direct queries per call. The Data source bar then shows “Paused” with the reason, as do system health and notifications. The pause ends as soon as the credentials are changed and saved or Test connection succeeds.

Finding the query for your own database (Oracle, SQL Server)

The quickest way is the SQL assistant … in step 2 (see above). The following steps describe the manual way, e.g. if the assistant finds no suitable table.

If there is no ready-made template for your CRM or ERP, determine tables and columns yourself in four steps. All queries are read-only. Ideally run them as the read-only user CALLERHUB in SQL Developer or sqlplus (Oracle) or SQL Server Management Studio. The names CRM, CUSTOMERS and CONTACTS and all column names are examples.

1. Find columns with phone number, name and country

Oracle:

SELECT owner, table_name, column_name, data_type
  FROM all_tab_columns
 WHERE owner NOT IN ('SYS', 'SYSTEM', 'XDB', 'MDSYS', 'CTXSYS', 'ORDSYS', 'OLAPSYS', 'WMSYS')
   AND REGEXP_LIKE(column_name, 'TEL|PHON|FON|MOBIL|HANDY|NAME|FIRMA|COMPANY|LAND|COUNTRY|LKZ', 'i')
 ORDER BY owner, table_name, column_id;

Microsoft SQL Server (run in the right database, e.g. after USE CRM;):

SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
  FROM INFORMATION_SCHEMA.COLUMNS
 WHERE COLUMN_NAME LIKE '%tel%'   OR COLUMN_NAME LIKE '%phon%' OR COLUMN_NAME LIKE '%fon%'
    OR COLUMN_NAME LIKE '%mobil%' OR COLUMN_NAME LIKE '%handy%'
    OR COLUMN_NAME LIKE '%name%'  OR COLUMN_NAME LIKE '%firma%' OR COLUMN_NAME LIKE '%company%'
    OR COLUMN_NAME LIKE '%land%'  OR COLUMN_NAME LIKE '%country%'
 ORDER BY TABLE_SCHEMA, TABLE_NAME, ORDINAL_POSITION;

Candidates are tables with several hits, e.g. CUSTOMERS with PHONE, MOBILE, COMPANY_NAME and COUNTRY. In Oracle, SELECT table_name, num_rows FROM all_tables WHERE owner = 'CRM' ORDER BY num_rows DESC NULLS LAST; shows the largest tables.

2. Search for a known phone number

If the column names do not help, search for a known phone number, e.g. your own switchboard. Use only the last digits (4567890), because the notation varies. The following query generates one check query per text column. Copy the output, remove the last UNION ALL and run it; the result names table and column with hits.

Oracle:

SELECT 'SELECT ''' || owner || '.' || table_name || '.' || column_name || ''' AS location, COUNT(*) AS hits FROM '
       || owner || '.' || table_name || ' WHERE ' || column_name || ' LIKE ''%4567890%'' HAVING COUNT(*) > 0 UNION ALL'
  FROM all_tab_columns
 WHERE owner = 'CRM' AND data_type IN ('VARCHAR2', 'NVARCHAR2', 'CHAR', 'NCHAR');

Microsoft SQL Server:

SELECT 'SELECT ''' + TABLE_SCHEMA + '.' + TABLE_NAME + '.' + COLUMN_NAME + ''' AS location, COUNT(*) AS hits FROM ['
       + TABLE_SCHEMA + '].[' + TABLE_NAME + '] WHERE [' + COLUMN_NAME + '] LIKE ''%4567890%'' HAVING COUNT(*) > 0 UNION ALL'
  FROM INFORMATION_SCHEMA.COLUMNS
 WHERE TABLE_SCHEMA = 'dbo' AND DATA_TYPE IN ('varchar', 'nvarchar', 'char', 'nchar');

For large databases, limit the search to one schema or a few tables, otherwise it takes a long time.

3. Look at the content

-- Oracle (12c and later; older versions: WHERE ROWNUM <= 20)
SELECT customer_no, company_name, company_name2, phone, mobile, country FROM crm.customers FETCH FIRST 20 ROWS ONLY;
-- SQL Server
SELECT TOP 20 customer_no, company_name, company_name2, phone, mobile, country FROM dbo.customers;

Check: which column contains the name that should appear on the phone? Are contacts stored in a separate table? Are the phone numbers in a separate communication table (the SQL assistant … proposes a joined query for this)? Does country contain an ISO code (DE), a name or a dialling code? The notation of the phone numbers does not matter; CallerHub normalises them.

4. Derive the query for the phone number list

CallerHub expects the columns nummer (phone number) and anzeigename (display name), optionally rang (rank), land (country), id and link (see phone number list). These aliases are fixed names, also shown above the SQL field; only the table and column names after SELECT and FROM depend on your database. CallerHub also accepts the English aliases displayname, country and rank. Each column with phone numbers becomes one part; UNION ALL joins the parts.

Oracle:

SELECT c.phone AS nummer, c.company_name AS anzeigename, 0 AS rang, c.country AS land, c.customer_no AS id
  FROM crm.customers c WHERE c.phone IS NOT NULL
UNION ALL
SELECT c.mobile, c.company_name, 0, c.country, c.customer_no
  FROM crm.customers c WHERE c.mobile IS NOT NULL
UNION ALL
SELECT p.phone, c.company_name || ' - ' || p.first_name || ' ' || p.last_name, 1, c.country, c.customer_no
  FROM crm.contacts p JOIN crm.customers c ON c.customer_no = p.customer_no
 WHERE p.phone IS NOT NULL

Microsoft SQL Server:

SELECT c.phone AS nummer, c.company_name AS anzeigename, 0 AS rang, c.country AS land, c.customer_no AS id
  FROM dbo.customers c WHERE c.phone <> ''
UNION ALL
SELECT c.mobile, c.company_name, 0, c.country, c.customer_no
  FROM dbo.customers c WHERE c.mobile <> ''
UNION ALL
SELECT p.phone, CONCAT(c.company_name, ' - ', p.first_name, ' ', p.last_name), 1, c.country, c.customer_no
  FROM dbo.contacts p JOIN dbo.customers c ON c.customer_no = p.customer_no
 WHERE p.phone <> ''

• rang 0 for companies, 1 for contacts: if the same phone number appears for both (e.g. the switchboard), the company wins.
• Enter the query under Data sources → Step 2: Phone number list. Test connection loads the whole list and reports the count; then Save and apply.
• Grant the read-only user read access to the tables used (see read-only user).

Direct query (only if needed)

For very large tables, CallerHub can query the database with parameters on each call (see direct query). Because the database contains phone numbers in any notation, compare digits only:

-- Oracle
SELECT company_name AS anzeigename FROM crm.customers
 WHERE REGEXP_REPLACE(phone, '[^0-9]', '') IN (:num_national, :num_digits, '00' || :num_digits)
-- SQL Server
SELECT TOP 1 company_name AS anzeigename FROM dbo.customers
 WHERE REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(phone, ' ', ''), '-', ''), '/', ''), '(', ''), ')', ''), '+', '')
       IN (:num_national, :num_digits, '00' + :num_digits)

A function on the column prevents the use of the index; the query becomes slow on large tables. A view or column with an already normalised phone number is better – or the phone number list.

Templates for CRM and ERP systems

Template (Number list card) inserts SQL or a definition for the selected source. When the source is changed, an unmodified template is replaced automatically; your own SQL is kept.

Apart from Infor COM, no template has been tested with a real installation of the respective system. Table, column and field names are based on published data models and may differ depending on the version and customisation. Verify them with Test connection and a test lookup before use.

Multiple data sources

• In the fixed bar of the Data sources page, use Add data source to create up to 10 sources (the counter shows e.g. “2 of 10”; more with a special licence, see callerhub.de), e.g. “CRM” (SQL Server) and “Phone book” (Active Directory). Each source has its own connection, query and query mode.
• The sources are queried in the order shown; the first source with a match supplies the name. The up and down buttons in the header of the open card change the order; alternatively, drag a card by its header to another position. Then Save and apply.
• Which sources a phone system queries is set by its interface: Interfaces → Phone system → Queried data sources (default: all, including sources added later).
• If one source fails, the others continue to deliver. If no source finds the phone number and one source is failing, CallerHub responds with 503 so that the outage is not cached as “unknown”. The status indicator shows “Data error” with the name of the source.
• The Source column in log and status shows where the name came from, e.g. Liste/CRM; with a plugin e.g. Liste/CRM/Plugin.

Countries and country codes

National phone numbers (e.g. 044 123 45 67) need a country code. If the list supplies a column land (or country) or the CSV file a third column, the country code applies per row. The country code under Administration → Advanced (example 49) applies only when the country is missing or unknown.

• Phone numbers with + or 00 are already international.
• The trunk prefix is taken into account per country: usually 0; none, for example, in Italy (the leading 0 remains part of the phone number), Spain, Portugal, Greece, Denmark, Norway, Luxembourg, Poland and the Czech Republic; 1 in North America, 06 in Hungary, 8 in Russia and Kazakhstan.
• The log reports unknown country values as a warning with examples and count.

The rules cover common countries; check special cases (e.g. changes to numbering plans) with a test lookup.

Cache

The phone numbers are held only in the memory of the running program – not in a database and not in a file. After exiting or stopping they are gone and are loaded again on the next start.

Reload reloads the lists immediately; Clear cache additionally discards the results of the direct query. While loading, the previous list stays active.

Interfaces and phone systems

On the Interfaces page, each phone system (or each phone with directory lookup) is connected as its own interface, each shown as a card of its own. At most 10 interfaces are possible – the counter at the top shows e.g. “1 of 10”; the Basic edition allows one, and more are possible with a special licence (callerhub.de). Like data sources, interface cards can be dragged by their header to change the order. All interfaces share port and HTTPS (Administration › Server; the line at the top of the page shows the address and links there); CallerHub recognises the requesting system by its API key. Each interface has its own allowed IP addresses and its own selection of queried data sources. A new installation starts without an interface: the card Add first interface opens the choice of phone system. Until then CallerHub answers requests with 503 “No interface set up”.

Show instructions (link on the right of the card) opens the setup instructions for the selected phone system. All instructions follow the same steps: 1. Address (the URL CallerHub answers on), 2. Enter in the phone system (where the address goes), 3. Response (what the phone system receives), 4. Test (in the browser, then with a call) and, where available, Optional: call analysis (how call records reach CallerHub).

Only the STARFACE connection has been proven in operation. The instructions for 3CX, Asterisk/FreePBX, VitalPBX, Issabel, Yealink/Fanvil and Snom are based on published interfaces; check placeholders, menu paths and setting names against the documentation of your version.

Setting up phone systems

Before you start

• At least one data source is ready (state “Ready” on the start page) and a test lookup with a known number returns the expected name.
• Network: the phone system (or the phones) can reach the CallerHub computer on the port (default 8080, HTTPS e.g. 8443). The Windows firewall allows the port; Administration → System health offers a button for the firewall rule.
• Known addresses: the IP address of the phone system or the network of the phones, for Allowed IP addresses.
• Admin access to the web interface of the phone system or the provisioning of the phones.
• CallerHub runs in one place only – either as a service or in the program window (see Windows service).

How the query works

For each incoming call the phone system calls an address of CallerHub and receives the name. Parameters of /lookup:

Responses: 200 with the name (empty if unknown), 401 wrong or missing API key, 403 IP address not allowed for this interface, 429 temporarily locked after too many wrong keys, 503 no data source ready. /health returns OK without a key (availability check).

Procedure

The same procedure applies to every system. The examples use 192.168.10.5 as the CallerHub server, port 8080 and the placeholder API-KEY; Copy instructions provides the complete address with the real key.

1. Interfaces → Add (for a new installation Add first interface), choose the phone system, enter a label.
2. Allowed IP addresses: enter the IP address of the system or the phones (e.g. 192.168.10.20 or 192.168.20.0/24 for a phone network).
3. Check Queried data sources, then Save and apply.
4. Test in the browser of a computer in the same network: http://192.168.10.5:8080/lookup?apikey=API-KEY&number=030 1234560 returns the name (empty if unknown). 401 = wrong key, 403 = IP address not allowed.
5. Set up the system as described below and make a test call. The bar then shows “Request hh:mm”; the start page lists the access under Recent requests.

STARFACE

STARFACE has no built-in name lookup via a web address; it queries CallerHub through a module. For an incoming call the module calls the CallerHub address and shows the response (text) as the caller name.

1. Address and API key: http://192.168.10.5:8080/lookup?number=<number>, API key as header X-Api-Key or parameter apikey. Test in the browser: http://192.168.10.5:8080/lookup?number=07114567890&apikey=API-KEY.
2. Create a module: in the STARFACE web interface Admin → Modules → Module library; in the Module Designer create a function for incoming calls with the components CreateHttpUrlWithParams, HttpRequest (GET), ReadFromStream (UTF-8) and SetCallerId (name = response). Screenshots of these components are in the STARFACE wiki (German): Using web services from the module system.
3. Or import a ready-made module: Admin → Modules → Module library → Import module, choose the .sfm file, create a module configuration with address and API key and activate it. Screenshots: Import of new modules.
4. Make a test call from a number stored in the CRM. The access appears in CallerHub under Recent requests.

The sample module Samples\CRM-Lookup_v3.sfm is included as a template; its structure and limitations are described in STARFACE sample module. CallerHub also shows these instructions with the real API key under Interfaces → Phone system → Instructions.

3CX

1. In the Phone system card, choose “3CX (CRM template)”, click Save and apply, then save 3CX template …. The file contains address and API key.
2. In the 3CX management console, upload the template under Integrations → CRM (menu path depends on the version) and select CallerHub as CRM.
3. Switch on the phone number search. 3CX queries with format=json and receives name, phone and – if stored – the url of the record.

Asterisk / FreePBX

1. Prerequisite: the func_curl module is loaded (asterisk -rx "module show like curl").
2. In the incoming context (FreePBX: /etc/asterisk/extensions_custom.conf, context from-pstn-custom or similar), set the name before dialling:

exten => _X.,1,Set(CURLOPT(httptimeout)=2)
 same => n,Set(CALLERID(name)=${CURL(http://192.168.10.5:8080/lookup?apikey=API-KEY&called=${EXTEN}&number=${URIENCODE(${CALLERID(num)})})})
 same => n,Goto(from-pstn,${EXTEN},1)

• Reload the dial plan: asterisk -rx "dialplan reload". If CallerHub cannot be reached, the name stays empty after 2 seconds.
• With HTTPS, Asterisk must trust the certificate (store the root certificate on the Asterisk server).

Yealink / Fanvil (remote phone book)

1. Web interface of the phone: Directory → Remote phone book, address http://192.168.10.5:8080/lookup?format=yealink&apikey=API-KEY&number=#SEARCH, name CallerHub.
2. Under Features or Directory, switch on the name lookup for incoming calls in the remote phone book (name depends on the firmware).
3. For many phones via provisioning:

remote_phonebook.data.1.url = http://192.168.10.5:8080/lookup?format=yealink&apikey=API-KEY&number=#SEARCH
remote_phonebook.data.1.name = CallerHub
features.remote_phonebook.enable = 1

Allowed IP addresses: the network of the phones, e.g. 192.168.20.0/24.

Snom

1. Web interface or provisioning: address of the XML phone book http://192.168.10.5:8080/lookup?format=snom&apikey=API-KEY&number=#SEARCH.
2. Switch on the lookup for incoming calls in the XML phone book; check setting names and placeholders against the Snom documentation of your firmware.

Other systems (generic)

Any system that can call an address via HTTP GET for each call can be connected. format= selects the response: text (name only), json or xml. Optionally, &called= (called number) and &user= (user) add details to the statistics. Example test with curl:

curl -H "X-Api-Key: API-KEY" "http://192.168.10.5:8080/lookup?format=json&number=%2B49301234560"

Systems without an HTTP lookup

Unify OpenScape Business, Auerswald, Avaya IP Office, Gigaset and many desk phones resolve names via LDAP; cloud phone systems (Teams, Zoom, NFON, Placetel …) and the FRITZ!Box use their own contact lists. For these, use the module Phone book (LDAP phone book or export).

Typical errors when connecting

If the cause remains unclear: ☰ → Error analysis → Start extended recording …, make a test call and check the recording, or send it in a diagnostic package. The recording contains every request with all headers and parameters (keys masked).

Phone book: LDAP, export and FRITZ!Box (module)

Many phone systems and desk phones do not call a web address but query an LDAP directory – for example Unify OpenScape Business, Auerswald COMtrexx/COMpact (as LDAP proxy for their phones), Avaya J100 on IP Office, Yeastar P-Series, innovaphone (reverse lookup), Ascom IP-DECT, Grandstream UCM and pascom, and phones by Yealink, Snom, Gigaset, Fanvil and Grandstream. Cloud phone systems (Microsoft Teams, Zoom, RingCentral, Webex, NFON, Placetel) and the FRITZ!Box only show names from their own contact lists. The module Phone book (LDAP and export) covers both. Enable it under Administration → Modules; the card Phone book appears on the Interfaces page.

LDAP phone book

• Read only (LDAPv3): bind, search, unbind. Write attempts are rejected.
• Reverse lookup: when the phone searches for a number (e.g. (telephoneNumber=07111234567)), CallerHub queries all active data sources – including direct queries – with rules, block list and VIP list. The number may be national, with +49 or 0049.
• Name search (phone book on the phone, e.g. (|(cn=Mül*)(sn=Mül*))) and searches with wildcards use the phone number lists in memory; direct-query sources cannot be searched by name.
• Entries: uid (international number), cn/sn/displayName (display name), telephoneNumber (national and E.164), labeledURI (link to the record), objectClass inetOrgPerson. At most 200 entries per search.
• Queries appear in the log and statistics with the interface LDAP.

The card shows the values to enter for each device. In general:

Server:            name or IP address of the CallerHub computer, port 389 (636 with LDAPS)
Base DN:           ou=callerhub
Name filter:       (|(cn=%)(sn=%))
Number filter:     (|(telephoneNumber=%)(mobile=%))
Display attribute: cn          Number attribute: telephoneNumber
Lookup for incoming calls: on

Field names and the placeholder (%, %s or *) differ by vendor and firmware; refer to the device manual. Yealink: web interface Directory → LDAP. On phone systems (Unify, Auerswald, Avaya), CallerHub is entered as the external LDAP directory of the phone system, which passes the names on to its phones.

Mitel 100 family (Mitel 112, 130, 150; formerly Aastra OpenCom 100)

These systems do not query a web address, but they can include an external LDAP directory per company. Settings in the web console of the system (release 12.1, not yet tested with CallerHub):

1. Telephony → Extended → Companies → (your company) → LDAP server: status on, server = name or IP address of the CallerHub computer, port 389, user name and password as on the CallerHub card, BaseDN ou=callerhub.
2. Duplicate phone book entry: Use LDAP + central keeps the entries of the central phone book. Number: start with transparent; if no name appears, try convert. Clear cache: e.g. 60 minutes.
3. User manager → User groups: tick Phone book: use LDAP for the groups concerned.
4. In CallerHub, enter the IP address of the system under Allowed IP addresses and create the firewall rule (system health).

Whether the system shows the LDAP name for incoming calls or only in the phone book search depends on the release; check with a test call.

Export the phone book

The buttons on the card save the entries of the phone number lists (after rules, without blocked numbers) to a file. Requirement: the interface is running.

Phones with a remote phone book can also load the list directly (module Browser access, access key from Administration → Browser access):

http://192.168.10.5:8080/phonebook?format=yealink&key=ACCESS-KEY
(format: yealink, fritzbox, vcard, csv)

FRITZ!Box

• Names for incoming calls: the FRITZ!Box does not query an external address. Export the phone book as FRITZ!Box XML and import it (see above); export again after changes in the CRM.
• Call analysis: under Administration → Module: Call analysis, enter the address of the FRITZ!Box (e.g. fritz.box). CallerHub reads the call monitor (port 1012) and writes every finished call to CallData\FRITZ!Box\fritzbox-YYYY-MM.csv. Enable the call monitor once by dialling #96*5* on a connected phone (#96*4* disables it). If the connection drops, CallerHub reconnects every 30 seconds.

STARFACE sample module

The sample “CRM-Lookup” shows what a module for CallerHub can look like in the STARFACE Module Designer. It complements the general instructions under Setting up phone systems.

Limitations of the sample Samples\CRM-Lookup_v3.sfm:

• intended as a reference template only, not tested on any STARFACE and not reviewed by STARFACE;
• component names from a STARFACE export (version 10); menu and field names may differ depending on the version;
• after the import, STARFACE shows a licence notice;
• incoming calls only; anonymous calls are not looked up.

1. Prerequisites

• CallerHub is running and can be reached from the STARFACE (see Firewall).
• The address (e.g. https://lookup.company.com:8443/lookup) and the API key are available (Interfaces → Phone system).
• Test in the browser: https://lookup.company.com:8443/lookup?number=07114567890&apikey=API-KEY returns a name.

2. Create the module

1. Open the Module Designer and create a new module. Name: CRM-Lookup, manufacturer: e.g. your company name.
2. Create the tab Einstellungen with the text field GUI_LOOKUP_URL (STRING) and the password field GUI_API_KEY (STRING).
3. Create the function lookupCaller.

3. Blocks in lookupCaller

Instead of the parameter apikey, the key can be sent as the header X-Api-Key (a second map as httpHeaders in HttpRequest). Headers do not appear in proxy or firewall logs.

4. Entry point, instance, test

1. Create an entry point for incoming calls with the target lookupCaller; save the module.
2. Create an instance, enter the URL and API key, and temporarily select INFO under “Log file”.
3. Call from a phone number that is maintained in the CRM. The request appears in CallerHub with the sender IP, called phone number and result. If no request arrives, check the address, firewall and allowed IP addresses. If a request arrives but no name appears, check the module log and the condition in step 12.

Interface (HTTP)

GET /lookup?number=+4930123456                  Header X-Api-Key: <key>  (or parameter apikey)
  → 200, text: "Musterfirma AG - Frau Beispiel"   (empty if unknown)
GET /lookup?number=…&called=201&user=zentrale    optional details for the statistics
GET /lookup?number=…&format=json               → {"found":true,"name":"…","phone":"+4930123456","url":"…","source":"CRM"}
GET /lookup?number=…&format=xml                → <lookup found="true"><name>…</name><phone>…</phone></lookup>
GET /lookup?number=…&format=yealink|snom       → XML phone book
GET /health                                      → OK (availability check, not counted in the statistics)
GET /stats, /stats/data                          Statistics in the browser (Browser access module)
GET /open?number=…&key=…                        Redirect to the CRM record
GET /metrics, /status                            Monitoring (Prometheus text or JSON)

Each interface has its own API key; CallerHub answers the request with the data sources of this interface. Error codes: 401 wrong key, 403 IP not allowed (in general or for this interface), 404 unknown path or module switched off, 405 wrong method, 503 number list not ready, data source error or no data source set up.

Console commands

Return values: 0 = success, 1 = runtime error, 2 = usage or configuration error.

Display name, block list and VIP list

Module “Display name, block list and VIP list”. The rules exist twice and complement each other:

• Global (Administration → Module: Display name, block list and VIP list): applies to all data sources and interfaces.
• Per data source (advanced mode, Data sources → Display name, block list and VIP list): applies only to the selected source.

Order for each call

1. Global block list: if the number is in it, the search ends.
2. The data sources of the interface one after the other: first the block list of the source, then the query; the first source with a match supplies the name.
3. Replacements of the matching source, then the global replacements.
4. VIP list of the matching source, otherwise the global VIP list.
5. Finally the plugins.

Statistics

• Period: today, yesterday, last 7/30 days, this/last month, this year or custom. Up to 2 days by hour, up to 92 days by day, beyond that by month.
• Break down by: all requests, called phone number, user, IP address, data source (hit rate per source), interface (per phone system) or caller (top callers, phone number masked, name only if the option is enabled).
• Weekday × hour: heat map of the requests; shows peak times.
• Export saves the chart and table as a CSV file.
• In the browser (bar above the evaluation): if browser access is set up, Open in browser opens the /stats page. Otherwise Provide in browser … sets it up (switches on the module, generates an access key, opens the card Administration → Module: Browser access); then check the allowed IP addresses and click Save and apply.

Stored per request: time, IP address, status, hit, duration, source, interface, called phone number, user, masked phone number and a non-reversible hash (for top callers). The full phone number is not stored.

Call analysis (module)

The Call analysis module evaluates all calls from the call records (CDR) of the phone system – including calls for which CallerHub was not asked. After enabling it under Administration → Modules, the Call analysis tab and the card Administration → Module: Call analysis appear.

To keep the program menu short, select Administration → Module: Call analysis → Do not show in the menu. The call analysis is then only available in the browser at /calls.

The evaluations follow common call accounting and contact centre reports (e.g. ProCall Analytics): reachability, waiting times, service level, callback rate and the distribution over weekdays and hours.

Providing call records

The phone system puts its call records as a CSV file into the CallData folder in the program folder (another folder can be set under Module: Call analysis). One subfolder per system (e.g. CallData\Head office) assigns the calls to an interface. CallerHub reads the folder every time the page is shown and with Refresh; the files are not changed.

• Asterisk / FreePBX: copy the file /var/log/asterisk/cdr-csv/Master.csv regularly into the folder (e.g. via a share or scheduled task). The layout is detected automatically.
• STARFACE: in the web interface Admin → Evaluation → Export call data (per user or group, period selectable); put the file output.csv into the folder. CallerHub recognises the layout (columns callid, starttime, linktime, incoming, answered, duration, login …) and merges the call steps of one call (e.g. group, then user). Waiting time: start until answered; extension: the user who answered. According to the STARFACE wiki the export is manual.
• 3CX and others: export the call list or call report as CSV (menu path depends on the version). Columns with names such as Start, Direction, From, To, Extension, Answered/Status, Wait, Duration (seconds or hh:mm:ss) are recognised.
• FRITZ!Box: live via the call monitor, see FRITZ!Box.
• Without a Direction column, CallerHub decides by the length of the number: extensions have at most as many digits as set under Extensions up to (digits) (default 4).

Start;Direction;From;To;Extension;Answered;Wait;Duration
2026-10-16 09:12:05;incoming;+49711456789;200;201;yes;8;00:03:41
2026-10-16 09:15:40;incoming;+4930123456;200;;no;35;0

Live reception (without a file)

Many phone systems report every call when it ends. CallerHub then writes the calls itself into the folder (one subfolder per interface or receiver, one file per month, same columns as above), so the call analysis needs no export:

Receivers are set up in the card Administration → Module: Call analysis under Live reception (up to 5): Add receiver … first asks for the phone system; port and direction are pre-filled. When CallerHub waits, enter the IP address of the phone system as allowed sender (required; other senders are rejected). Check record reads a pasted sample line and shows how CallerHub stores it – useful before the phone system is connected. The state of every receiver (waiting, connected, number of calls, errors) is shown below the list and in the system health.

Call records via API (3CX V20, Microsoft Teams, Webex Calling)

Cloud phone systems keep the call records themselves. With a receiver of the type CallerHub polls the data via API, CallerHub fetches new calls at the set interval (field Interval (min), default 15 or 30) and writes them into the call analysis. The time of the last fetch is remembered, so nothing is lost or counted twice after a restart; the first fetch takes the last 24 hours. Check record in the receiver dialog runs a trial fetch without remembering anything.

The interval should not be shorter than needed: cloud services limit the number of requests. Tokens of integrations expire; a failed fetch is shown in the card, in the system health and in the monitoring (call_data_receivers_error). The client secret is stored encrypted.

Reporting calls to /event

…/event?apikey=API-KEY&event=incoming&callid=4711&number=07111234567&called=0711999200
…/event?apikey=API-KEY&event=answered&callid=4711&extension=201
…/event?apikey=API-KEY&event=ended&callid=4711&duration=95

Events with the same callid (also callId, call_id) form one call: waiting time from begin until answered, duration from duration or the time until ended. Without a call ID, number and extension link the events. A single ended or missed event with duration and answered=1|0 is also enough. Form data and JSON objects are accepted with POST.

Call records via HTTP (/cdr)

POST /cdr?apikey=API-KEY&format=3cx (or mitel, openscape, callerhub) accepts one or more lines; innovaphone XML is detected automatically (also as parameter msg). The calls are assigned to the interface of the API key.

The call records contain full phone numbers. They remain in the specified folder; CallerHub does not store a copy. Document the retention period in the record of processing activities.

Test data

For trying things out, both analyses can show fictitious data as long as no real data exists:

• Administration → Module: Statistics → Show test data as long as there are no real requests
• Administration → Module: Call analysis → Show test data as long as there are no call records

Test data is marked (“Test data” in amber) and is not stored. As soon as the first real request or the first file with call records exists, CallerHub shows real data only.

Browser access

Module “Browser access”, card Administration → Module: Browser access. All functions use a separate access key (separate from the API key) and optionally their own IP allowlist.

Statistics in the browser (/stats)

Same analysis as in the program, also on a smartphone. Address: http://callerhub:8080/stats; enter the access key, “Remember on this device” is optional. The page does not load any external content.

Call analysis in the browser (/calls)

With the modules Browser access and Call analysis, http://callerhub:8080/calls shows the call analysis with the same access key: period, direction, breakdown, key figures, trend and table. Test data appears there as well as long as no call records exist. The statistics page links to the call analysis and vice versa.

CRM link (/open)

For CTI pop-ups: http://callerhub:8080/open?number=07114567890&key=ACCESS-KEY redirects to the record (link per source, see Data sources).

Monitoring (/metrics, /status, /check, /prtg) is a module of its own since version 3.0: see Monitoring. Settings from earlier versions are taken over automatically.

Over HTTP, the key is transmitted unencrypted. Offer browser access only in the internal network or via HTTPS.

Monitoring (Nagios, Icinga, Checkmk, PRTG, Zabbix, Prometheus, Grafana)

Module Monitoring (Full edition), card Administration → Module: Monitoring. Monitoring systems query CallerHub over HTTP(S) on the port of the interface. You choose which metrics are delivered; every address needs the monitoring key (parameter key, header X-Monitoring-Key or Authorization: Bearer …) and, optionally, comes only from the allowed IP addresses.

curl "http://callerhub:8080/check?key=KEY"
CALLERHUB OK - 2/2 data sources ready, 1146 requests | sources_ready=2;;;0;2 answered=1146c unknown=212c rejected=0c errors=0c avg_ms=4ms;500;2000

Selectable metrics

Over HTTP, the key is transmitted unencrypted. Use HTTPS or the internal network, and enter the address of the monitoring server under Allowed IP addresses. The Windows Firewall rule must allow this address as well; the system health shows a mismatch and offers Adjust rule (see System health checks).

Notifications

Module “Notifications”, card Administration → Module: Notifications. Reports faults and their resolution – without phone numbers. The card has three sections; fault reports and scheduled reports work independently of each other.

Channel per event: for each of the two events (data source errors, no requests) the check boxes Email and Webhook next to the field choose how it is reported – one channel, both or none. A check box is available only when the channel itself is switched on and complete. The module shows “active” only when at least one channel is complete and the interface is running.

The network discovery also finds mail servers (ports 587, 465, 25); Use enters server, port and encryption here. When saving, all missing fields of the email settings are marked together. Send test message checks the values in the form without saving. Which webhook address Teams or Slack expects (e.g. Workflows or Incoming Webhooks) depends on the respective service; refer to its documentation.

Scheduled reports

Card Administration → Module: Notifications, list Scheduled reports (Full edition). Each line is one report; Add report … creates one, the pencil in the line edits it, the bin removes it. Up to 20 reports, each with:

By email, the report arrives as a PDF with the key figures in the text; Teams and Slack receive the key figures as a message; JSON receives the key figures and the PDF as Base64 (pdfBase64). Every PDF has the logo at the top right, page numbers and the footer “(c) Simon Bernhard - CallerHub.de” (with Rebranding your own). Send now (previous period) in the report dialog sends the report immediately to check the settings. Reports are sent while the interface is running; sent periods are remembered in Statistics\report-last.txt, so nothing is sent twice after a restart. The printout of the data flow has the same logo and footer.

For languages with non-Latin script (e.g. Russian, Chinese, Arabic, Hindi) the PDF is written in English.

Call events

Module Forward call events (Full edition), card Administration → Module: Forward call events. CallerHub passes calls on to other systems – a CRM that logs calls (e.g. Infor CRM), a ticket system, a time recording tool or your own script. Each action defines which events it handles and where they go; up to 10 actions.

Events

The letters I, O, R and C are the same as in ProCall, so existing CRM commands keep working.

Reporting events to /event

The phone system (or any other system) reports an event with the API key of an interface; the allowed IP addresses of that interface apply:

http://192.168.10.5:8080/event?apikey=API-KEY&event=outgoing&number=07111234567&extension=201

Parameters: event (or type, direction: also the letters I, O, R, C, A, E), number (other party), called (own number), extension, user, name (optional). GET and POST with form data (application/x-www-form-urlencoded) are accepted; the response is 200 OK. Events do not count as queries in the statistics.

Actions

Add action … opens the action: first choose the type, then optionally a typical template of that type (e.g. Infor CRM); Edit and test … opens the action with all fields and a Send test button that runs it immediately with sample values and shows exactly what was sent.

Placeholders: {event}, {direction}, {number}, {numberE164} (+497111234567), {numberNational} (07111234567), {numberDigits}, {extension} (extension, otherwise own number), {called}, {user}, {name}, {id}, {link} (found record; CallerHub looks the number up only when an action uses these), {interface}, {time}, {date}, {clock}. Values are cleaned before they are inserted: numbers keep only digits and +, texts lose quotation marks, separators and control characters; in addresses values are URL-encoded, in JSON escaped.

Example: Infor CRM

Template Infor CRM – directly to the server: server crm-server (replace with the name or address of the CRM server), port 4921, format User|password|text, events incoming, outgoing, missed and forwarded, text:

CTIPG0C1RegisterCall "application=CTIPTEST" "callNumber={numberE164}" "targetNumber={extension}" "direction={direction}"

Test with the application CTIPTEST, then change it to CTIPROD. The CRM assigns the call to the user via the extension (targetNumber). Template Infor CRM – run remoteCmd.exe calls the existing program with the same command instead.

Operation

• Actions run in the background; the answer to the phone system never waits for them. If a target cannot be reached, CallerHub tries again after 2 and 10 seconds; the card and the system health show sent and failed events and the last error.
• The text protocol of remoteCmd.exe is unencrypted and has no response: use it only in the internal network and allow the port on the CRM server only for the CallerHub computer.
• The extended recording (Error analysis) contains every sent event.

Modules

The core – accepting the phone number, querying data sources, returning names – is always active. Each module card in the administration shows its state in the title line (e.g. “Running · 2 active actions”, “Incomplete”, “Error”). Everything else can be enabled and disabled under Administration → Modules; changes take effect after saving. The settings of an enabled module are in the card Module: … below. Disabled modules do not appear in the user interface, and their addresses respond with 404.

Rebranding for resellers

Module Rebranding, card Administration → Module: Rebranding. Resellers deliver CallerHub under their own name. The module needs a special licence with the feature modul:rebranding; it is not part of the Full edition or of “all modules”. Add it as a second licence under Administration → Licence (see Editions and licence key).

Unchanged on purpose: licence texts and licence keys (they stay CallerHub's), the help, the Windows service name CallerHub and the program files. “About” shows your details and “Based on CallerHub (c) 2026 - Simon Bernhard”. Changes take effect after Save and apply; the window title follows immediately.

Plugins

Plugins extend the response to the phone system, e.g. append “outside business hours” to the name or show the country for unknown callers. They are deliberately given few rights, but they can do what settings cannot: run any logic per call.

Security

• Plugins run in a separate process. On Windows, CallerHub starts it in an AppContainer (no network, no registry, files readable only in the program folder) and in a Windows job (only one process, at most 512 MB memory, no windows, ends with CallerHub).
• If the AppContainer is not available, the plugin process runs in the Windows job only; the plugin card and the log report “Isolation limited”.
• All plugins together take at most 300 ms per call; if they take longer, CallerHub ends the plugin process, answers the call without the plugin result and keeps the plugins suspended until they are loaded again with “Reload” or at the next start.
• Plugins see only: phone number (E.164 and national), country, called phone number, found name, source, VIP, local time. No passwords, no settings of other areas.
• The “Plugins” module is off by default; each plugin must also be enabled individually.

Install plugins only from a trusted source and protect the Plugins folder against write access. On Linux/Mono (tests only) there is no isolation.

Sample plugins (Plugins\CallerHub.Sample.dll)

Plugin settings (field below the list):

[beispiel.geschaeftszeiten]
zeiten=08:00-17:00
tage=1-5
hinweis= (after hours)

Writing your own plugin

' MeinPlugin.vb – class library for netstandard2.0 with a reference to Plugins\CallerHub.Plugins.dll, compile with the .NET SDK:
'   dotnet new classlib -lang VB -f netstandard2.0 -n MeinPlugin   (add the reference, replace the file)
'   dotnet build -c Release
Imports System.Collections.Generic
Imports CallerHub.Plugins

Public NotInheritable Class ZentralePlugin
    Implements ICallerHubPlugin

    Private suffix As String = " (Zentrale)"

    Public ReadOnly Property id As String Implements ICallerHubPlugin.id
        Get
            Return "firma.zentrale"
        End Get
    End Property
    Public ReadOnly Property name As String Implements ICallerHubPlugin.name
        Get
            Return "Mark main office"
        End Get
    End Property
    Public ReadOnly Property description As String Implements ICallerHubPlugin.description
        Get
            Return "Appends a note to calls to the main office (called number 200)."
        End Get
    End Property
    Public ReadOnly Property settingsExample As String Implements ICallerHubPlugin.settingsExample
        Get
            Return "hinweis= (Zentrale)"
        End Get
    End Property

    Public Sub configure(settings As IDictionary(Of String, String)) Implements ICallerHubPlugin.configure
        Dim value As String = Nothing
        If settings.TryGetValue("hinweis", value) Then suffix = value
    End Sub

    Public Function process(callInfo As PluginCall) As PluginResult Implements ICallerHubPlugin.process
        ' Nothing = change nothing
        If callInfo.calledNumber <> "200" OrElse String.IsNullOrEmpty(callInfo.displayName) Then Return Nothing
        Return New PluginResult With {.displayName = callInfo.displayName & suffix, .note = "Zentrale"}
    End Function
End Class

Copy the DLL to Plugins, click “Reload” under Administration → Module: Plugins, enable it, save. Fields of PluginCall: phoneNumberE164, phoneNumberNational, countryIso, countryCode, calledNumber, displayName, sourceLabel, found, isVip, localTime. The complete source code of the examples (C#, project CallerHub.Sample.csproj) is in the source code under plugins\beispiele.

AI assistant (chat)

CallerHub uses the Claude chat in the browser – no API, no key, no automatic transfer. Procedure: CallerHub compiles a question with context, makes personal details unrecognisable, shows it for review and editing, copies it to the clipboard and opens https://claude.ai/new. Paste it there (Ctrl+V) and send it.

Anonymised: phone numbers (last digits replaced by ****), email addresses (<E-Mail>), IPv4 addresses (192.168.x.x), passwords and keys. Still, check the text before sending it.

AI answers can be wrong. Verify SQL and settings before use with Test connection and a test lookup.

Network discovery

Finds databases, directories and phone systems on the network and checks the configured services – including external ones such as cloud CRM, Microsoft 365 or the SMTP server. To keep the search within clear limits, the following applies:

• The Network discovery module is off by default; when enabled, a yellow note appears in the system health.
• A search runs only after clicking Start search and confirming; every search is logged.
• Only connection setup (TCP) or standard requests (SQL Server Browser UDP 1434, SSDP UDP 1900) – no sign-in, no passwords.
• At most 1,024 addresses per search, network ranges /22 to /32, timeout 400 ms per attempt, “Cancel” at any time.

Results appear in the list while the search is running. Use takes the selected result over: a data source opens the dialog New data source with the matching type and name pre-selected, then server and port are filled in; a mail server goes to the notifications; Asterisk AMI and Mitel SMDR create a receiver of the call analysis; a FRITZ!Box becomes the call monitor. You add credentials yourself.

Search only in your own networks or with permission. Port scans may be reported by security systems (IDS/IPS); inform IT security beforehand.

Firewall examples

Basic rule: inbound only the CallerHub port (example 8443, HTTPS) and only from the IP addresses of the phone system; outbound only to the data sources. All examples use documentation addresses: phone system/cloud 203.0.113.10, public address of the firewall 198.51.100.10, CallerHub server 192.168.10.5, database 192.168.10.30.

1 · OPNsense / pfSense

1. Firewall → Aliases: STARFACE_Cloud (Host: 203.0.113.10), CALLERHUB (Host: 192.168.10.5).
2. Firewall → NAT → Port Forward (newer OPNsense versions may use “Destination NAT”), “+”: Interface WAN, Protocol TCP, Source STARFACE_Cloud (via “Advanced”), Destination WAN address, Port 8443, Redirect target CALLERHUB / 8443, Description CallerHub, Filter rule association “Add associated filter rule”.
3. Save, Apply changes. Verify under Firewall → Log Files → Live View (filter port 8443) with a test call.

2 · Sophos Firewall (SFOS)

1. Hosts and services → IP host: STARFACE_Cloud = 203.0.113.10, CallerHub = 192.168.10.5; Services: CallerHub-8443 = TCP 8443.
2. Rules and policies → NAT rules → Add NAT rule (or the “Server access assistant (DNAT)” wizard): Original source STARFACE_Cloud, Original destination the WAN address, Original service CallerHub-8443, Translated destination CallerHub.
3. Rules and policies → Firewall rules: rule WAN → LAN, source STARFACE_Cloud, destination CallerHub, service CallerHub-8443, action Accept, logging on.

3 · Fortinet FortiGate (FortiOS, CLI)

config firewall address
    edit "STARFACE_Cloud"
        set subnet 203.0.113.10 255.255.255.255
    next
end
config firewall vip
    edit "CallerHub-VIP"
        set extintf "wan1"
        set extip 198.51.100.10
        set mappedip "192.168.10.5"
        set portforward enable
        set extport 8443
        set mappedport 8443
    next
end
config firewall service custom
    edit "CallerHub-8443"
        set tcp-portrange 8443
    next
end
config firewall policy
    edit 0
        set name "STARFACE-zu-CallerHub"
        set srcintf "wan1"
        set dstintf "internal"
        set srcaddr "STARFACE_Cloud"
        set dstaddr "CallerHub-VIP"
        set service "CallerHub-8443"
        set schedule "always"
        set action accept
        set logtraffic all
    next
end

In the web interface, this corresponds to Policy & Objects → Virtual IPs and Firewall Policy. Adapt the interface names (wan1, internal) to your device.

4 · AWS (CallerHub on EC2)

# inbound: only the phone system on port 8443
aws ec2 authorize-security-group-ingress --group-id sg-0aaa1111bbbb2222c \
    --protocol tcp --port 8443 --cidr 203.0.113.10/32
# database (e.g. RDS SQL Server) only from the CallerHub security group
aws ec2 authorize-security-group-ingress --group-id sg-0ddd3333eeee4444f \
    --protocol tcp --port 1433 --source-group sg-0aaa1111bbbb2222c

Console: EC2 → Security Groups → Inbound rules → Edit inbound rules. If required, restrict the outbound rules to the ports of the data sources.

5 · Microsoft Azure (Network Security Group)

az network nsg rule create --resource-group rg-telefonie --nsg-name nsg-callerhub \
    --name Allow-Telefonanlage-8443 --priority 310 --direction Inbound --access Allow \
    --protocol Tcp --source-address-prefixes 203.0.113.10/32 --source-port-ranges '*' \
    --destination-address-prefixes '*' --destination-port-ranges 8443

Portal: Network security group → Inbound security rules → Add. In addition, open the Windows Firewall on the VM (see Windows).

Menu paths and commands refer to current versions of the manufacturers and may differ. Compare them with the manufacturer's documentation and verify the change with a test call. If a reverse proxy is used instead of NAT, enter its IP under Administration → Server → Trusted reverse proxies (advanced mode).

Windows settings (current and legacy versions)

CallerHub offers all steps as buttons in the system health (prompt for administrator rights). For scripts and group policies, the commands are listed here; port 8443, user FIRMA\svc-callerhub and the addresses are examples.

Windows Server 2016/2019/2022/2025, Windows 10/11 (PowerShell as administrator)

# Firewall rule (only from the phone system)
New-NetFirewallRule -DisplayName "CallerHub" -Direction Inbound -Protocol TCP -LocalPort 8443 `
    -RemoteAddress 203.0.113.10 -Action Allow -Profile Domain,Private
# URL reservation for the user or service
netsh http add urlacl url=https://+:8443/ user="FIRMA\svc-callerhub"
# Bind the certificate (thumbprint from the certificate manager, computer account)
netsh http add sslcert ipport=0.0.0.0:8443 certhash=<thumbprint> appid={6b1e1c0a-4f6e-4d3a-9c55-2f7a8e0b6a11}
# Windows service (alternatively: Administration → Operation → Install)
New-Service -Name CallerHub -DisplayName CallerHub -BinaryPathName '"C:\CallerHub\CallerHub.exe"' -StartupType Automatic
Start-Service CallerHub
# Verify
Get-NetFirewallRule -DisplayName CallerHub | Get-NetFirewallAddressFilter
Get-Service CallerHub

Older systems: Windows Server 2012 / 2012 R2 (cmd as administrator)

netsh advfirewall firewall add rule name="CallerHub" dir=in action=allow protocol=TCP localport=8443 remoteip=203.0.113.10
netsh http add urlacl url=https://+:8443/ user="FIRMA\svc-callerhub"
netsh http add sslcert ipport=0.0.0.0:8443 certhash=<thumbprint> appid={6b1e1c0a-4f6e-4d3a-9c55-2f7a8e0b6a11}
sc.exe create CallerHub binPath= "C:\CallerHub\CallerHub.exe" start= auto DisplayName= "CallerHub"
sc.exe start CallerHub

Windows Server 2012 and 2012 R2 only receive security updates through paid extensions (check the current status with Microsoft). Windows 7, 8.1 and Server 2008 R2 are no longer supported by .NET 10 and therefore by CallerHub 3.0. Use a current system for continuous operation.

Service account and permissions

• Recommended: virtual service account NT SERVICE\CallerHub (choose under Administration → Security; applies when the service is set up). When setting up the service, CallerHub grants this account write access to the program folder (and to separate folders for log, statistics and call records) and the interface address in http.sys. After changing the port or HTTPS, remove and set up the service again.
• Alternatively a dedicated account (e.g. FIRMA\svc-callerhub, required for Windows authentication to SQL Server or LDAP with a user account instead of the computer account); LocalSystem only if nothing else is possible (the system health warns).
• icacls "C:\CallerHub" /grant "FIRMA\svc-callerhub:(OI)(CI)M" grants modify permission on the folder.
• Do not run the service and the user interface on the same port at the same time (the system health reports this).

Linux

CallerHub is a Windows program (.NET 10, Windows Forms) and does not run on Linux. For the automated tests, the same source code can be compiled with Mono; this mode is not intended for production use (no Windows service, no DPAPI encryption, no URL reservation, no event log, no plugin isolation).

Linux is more common on the other side: database, phone system (Asterisk/FreePBX) or directory. Examples that allow CallerHub (192.168.10.5) to access them:

# ufw (Ubuntu/Debian): PostgreSQL only for CallerHub
sudo ufw allow from 192.168.10.5 to any port 5432 proto tcp
# firewalld (RHEL, Rocky, Alma, SUSE): MariaDB only for CallerHub
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.10.5" port port="3306" protocol="tcp" accept'
sudo firewall-cmd --reload
# nftables (table inet filter, chain input exists)
sudo nft add rule inet filter input ip saddr 192.168.10.5 tcp dport 5432 accept
# iptables (older systems)
sudo iptables -A INPUT -p tcp -s 192.168.10.5 --dport 5432 -j ACCEPT

• PostgreSQL: set listen_addresses in postgresql.conf accordingly, in pg_hba.conf e.g. host odoo odoo_ro 192.168.10.5/32 scram-sha-256, then reload.
• MariaDB/MySQL: check bind-address in the server configuration; user with read permission only: CREATE USER 'crm_leser'@'192.168.10.5' IDENTIFIED BY '…'; GRANT SELECT ON suitecrm.* TO 'crm_leser'@'192.168.10.5';
• Asterisk: outbound, the phone system must reach CallerHub on port 8080/8443; for HTTPS, Asterisk must trust the certificate.

Security and standards

The card Administration → Security brings together all decisions the operator has to make; the system health shows open recommendations.

Further protection in the program

• Key comparison without timing differences (SHA-256); responses with security headers (CSP, X-Frame-Options, nosniff, no-store); JSON output escapes < > &.
• At most 8 concurrent direct queries per data source, circuit breaker after 5 consecutive errors (30 seconds), account lockout protection for database, LDAP, Exchange and REST.
• Follow-up pages of a REST API only from the same server and without switching to http; responses at most 100 MB; Retry-After is respected.
• Plugins in a separate process with minimal rights; log without keys and passwords, phone numbers masked.
• System health reports: service account with full rights, outdated TLS versions (SSL 3.0, TLS 1.0/1.1) with HTTPS, missing signature of the program file, unreadable keys, network drives the service cannot see.

Supply chain

• Third-party packages with fixed versions and checksums (packages.lock.json); the build checks them for known vulnerabilities.
• Every delivery contains a bill of materials of the third-party packages (SBOM.cdx.json, CycloneDX 1.5) and SHA-256 checksums (SHA256SUMS.txt). Verify: tools\lieferung\lieferung.cmd pruefen <folder> <folder>\SHA256SUMS.txt.
• Digital signature (Authenticode, SHA-256): the build signs CallerHub.exe and the sample plugins with the CallerHub code signing certificate (issued by the own certification authority CallerHub Root CA). CallerHub itself trusts this signature without further steps (e.g. for Load only signed plugins); About and the system health show the signature. For Windows itself (publisher display, policies), run zertifikat-vertrauen.cmd in the program folder as administrator or distribute CallerHub-Root-CA.cer (trusted root certification authorities) and CallerHub-Codesignatur.cer (trusted publishers) by group policy. SmartScreen may still warn about downloaded files until a certificate from a public certification authority is used. Alternatively sign with your own certificate: tools\signieren\signieren.cmd.
• Report vulnerabilities confidentially (see SECURITY.md).

In-house security tests

Relation to standards

CallerHub is not certified. The following standards serve as a benchmark; the comparison and open points are in doc/sicherheitstests.md.

Technical background for administrators

Architecture

• One program file (CallerHub.exe, .NET 10, self-contained) for the program window, the notification area and the Windows service. No installation, no own database, no registry entries apart from the optional service, event source and URL reservation.
• The HTTP interface is based on the Windows HTTP server (http.sys); requests are processed in parallel. All interfaces share one port; the API key in the request decides which interface (and which data sources and allowed IP addresses) applies.
• Phone number lists: sources of type list (database, CSV, LDAP/AD, Microsoft 365, REST) are loaded completely into memory at the start and refreshed in the background (default every 15 minutes, per source). A lookup is a memory access and takes well under a millisecond; a slow or unavailable database does not delay the answer, the last loaded list stays in use.
• Direct queries (SQL with a parameter) ask the database for each call: at most 8 at the same time per source, circuit breaker after 5 consecutive errors (30 seconds).
• Cache: answers of direct queries are kept in memory (example: hits 300 s, unknown numbers 60 s; see Cache).
• Sources are asked in the order of the cards; the first match wins. Rules, block list and VIP list apply afterwards.

Global and per-interface settings

The Windows firewall rule created by CallerHub combines the allowed IP addresses of all interfaces, because all interfaces use the same port.

Files in the program folder

Operation and monitoring

• /health (without key) for load balancers and monitoring; /status and /metrics (Prometheus) with the module Browser access.
• Errors optionally in the Windows Application log (source CallerHub); notifications by email or webhook.
• Settings can be changed while the interface is running: Save and apply applies them without a restart; the service reads them on its next start.
• Update: replace the program folder content and keep the settings file, Logs, Statistics and CallData (see Installation).

Logging and diagnostics

• Log levels Info, Access, Warning, Error, Debug; phone numbers masked unless full numbers are switched on; keys, passwords, Authorization and Cookie always masked.
• Debug logging and the extended recording turn themselves off; the extended recording is limited to 10 MB.
• The diagnostic package is anonymised before it is shown (see Diagnostic package).

Service, backup, diagnostics

Everything for continuous operation is in the card Administration → Operation, in five sections with a short explanation and the matching buttons.

Windows service

• The section shows the state and only the matching buttons: Install as service, Start service, Stop service, Remove service (service name CallerHub, automatic start, restart after failure after 1, 1 and 5 minutes). The service uses the same settings as the user interface.
• While the service is running, keep the interface stopped in the user interface; use the user interface only for configuration and analysis. Restart the service after saving.
• Without a service: Start at Windows sign-in (minimised) starts the user interface in the notification area.

Is CallerHub running as a service? Any of these shows it:

• Administration → Operation → Windows service shows the state (e.g. “Service 'CallerHub' is running.”) and the account; the system health warns with “Service and program are running at the same time” when both use the port.
• Windows: services.msc, entry CallerHub; or in a command prompt:

sc.exe query CallerHub
tasklist /fi "imagename eq CallerHub.exe" /v

A process CallerHub.exe with the session name Services is the service; one in your session is the program window or the notification area icon.

Stop it: Stop service in the card (administrator rights), or as administrator:

sc.exe stop CallerHub
rem permanently: do not start automatically any more
sc.exe config CallerHub start= disabled

Remove service deletes the service registration; the program folder and settings stay.

HTTPS wizard

☰ → Interface → Set up HTTPS …: select a certificate with a private key from the computer's “Personal” certificate store (certlm.msc), specify the port (e.g. 8443) and the Windows user (e.g. COMPANY\svc-callerhub), click Set up. The wizard binds the certificate and sets the URL reservation; “Copy commands” provides the same netsh commands for manual execution. The name in the certificate (e.g. lookup.company.com) must match the address that the phone system calls.

• No certificate yet? The wizard says so and offers Create certificate …: CallerHub creates a self-signed certificate for this computer (RSA 3072, SHA-256, valid for 3 years, names: computer name, full DNS name, localhost and the IPv4 addresses) in the computer's “Personal” store and saves the public part as Certificates\callerhub-<computer>.cer. This computer trusts the certificate automatically (CallerHub enters it under trusted root certification authorities), so browsers on this computer no longer show “not secure” – open the address with a name contained in the certificate, e.g. https://<computer>:8443/stats. Other computers and the phone system: import this file (trusted certificates, e.g. by group policy; Firefox uses the Windows certificates when security.enterprise_roots.enabled is on). For access over the internet, use a certificate from a public or company certification authority instead.
• When switching between HTTP and HTTPS on the same port, Windows refuses the start with “conflicts with an existing registration”. CallerHub detects this and offers to change the reservation (administrator rights).

Windows event log

Create event source registers the source CallerHub once (administrator rights) and then shows “Set up”; the button changes to Remove event source. Errors appear in the Event Viewer under Windows Logs → Application as soon as “Also write errors to the event log” is enabled and saved.

Backup, export, import

• Before every save, CallerHub creates a backup in Backups (at most 20). Restore backup restores one of them.
• Export/Import transfers the settings as an XML file. Passwords are encrypted with the key of this computer; on another computer, enter them again after the import.

Error analysis

All tools are in the menu ☰ → Error analysis (group Operation):

Diagnostic package

The package (ZIP) contains the settings without secrets, system information (version, Windows, memory, display scale, modules, licence, interfaces, HTTPS, port, proxies, notifications), status (JSON), the response times of the user interface (ui-performance.txt: page changes, scrolling, stalls), the logs of the last days and the extended recordings of the last days (Trace\…). Before the package is shown, CallerHub anonymises every entry:

• User, domain and computer names, user folders, network shares and folder names become placeholders such as user-1, <folder-2> or <program folder>.
• Server and host names from the settings and the logs become server-1.example, mail addresses mail-1@example.invalid, IPv4 addresses ip-1; database users in connection strings become user-N.
• Kept: public domains (e.g. microsoft.com), 127.0.0.1 and 0.0.0.0, file names and program names, because they are needed for the analysis.
• The same original value always gets the same placeholder, so relationships remain visible. ANONYMISATION.txt in the package lists what was replaced (categories and counts, not the original values).

The window Diagnostic package lists all entries; selecting one shows its content. Buttons:

• Save as … – saves the ZIP file.
• Send with email program … – opens a new message in the default email program with the package attached (if no email program is registered, Explorer opens with the file selected).
• Upload – transfers the package to the support server (FTP with TLS where offered, fallback address if the name cannot be resolved). The file name gets a random suffix; tell support the name shown after the upload. A different target can be set with DiagnosticUploadUrl in the settings file.

Review the content before passing the package on. Phone numbers are masked in the log anyway.

Event Log: additionally write errors to the Windows Application log (source CallerHub), e.g. for monitoring.

Log

The log opens as a separate window with its own taskbar entry (☰ → Error analysis → Show log). It does not stay in the foreground and can be used next to the main window; it closes when CallerHub exits.

2026-10-14 17:03:58.164 WARN   ip=198.51.100.23 pfad=/lookup nummer=- status=403 quelle=- dauer=0ms ergebnis=IP not allowed

Performance line

While the interface is running, CallerHub writes one line per minute with requests (and when it stops):

INFO   Performance 60 s: requests=41230 rate=687.2/s avg=4ms p50=≤2ms p95=≤10ms p99=≤50ms max=380ms queue_avg=0ms queue_max=12ms concurrent_max=24 errors=0 rejected=0 threads=61 pool_busy=3 memory=88MB gc=120/4/1 call_events_queue=0

Under high load the log file stays open and the main window updates the request list in batches, so neither slows the interface down.

Phone system simulator

☰ → Error analysis → Phone system simulator (test and load test) … or Telefonanlagen-Simulator.cmd in the program folder (CallerHub.exe simulator) opens a separate window that simulates phone systems against a CallerHub installation – for testing a new setup and for load tests.

• Address of CallerHub and API key are taken from the settings; Known numbers (hits in the data sources) and Unknown numbers (%) control the mix.
• Any number of simulated systems at the same time; per system the type and the load: Quiet (1 call per minute), Normal (6 per minute), Busy (1 per second), High (10 per second), Very high (50 per second), Extreme (as fast as possible, 32 parallel loops). Quiet levels run in real time (ringing, talking); high levels report the times without waiting.
• Types: query per call (STARFACE, 3CX, Asterisk, Yealink, Snom), events (/event, Placetel, sipgate.io), call records sent to CallerHub (3CX active socket, OpenScape Business, innovaphone TCP and HTTP) and systems CallerHub connects to (3CX passive socket, Mitel SMDR, Asterisk AMI, FRITZ!Box call monitor).
• The simulated systems answer SSDP searches and listen on their ports, so the network discovery finds them.
• The window shows calls, transmissions, errors, rate and response times per system; CallerHub writes its view to the performance line.

Use the simulator only against your own test systems: high levels produce very many requests, log lines and call records.

Diagnostic run

Menu Diagnostics → Diagnostic run (at most 1 minute) …, button Diagnostic run … in Administration → Operation, or on the command line CallerHub.exe diagnoselauf. The run tests the whole setup on this computer and creates a report for support – within 60 seconds.

1. Current setup: the checks when saving, ports assigned twice, the system health.
2. Computer and network: domain membership, DNS name, network addresses, whether the port is free or used by CallerHub, whether the database and mail servers answer, free disk space, write access to the log and statistics folders, whether error analysis is still active, and how fast the user interface responded.
3. Illogical settings: about 16 combinations an administrator can set (e.g. two interfaces with the same API key, a receiver on the port of the interface, a webhook without address, all data sources off, a missing CSV file); each must be detected. A start with a missing file must not crash the interface.
4. Live test: a second interface only on localhost with free ports and temporary folders, with your data sources and interfaces plus a test database (Samples\simulator-contacts.csv, 20,000 fictitious contacts), all modules, five live receivers and a call event action to a local test receiver. The simulator sends with 11 phone systems; then about 25 addresses are called with correct and wrong keys, unusual numbers and methods.
5. Load steps: 10/s, 50/s, as fast as possible with one and with three phone systems; the run stops at more than 5 % errors or 5 seconds response time and reports the limit.
6. Help and user actions: whether the help describes the functions used, and what you have to do yourself (e.g. firewall rule, settings in the phone system).

Your saved settings are never changed: the run only uses copies and checks at the end that the settings file and the loaded settings are unchanged. Real targets are not contacted – no CRM actions, emails, webhooks, plugins or connections to your phone systems; your data sources receive only a few lookups. Windows may ask once whether CallerHub may accept connections (firewall).

The report diagnostic-run.txt is written for people, not only for support:

• Result – one sentence: everything is fine, or how many points need attention.
• Recommendations – grouped as important, recommended and optional; each with Where, the place in the app (e.g. Administration > Security). Duplicate notes are listed once.
• Performance – in words, e.g. how many calls per minute CallerHub can answer.
• Overview per area and, at the end, the technical details (load steps, every check).

While the run is active, messages of the test interface go to the log only; the footer and the start page are not affected.

Afterwards, the diagnostic package opens with the file diagnostic-run.txt; save, email or upload it as described under Diagnostic package. Like the package, the report is anonymised.

Troubleshooting

Error messages state the cause and a suggestion; details are in the log. The system health shows most causes with a matching button. For a second opinion: ☰ → AI assistant (Claude chat) → Analyse last error ….

Frequently asked questions

A data source or interface shows “Incomplete”. What is missing?

The reason is shown next to the subtitle of the card and as a tooltip over its header; the save bar names the first missing entry as well. Administration → System health lists every incomplete or invalid setting. Open next to an entry opens the page and card and frames the field concerned in red. When you save, invalid fields in the current view are framed as well.

The window sometimes reacts slowly. What can I do?

CallerHub measures how fast pages open, how long scrolling takes and whether the window stops responding. Slow actions (from 150 ms) are written to the log once a minute, e.g. UI performance: page:administration took 260 ms; the diagnostic package contains the summary in ui-performance.txt. Send the package to support. Typical causes are an active error analysis (detailed logging), a full disk or a virus scanner checking the program folder.

Why did Start not start everything?

Start starts everything that is complete. Incomplete data sources and interfaces are skipped; CallerHub names them once and the system health keeps listing them until they are complete.

How many data sources and interfaces are possible?

Up to 10 of each; the counter shows e.g. “3 of 10”. More are possible with a special licence (callerhub.de).

How do I change the order of the data sources?

Drag the header of a card to the new position (a line shows where it will be placed), or use the arrow buttons in the open card. The first source with a match supplies the name.

Where are the database drivers?

In the Drivers folder next to CallerHub.exe. After an update from an older version, the folder native and an Oracle.ManagedDataAccess.dll next to the program file are no longer needed and can be deleted.

The SQL assistant finds employees, but not customers or suppliers.

In many ERP systems the phone numbers are in a separate communication table, linked by a key to the company or person. The assistant recognises such links and proposes a query that joins the tables (one or two levels, e.g. company and contact person). Check the proposal with Test before saving.

Which separator do lists use?

A semicolon everywhere, e.g. in the block list, the VIP list, recipients and replacements (one per line, e.g. Limited;Ltd). The former notation => for replacements is still accepted.

How do I send diagnostic data to support?

☰ → Error analysis → Create and view diagnostic package …; check the entries in the window, then Save as … or Send with email program …. User, computer and server names, folders, mail and IP addresses are replaced by placeholders (see Diagnostic package).

The phone system does not show names. How do I find the cause?

See Typical errors when connecting. If that does not help: ☰ → Error analysis → Start extended recording …, make a test call, then create a diagnostic package – it contains the recording.

What does “Listening” mean?

The interface is running, but no phone system has sent a request yet. After the first request, the indicator changes to “Running”. If it stays at “Listening” during a test call, the request does not reach CallerHub (address, port, firewall).

How do I know whether CallerHub runs as a Windows service, and how do I stop it?

See Windows service: the card shows the state; sc.exe query CallerHub and sc.exe stop CallerHub work in a command prompt.

I changed the language, but nothing happened.

A new language takes effect after a restart. The dialog “Select Language” offers Restart now or Later.

Where are all settings? Some cards are missing.

Simple mode shows only what is needed for operation. ☰ → Show advanced settings shows everything, e.g. “Display and link” of a data source or the cards Security and Operation in the administration.

How do I see the current settings when the file is encrypted?

Administration → Privacy → Show current settings … lists all saved settings; passwords, keys and credentials are shown as ***.

Editions and licence key

CallerHub comes in two editions. A licence key is entered under Administration → Licence; CallerHub checks it without an internet connection using a signature (RSA 3072 bit, SHA-256, according to BSI TR-02102-1) and shows customer, expiry date and the unlocked features.

Several licences: the card shows all entered keys as a list (customer, licence number, features, valid until, state). Add licence … adds a key, the pencil replaces it, the bin removes it. The features of all valid keys add up – e.g. the Full edition plus the special licence Rebranding, or an additional interface package. The status line shows the combined result.

The Licence card lists every feature and module that requires a licence with its state (Licensed or Not licensed) for the entered key or the trial. Modules of the Full edition are also marked “· Full edition” under Administration → Modules. Licence keys are available via callerhub.de.

Licence agreement and privacy notice

The licence agreement and the privacy notice are in the program folder: LICENSE.txt (English) and LICENSE.de.txt (German, authoritative), PRIVACY.txt and PRIVACY.de.txt.

• Basic edition: free for private and commercial use on any number of computers; no entitlement to support or updates.
• Full edition: simple, non-exclusive right of use for the features and term stated in the licence key, for the customer named in it.
• Not permitted: circumventing the licence check, modifying or reverse engineering the program (except where permitted by law), removing notices. Passing on the unmodified program folder is permitted (without licence keys and settings).
• Data: CallerHub works on your computers only and does not send data to the provider – no telemetry, no advertising. You are the controller under the GDPR; the privacy notice lists all data, folders, retention periods and recipients for your records (Art. 30 GDPR) and your privacy information (Art. 13/14 GDPR).
• Liability: Basic edition only for intent and gross negligence; Full edition according to statutory provisions with the usual limitation for slight negligence. German law applies; mandatory consumer rights remain unaffected.

Licences

CallerHub (c) 2026 - Simon Bernhard · callerhub.de

Icons: Bootstrap Icons, MIT License, Copyright (c) 2019-2024 The Bootstrap Authors.

CallerHub contains the .NET 10 runtime and Microsoft.Data.SqlClient (Microsoft, MIT License), System.Data.Odbc and Oracle.ManagedDataAccess.Core (Oracle Corporation). The licence texts are in the Licenses folder (overview OVERVIEW.txt). ODBC drivers come from the respective manufacturers. Product names mentioned are trademarks of their respective owners; CallerHub is not affiliated with these manufacturers.