Docs / Phone system

Phone numbers and routes

Calls from outside arrive on a trunk from your carrier, addressed to one of your phone numbers (DIDs). Phone numbers (DIDs) decides where each number rings. Calls to outside numbers leave through Outbound routes, which decide which dialled numbers may go out, how they are rewritten and over which trunks. This chapter covers both, caller ID, and emergency calls. Connecting the carrier itself is in Trunks (carriers).

Incoming calls

A call from the carrier is matched to a phone number of a tenant and sent to that number's destination. A number nobody routed is refused as an unallocated number without being answered, so the carrier plays its own "not in service" message. The refusal is noted in the server's log with the number and the trunk.

Routing a phone number

1. Pick the tenant at the top of the console.
2. Open Phone numbers (DIDs) and click Route a number.
3. Fill in the form (see the table below) and click Route this number.

Numbers are stored as digits with the country code. When the server's Country tones setting is us or ca, a 10-digit number gets its leading 1, so (612) 555-0100 is stored and matched as 16125550100. The list shows it as +16125550100.

A number can be routed once per trunk on the whole server, because the carrier delivers it to the server rather than to a company. Routing it a second time says "DID 16125550100 is already routed".

Catch-all routes

* in Phone number routes every number on one trunk that has no route of its own, shown as Everything else in the list. A catch-all must name its trunk under Arriving on, and each trunk has at most one. Use it for a trunk that belongs to one company, so new numbers from the carrier ring somewhere even before you route them one by one.

Which route wins

For a call on a given trunk, Onyx Voice looks for, in this order:

1. a route for that number on that trunk;
2. a route for that number with Any trunk;
3. that trunk's catch-all.

A trunk that belongs to one tenant only carries that tenant's numbers. A trunk shared by all tenants carries the numbers of every tenant, which is how a hosted server receives all its companies' numbers on one carrier account.

Changing or removing a route

The list shows each number, where it goes, its trunk and its options (name prefix, recorded, queue priority). There is no edit button: to change a route, click Remove (twice) and route the number again. Calls to it are refused in between, so do it at a quiet moment.

From the command line:

onyx did list acme
onyx did add acme +16125550100 800 --name "Main line" --cid-prefix "Main: " --priority 3
onyx did add acme "*" 101 --trunk ExampleTel
onyx did delete acme 7

onyx did list shows the id that onyx did delete needs.

Destinations

Wherever a call needs a destination (a phone number, a menu option, a ring group or queue that nobody answers, business hours), the list in the console offers:

• Hang up;
• any number in the tenant's plan, under Numbers: an extension, ring group, call queue, conference room, paging group, auto attendant or business hours number;
• Voicemail of an extension that has voicemail on.

On the command line and in imports the same destinations are written as a number (800), a voicemail box (vm:101) or hangup. The destination must exist when you save. If it is deleted later, calls that would go there end and the engine writes a warning to its log (Server › Logs & diagnostics).

Outside numbers cannot be destinations. To send a phone number straight to a mobile or an answering service, make a ring group whose only member is the outside number (written as your users dial it) and route the phone number to the ring group.

Caller names

If the tenant has contacts, an incoming caller whose number is in them is shown with the contact's name instead of whatever name the carrier sent. The Name prefix is added in front after that, so a receptionist sees Sales: Alice Jones. Contacts and directory sync are in Contacts and directory sync.

Callers ahead in the queue

Place in queues gives everyone who calls this number priority in call queues: Higher, High and First in line are priorities 3, 6 and 10; a caller with a higher priority is answered before callers with a lower one, whatever their wait. Use it for a VIP or partner line. Queues are covered in Call centre.

When an incoming call does not arrive

• Check that the number is routed exactly as the carrier sends it: look in the server's log for the "unrouted DID" notice, which shows the digits that arrived.
• If the trunk puts the number somewhere unusual, change the trunk's Phone number is in setting; see Incoming numbers.
• If the tenant is switched off, all its numbers are refused.
• More in Troubleshooting.

Outbound routes

An outbound route says: numbers dialled like this go out over these trunks. A tenant needs at least one route before anyone can call outside; without a matching route a caller hears that the number is not in service.

Creating a route

1. Open Outbound routes and click New route.
2. Under Start from, click a preset or type the patterns yourself:
   • US: 9 + number fills 9|1|NXXNXXXXXX and 9||1NXXNXXXXXX;
   • US: no prefix fills |1|NXXNXXXXXX and 1NXXNXXXXXX;
   • Emergency (911) fills the emergency numbers (see Emergency calls);
   • International fills 9||011..
3. Name the route, for example US calls, and set its Priority (lower runs first).
4. Dial patterns: one per line (syntax below).
5. Trunks, in order: tick the trunks the route may use. Shared trunks are marked "(shared)".
6. Caller ID for this route: leave empty to use each extension's own, or enter a number for every call on this route.
7. Tick Emergency route only for emergency numbers.
8. Click Create route.

