Voicemail Boxes

A voicemail box stores messages for a subscriber (or fans them out to a group — see distribution lists below). Boxes are declared under the top-level voicemail-boxes: key; each references a voicemail context that supplies its policy.

voicemail-boxes:
  "1001":
    context: standard

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

Field	Meaning
`context`	Required. The voicemail context whose policy governs this box.
`members`	Makes this a distribution list (below).
`greeting-recording`	Distribution lists only: the static greeting played to callers.

Box names that are all digits must match the context’s box-id-length so the dial-in menus can parse them; alphanumeric names are fine for boxes that are never dialed directly (typically distribution lists).

How calls reach a box

Line fallback — the usual path: a line with voicemail: <box> (and the voicemail calling feature in its profile) sends busy / unanswered / DND calls to the box, with the matching greeting kind.
Direct translation target — resource-type: voicemail-box sends a call straight to the box (“leave a message for the sales team”), playing the default greeting.
Operator target — a context’s press-0 destination can be a box.
Subscriber access — the *98 / *97 feature codes (feature-code maps).

A box cannot be bound to a line if it is a distribution list.

PINs

New boxes are created without a PIN, and a PIN-less box can never be opened through the dial-in path — so unconfigured boxes can’t be guessed at (“wardialed”). The initial PIN is set through one of two authenticated paths:

the subscriber dials the own-line access code (*98) — the line itself is the credential, no PIN prompted — and sets one in the options menu;
an administrator sets it through the management API.

PINs are stored only as strong one-way hashes; an administrative reset clears the PIN (returning the box to not-dial-in-accessible) rather than restoring any default. Minimum length comes from the context’s min-pin-length. Three wrong entries end a dial-in attempt.

What callers hear: leaving a message

Greeting. Selection order: an active temporary greeting → the subscriber’s recorded greeting for the situation (busy greeting on a busy-forward, otherwise the default greeting) → the context’s default-greetings recording → silence. During the greeting, # skips straight to the beep and 0 transfers to the context’s operator.
Recording, bounded by the context’s length and silence limits; # ends the recording. Messages under min-message-seconds are discarded with a courtesy prompt.
Review menu: 1/# send the message · 2 listen back · 3 re-record (up to max-recording-attempts takes) · 4 toggle urgent · * cancel without sending. A caller who simply hangs up mid-recording or mid-review still has their message saved — only an explicit * discards it.
Full box: per the context’s mailbox-full-policy, the caller either hears the mailbox-full announcement (reject) or the oldest heard message is quietly discarded to make room (overwrite-oldest).

Urgent-flagged messages are counted separately and light message-waiting indicators with higher priority on phones that support it.

The subscriber menus

Both access paths — *98 from the subscriber’s own line (no PIN) and the PIN-gated dial-in (*97, from any phone) — land in the same menu tree.

Main menu

Key	Action
`1`	Listen to new messages
`2`	Listen to saved (heard) messages
`3`	Open a folder
`5`	Compose a message to another box (when the context enables send/forward)
`0`	Mailbox options
`*`	Exit

While listening / after a message

Keys work as barge-in during playback — no need to wait for the message or the menu prompt to finish.

Key	Action
`1`	Replay the message
`2`	Move it to a folder
`3`	Play the envelope (received time in the context’s timezone, and the caller’s number)
`5`	Call the sender back (below)
`7`	Delete
`8`	Forward to another box (when the context enables send/forward)
`9`	Save and play the next message
`0`	Back to the main menu
`*`	Exit

A message played to the end is marked heard — that’s what clears the message-waiting lamp. Barging in doesn’t mark it; the action you choose does. When the box’s envelope-autoplay preference is on, each message is automatically preceded by its spoken envelope — no need to press 3.

Forward and compose destinations are checked before anything is written: an unknown box number is refused with an “incorrect mailbox” prompt and re-asked. A distribution list is a valid destination — the message fans out to every member, each receiving their own independent copy.

Folders. Messages can be filed into standard folders — 0 Inbox, 1 Family, 2 Friends, 3 Work, and 4–8 five general-purpose folders — and browsed from main-menu 3.

Mailbox options (main menu 0)

Key	Action
`1`	Change PIN
`2`	Record the default greeting
`3`	Record the busy greeting
`4`	Record a temporary greeting (vacation) — activates when accepted
`5`	Toggle envelope autoplay (hear each message’s time and caller automatically before it plays)
`0` / `*`	Back

Each recorded greeting gets its own review pass (accept / listen / re-record / cancel); the live greeting is only replaced when the new take is accepted, so an abandoned attempt changes nothing.

Calling a sender back. Message-menu 5 places a return call to the number that left the message, routed through the context’s callback translation policy. Sessions from external phones are refused unless the context explicitly allows it — see the callback policy and its toll-fraud rationale.

Message-waiting indication (MWI)

Unread counts drive message-waiting notification to the devices of the line bound to the box: lamps light when a message arrives and clear when the last new message is heard or deleted, on all of the line’s registered devices.

Distribution lists

A box with members is a distribution list — an announcement target that fans a single recording out to every member:

voicemail-boxes:
  all-staff:
    context: standard
    members: ["1001", "1002", "1003"]
    greeting-recording: all-staff-greeting

recordings:
  all-staff-greeting:
    recording-source: https://recordings.example.com/all-staff.wav

Callers hear the configured greeting-recording (required — a distribution box has no subscriber to record one) and leave one message; each member receives their own copy in their inbox, and each member manages their copy independently.
Distribution boxes have no PIN and cannot be opened through any access menu — they are a delivery mechanism, not a mailbox.
Members must be regular boxes in this namespace: no nesting a list in a list, and a list cannot include itself.
The greeting is config-owned: it is re-applied from greeting-recording on every config apply (unlike subscriber-recorded greetings, which are never touched by an apply).

Lifecycle across config applies

Applying configuration never clobbers subscriber state:

New box → created empty, no PIN, preferences seeded from the context.
Existing box → PIN, recorded greetings, messages, and preferences are untouched, whatever else changed in the config. (The one exception is the distribution-list static greeting, re-stamped as above.)
Removed box → governed by the namespace-level configuration: key cleanup-mailboxes. It defaults to "true": removing a box from the config deletes its messages and greetings on apply. Set cleanup-mailboxes: "false" to retain removed boxes’ contents as orphans instead — recoverable, re-homeable into an active box, or purged explicitly through the management API (covered in the voicemail administration guide).

Validation summary

context is required and must exist.
Digit-only names must match the context’s box-id-length.
Distribution lists require greeting-recording (which must exist in recordings:); members must exist, not be lists, and not include the list itself.
A line’s voicemail may not reference a distribution list.