Lines

A line is a dialable subscriber identity: the thing a call is delivered to and the thing calls originate from. Lines are declared under the top-level lines: key, keyed by name — conventionally the extension or number that reaches them, since translation rules commonly target resource-id: "!dialedNum".

lines:
  "1001":
    line-profile: standard
    devices: [alice-desk, alice-mobile]
    voicemail: "1001"
    caller-id: "+14155551001"
    internal-caller-id: "1001"
    caller-id-name: "Alice Alvarez"
    e911:
      address: 100 Main St Suite 4, San Francisco CA
      zip: "94105"
      state: CA

Every ordinary line needs a line-profile — the line profile carries the service-class settings (translation context, features, screening, codecs) shared across lines, while the line itself carries per-subscriber identity.

Lines and devices

A device is a single SIP endpoint (a physical phone, a softphone client). Devices are declared in the top-level devices: map, which records which line each device belongs to; the line lists the same devices back:

devices:
  alice-desk: "1001"
  alice-mobile: "1001"

lines:
  "1001":
    devices: [alice-desk, alice-mobile]
    ...

• Devices register against your SIP realm as device@realm. Credential minting and registration behavior are covered in the device registration guide.
• All of a line’s devices ring together when the line is called, and any of them can originate calls as the line — a call from alice-mobile is, for all routing and identity purposes, a call from line 1001.
• Devices ring for the profile’s max-ring-time (default 25 seconds) before the line’s no-answer handling takes over; a subscriber’s configured no-answer forward timeout, when set, overrides it for that line.

What happens when a line is called

When a translation resolves to a line, in order:

1. Do-not-disturb — if the line has DND set (and its profile grants the dnd feature), the dial is skipped entirely and the call goes to the line’s voicemail; with no mailbox available it fails to the target’s failure treatment.
2. Call-forward always — if set (and granted), the call re-originates toward the forward target instead of ringing devices.
3. Concurrent-call cap — an over-cap line refuses the call with all-circuits-busy.
4. Devices ring. On busy: call-forward-busy if set and granted, otherwise voicemail with the busy greeting. On no-answer: call-forward- no-answer if set and granted (its timeout shortens the ring), otherwise voicemail with the no-answer greeting.
5. Voicemail fallback requires both a voicemail box on the line and the voicemail calling feature in its profile. A line missing either plays the failure treatment instead — two different caller experiences from what looks like the same configuration, so check both halves when “calls aren’t reaching voicemail”.

DND, forwards, and speed dials are subscriber state managed through the API or portal, not authored in YAML — but the entitlement to each feature comes from the line profile, and a feature the profile doesn’t grant is ignored even if state exists for it. Feature changes take effect within a few seconds, not instantly.

Forwarded calls act as the line

A forward is a new call from the line: the forward target is walked through the line profile’s translation context, screened against its screening context, and dialed with the original caller’s identity presented (with a Diversion header naming the line). See the translation-contexts page for why line contexts must handle off-net numbers.

Caller identity fields

Field	Presented to	Notes
caller-id	External destinations (trunks, other namespaces)	The line’s outward number. Enforced: what the device asserts is ignored unless the profile sets allow-unrestricted-caller-id. Must be a valid US number when e911 is configured.
internal-caller-id	Other lines in this namespace	Typically the bare extension.
caller-id-name	Both	Display name.

E911

The e911 block registers the dispatchable address for the line:

e911:
  address: 100 Main St Suite 4, San Francisco CA
  zip: "94105"
  state: CA

Configuring an e911 address requires the line’s caller-id to be a valid US number — that number is the identity asserted on emergency calls and the key your E911 provider uses to look up the address. Keeping this address current when the line physically moves is a regulatory obligation on you as the operator.

911 database population

Currently, the 911 address fields are METADATA ONLY and are not automatically applied to the ALI database or transmitted on an emergency call. With this version of the program, you are still responsible for populating and managing the location database.

Pointer-line variants

A line doesn’t have to ring devices. Three exclusive variants turn a line name into a pointer — useful because translation rules that target line: !dialedNum then work uniformly for real lines and delegated numbers alike. Each variant excludes all the ordinary line fields (profile, devices, voicemail, ring group, and the other pointer kinds).

alias — another name for an existing line

lines:
  "1001":
    line-profile: standard
    devices: [alice-desk]
  "4155551001":
    alias: "1001"

Calls to the alias behave exactly as calls to the target line. Chains of aliases are followed; loops are rejected at validation.

alias-namespace — delegate to another namespace

lines:
  "4155552000":
    alias-namespace: pstn-customer-a     # a received alias or a namespace ID

Calls landing on this line transfer into the named namespace, subject to that namespace’s linkage policy (it must allow inbound transfers from you), and are routed by its configuration. This is the standard way a carrier namespace hands a DID block down to a customer namespace.

alias-trunk — deliver onward to a trunk

lines:
  "4155553000":
    alias-trunk: customer-pbx

Calls landing on this line are dialed straight out the named trunk — the usual shape for DID delivery to a trunk-served customer PBX, without writing a per-DID translation rule.

Ring-group lines

A line may also front a hunt group instead of its own devices:

lines:
  "1000":
    line-profile: standard
    ring-group: front-desk

Calls to the line run the ring group. This combines with a profile (the line can still originate) but excludes devices and voicemail on the line itself — no-answer handling belongs to the ring group’s no-answer target.

Concurrency

max-concurrent caps simultaneous calls on this line (inbound and originated). It overrides the profile’s template value; zero or absent falls back to the profile, and no value anywhere means unlimited. Over-cap calls receive all-circuits-busy. Caps count per line — never pooled across lines sharing a profile.

Validation summary

• line-profile must name a defined profile (ordinary lines).
• devices entries must exist in the top-level devices: map, and the map must agree: each listed device must be assigned to this line in devices:, and every devices: map entry must name a line that exists. A device assigned to one line but listed by another is rejected — it would misattribute the device’s calls.
• voicemail must name a defined box that is not a distribution list.
• ring-group excludes devices; alias variants exclude everything else.
• e911 requires a valid US caller-id.
• Alias chains must not loop; pointer targets must resolve.