If there is no trunk yet, the form says so; add one first on Trunks (carriers).

Dial pattern syntax

A pattern is prefix|prepend|match, or just match:

• prefix: digits the person dials first that are removed before the number goes out, such as the 9 for an outside line. Up to 8 digits, * or #.
• prepend: digits added in front of what is left, such as a 1 before a 10-digit number. Up to 8 digits, optionally starting with +.
• match: what the rest of the dialled number must look like.

Examples:

A pattern that breaks these rules is refused with a message naming it. Patterns of two parts (9|911) are refused: write all three parts (9||911) or only the match.

The number that reaches the carrier is then written in the format that trunk wants (+E.164, 11 digits and so on) and the trunk's dial prefix is put in front; see Number formats. You do not need separate routes per carrier format.

Which route a call takes

When someone dials, Onyx Voice first looks at the tenant's own numbers and feature codes; a dialled number that is an extension or a menu never goes out. Then it tries the outbound routes from the lowest Priority number up, and the first route with a matching pattern takes the call. If two routes could match, give the more specific or more important one (emergency) the lower priority.

Before an outside call leaves, the tenant's call limits are checked (international and premium numbers, calls at once, calls per hour, daily spend); emergency routes are never limited. See Call limits (toll fraud).

Trunk order and failover

A route tries its trunks in order. It moves on to the next trunk when the current one cannot take the call: the carrier is unreachable, rejects the call as congested, or the trunk is at its Maximum simultaneous calls. A busy number or a call nobody answers is not retried on another trunk. When no trunk can take the call, the caller hears "all circuits are busy".

In the console the trunks are tried in the order the page lists them, which is the order they were added. For another order, create the route on the command line, where --trunks gives the order. A route uses 1 to 8 trunks, and a trunk that is switched off is skipped.

Changing or deleting a route

The list shows each route's priority, name, patterns, trunks (in order, with arrows) and caller ID. There is no edit button: click Delete (twice) and create the route again.

From the command line:

onyx route list acme
onyx route add acme "US calls" --pattern "9|1|NXXNXXXXXX" --pattern "9||1NXXNXXXXXX" --trunks ExampleTel,BackupTel --priority 100
onyx route add acme Emergency --pattern 911 --pattern "9||911" --pattern 933 --trunks ExampleTel --priority 1 --emergency
onyx route delete acme "US calls"

Caller ID

An outside call carries one caller ID number, chosen in this order:

1. On an Emergency route: the extension's Emergency caller ID, else its Outbound caller ID, else the tenant's main number.
2. The route's Caller ID for this route, if set.
3. The extension's Outbound caller ID.
4. The tenant's Main number.

Calls from outside callers that are forwarded out again (call forwarding, ring group members with an outside number) carry the tenant's main number, if it has one. At a hot desk, the logged-in person's outbound caller ID is used, but the emergency caller ID stays the desk's own.

If none of these is set, the call goes out with the extension number as caller ID, which carriers refuse or replace. Set at least the tenant's main number (Main number). Carriers accept only numbers that are on your account (or that you have registered with them), so use your own numbers.

The trunk then writes the number in the carrier's format (Send caller ID as) and in the header the carrier reads (Caller ID header); see Caller ID header. The caller's name is sent too, but most carriers show their own directory name instead.

Calls between extensions show the caller's name and extension number.

Emergency calls

Every tenant that has outside calling needs an emergency route.

1. Open Outbound routes and click New route.
2. Click Emergency (911). It sets priority 1, ticks Emergency route, names the route Emergency if the name is empty, and fills the patterns. Make sure they read:

   911
   9||911
   933

   (9||911 catches people who dial 9 first out of habit; 933 is the address test number many US carriers answer.)

3. Tick the trunks, ideally more than one.
4. Click Create route.

What makes a route an emergency route:

• calls on it always go through, even when call limits have stopped the tenant's other outside calls;
• they carry each extension's Emergency caller ID, the number your carrier has registered to the street address where that phone is.

Good practice and limits:

• Register a street address with your carrier for every number you use as an emergency caller ID, and set each extension's Emergency caller ID to the number for its location. Remote and home workers need their own.
• Do not use 911 or 933 as numbers in the tenant's plan: numbers in the plan are matched before routes and would catch emergency calls.
• Test with 933 after any change to routes or trunks.
• Onyx Voice does not yet notify a front desk or security when someone dials 911, and does not send location details other than the caller ID number.

Number formats from the trunk

How a dialled number and the caller ID are written for the carrier (with or without +, 10 or 11 digits, a tech prefix) is a setting of each trunk, not of the route. So one route can use trunks of carriers with different formats. See Number formats.