Onyx VoiceDocumentation
All chapters

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). Inbound routes decide 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 Inbound routes and click Route a number.
  3. Fill in the form (see the table below) and click Route this number.
FieldWhat it does
Phone numberThe number in any format: (612) 555-0100, +1 612 555 0100 or 16125550100 are the same. Or * for every number on a trunk (below).
Send calls toThe destination (below).
Arriving onAny trunk, or one trunk if the number must only be accepted from it.
LabelA name for the list, for example Main line.
Name prefixPut in front of the caller's name on the phone display, for example Sales: . Up to 20 characters.
Record every call to this numberRecords all calls to this number; see Call recording.
Place in queuesNormal, Higher, High or First in line: callers on this number go ahead of others in any queue they reach.

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. The same setting is on Trunks: Incoming calls on the trunk's row (see trunks).

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).

To change a route, click Edit on its row (or the row itself). The form opens filled in with the route as it is: change the number, where it goes, the trunk, the label, the name prefix, recording or the place in queues, then click Save changes. Calls to the number keep arriving while you edit, and the change applies within a few seconds.

To remove a route, click Remove (twice). Calls to that number are refused from then on.

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 set acme 7 --to 801 --priority 0
onyx did delete acme 7

onyx did list shows the id that onyx did set and onyx did delete need. onyx did set changes only what you give it.

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.

Blocked callers

On Inbound routes, the Blocked callers card holds callers the company refuses, on every one of its numbers: they hear "the number you have dialled is not in service" and nobody's phone rings.

  • To block a number, type it under Number, optionally why, and click Block. Any format works; North American numbers are stored with their leading 1, so (612) 555-0199 and 16125550199 are the same caller.
  • Refuse callers who hide their number refuses calls with no caller number (anonymous, restricted, private).
  • Click Unblock to let a number through again.
  • People can block a caller themselves: in the portal's Recent calls, an outside call has a Block button. It blocks the number for the whole company, and the list shows who did it.

From the command line: onyx block add acme 6125550199 --note "robocaller", onyx block remove acme 6125550199, onyx block anonymous acme on and onyx block list acme.

Caller ID routing

The Caller ID routing card sends callers whose number starts with some digits somewhere else than the number they dialled would send them: an area code (612), a prefix or one whole number (a key customer straight to their account manager). Choose Go to, and under On either one of your numbers or Any of our numbers. When several rules match, the longest one wins. Blocked callers are refused before any rule. From the command line: onyx callerroute add acme 612 102 --name "Local customers" (with --did <number> for one number), onyx callerroute list acme and onyx callerroute delete acme <id>.

Text messages (SMS)

Your phone numbers can send and receive texts through the carrier's messaging service. Onyx Voice works with Twilio and Telnyx (the number must be enabled for messaging at the carrier; in the US, business texting also needs the carrier's 10DLC registration).

  1. On Integrations (API), card Text messages, choose the Carrier, give the account a name and its credentials (Twilio: the Account SID and Auth Token; Telnyx: an API key), and click Add account. A system administrator's account serves every tenant that has none of its own.
  2. Copy the account's Incoming address and give it to the carrier: in Twilio, as the phone number's "A message comes in" webhook (HTTP POST); in Telnyx, as the messaging profile's webhook URL.
  3. On Inbound routes, edit the number and choose who gets its texts under Texts go to.

That person then has a Messages card in the portal: the conversations on their numbers (newest first, with unread counts), each conversation, a reply box, and a new text to any number. Each incoming text is also e-mailed to them. Twilio's posts are checked with Twilio's signature; Telnyx's are accepted only at the account's secret address.

From the command line: ONYX_SMS_SECRET=<token> onyx sms account-add acme --provider twilio --name Twilio --sid AC... (prints the incoming address), onyx sms to acme 16125550100 101 and onyx sms list acme.

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.
In the matchMeans
0 to 9, *, #That key exactly
XAny digit 0 to 9
ZAny digit 1 to 9
NAny digit 2 to 9
[1-4], [0-35]One digit from the list or range
. at the endOne or more further characters
! at the endZero or more further characters

Examples:

PatternThe person dialsNumber after the route
9|1|NXXNXXXXXX9612555010016125550100
9||1NXXNXXXXXX91612555010016125550100
|1|NXXNXXXXXX612555010016125550100
1NXXNXXXXXX1612555010016125550100
9||011.9011441632960000011441632960000
911911911

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.

To hide your number on one call, dial *67 before it, for example *6716125550199. The call goes out marked private (a SIP Privacy: id request); whether the person called sees "Private" depends on the carrier, and calls to emergency numbers always show it.

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.