Docs / Call handling

Contacts and directory sync

Contacts are the outside people and companies a tenant calls: customers, suppliers, the on-call technician's mobile. Each tenant has its own list. This chapter covers adding contacts by hand, importing and exporting them as CSV, keeping them in step with Active Directory, another LDAP directory or Microsoft 365, and where contacts show up: desk phone phonebooks, softphones, and the caller's name on incoming calls.

Contacts are managed per tenant on the Contacts page. Pick the tenant first in the tenant picker at the top of the console (system administrators); tenant administrators see their own tenant's list.

Where contacts show up

• Desk phone phonebooks. Phones provisioned by Onyx Voice get the tenant's phonebook: every enabled extension and ring group by name, then every contact, one entry per number. A contact's work number is listed under the name; a mobile or other number as "Name (mobile)" or "Name (other)". The list is sorted by name. Phones pick up changes at their next phonebook refresh. See Desk phones for which makes get a phonebook.
• Softphones. The Onyx Softphone apps show the company directory: the tenant's own numbers first (people with a green dot when one of their devices is registered), then the contacts with all their numbers. The browser softphone in the portal has no directory. See Softphones.
• The caller's name on incoming calls. When a call comes in from a carrier on one of the tenant's numbers, Onyx Voice looks the caller's number up in the tenant's contacts and shows the contact's name instead of whatever name the carrier sent. The phones that ring, the call history and the queue wallboard all see that name.

How numbers are matched for caller names: only the digits count, so +1 (612) 555-0100, 612-555-0100 and 16125550100 are the same number. When the server's Country tones setting (engine.tone_zone) is us or ca, a 10-digit number is taken as 1 plus the number, so a contact stored as 612 555 0100 matches a carrier that sends +16125550100. Numbers shorter than 3 digits are never matched. The name shown is at most 40 characters, on one line, without quotation marks.

Caller names come from contacts only for calls from outside on a phone number (DID). Calls between extensions already carry the extension's name. A phone number with a caller ID prefix set (for example Sales: ) puts the prefix in front of the contact's name.

Adding and editing contacts

1. Open Contacts and select Add contact.
2. Fill in Name (required), Company, Work number, Mobile, Other number and E-mail. A contact needs at least one number; numbers can be written in any format.
3. Select Add contact. The console confirms that phones show the contact at their next phonebook refresh.

To change a contact, select Edit on its row, change the fields and select Save contact. To remove one, select Delete and confirm. Contacts that came from a synced directory have no Edit or Delete: change them in the directory instead (see below).

The search box above the list finds contacts by name, company or number. The From column shows where each contact came from: Added here, Imported, LDAP directory or Microsoft 365.

Importing and exporting CSV

Export CSV downloads the tenant's contacts as a CSV file.

To import:

1. Select Import CSV.
2. Choose a CSV file whose first row names the columns. Onyx Voice looks for name (or full name, display name), company (or organization), and the numbers work, mobile and other, plus email. Exports from Outlook and Google Contacts work as they are: their Business Phone, Mobile Phone and E-mail Address columns are recognised.
3. To replace an earlier import instead of adding to it, tick Replace contacts from earlier imports (contacts added by hand stay). Only contacts that came from a CSV import are replaced; contacts added by hand and contacts from a synced directory are left alone.
4. Select Import. The console reports how many contacts were imported and how many rows were skipped: a row is skipped when it has no name or no number.

The file needs a name column and at least one number column, or nothing is imported.

Syncing from a directory

A synced directory keeps contacts in step with the place your organisation already keeps people: Active Directory or another LDAP server, or Microsoft 365. People with a phone number become contacts and are updated on every sync; people who leave the directory (or lose their phone number) are removed. Contacts from a directory are read-only in the console.

To add one: on Contacts, in Synced directories, select Add a directory, choose the Kind, give it a Name (for example "Company directory") and fill in the fields below. Sync every (minutes) is how often it runs (15 to 1440, default 60). Selecting Add directory saves it and runs the first sync at once; the console shows how many contacts it kept, or why it failed.

The Synced directories list shows each directory's last sync (the number of contacts, or Failed with the reason) and how often it runs. Sync now runs it immediately, Edit changes it, and Delete removes the directory together with its contacts.

Active Directory and LDAP

From each entry Onyx Voice reads the name (displayName, else cn), the company (company, else o), the work number (telephoneNumber, else ipPhone), mobile, homePhone (as the other number) and mail. Results are read in pages, so large directories work. Use ldaps:// whenever the directory is reached over a network you do not control: with ldap:// the account's password travels unencrypted.

Microsoft 365

Onyx Voice reads users through Microsoft Graph with an app registration of its own:

1. In the Microsoft Entra admin center, register an application (for example "Onyx Voice directory").
2. Under API permissions, add the Microsoft Graph application permission User.Read.All and grant admin consent.
3. Under Certificates & secrets, create a client secret and copy its value.
4. In Onyx Voice, choose Microsoft 365 as the Kind and enter the Directory (tenant) ID and Application (client) ID from the app's overview page, and the Client secret.

Onyx Voice reads each user's display name, company, business phones (the first as the work number, the second as the other number), mobile phone and e-mail. Disabled accounts are left out. When Microsoft refuses the sign-in or the user list, the error Microsoft gives is shown as the sync result: most often the permission is missing or admin consent was not given.

From the command line

The same operations are available with onyx (see Command line):

onyx contact list acme --search smith
onyx contact add acme "Jane Customer" --company "Acme Supplies" --work "+1 612 555 0100" --email [email protected]
onyx contact import acme contacts.csv --replace
onyx contact delete acme 42
onyx directory list acme
onyx directory sync acme          (all of the tenant's directories, or add the directory's ID)
onyx directory delete acme 3

To add a directory from a shell, put its password or client secret in the environment, never on the command line:

ONYX_DIRECTORY_SECRET='...' onyx directory add-ldap acme --name "Company directory" --url ldaps://dc1.example.com \
    --base-dn dc=example,dc=com --bind-dn [email protected] --every 60
ONYX_DIRECTORY_SECRET='...' onyx directory add-m365 acme --name "Microsoft 365" --m365-tenant <tenant id> --client-id <client id>