Voicemail Contexts

A voicemail context is a named policy bundle. Every voicemail box references exactly one context, and the context decides how all of its boxes behave: how long messages can be, how many fit, what plays when there’s no custom greeting, where “press 0” goes, and the security rules around PINs and call-return. Define one context per service class — standard, executive, hospitality — rather than per box.

voicemail-contexts:
  standard:
    timezone-default: America/New_York
    box-quota: 40
    box-id-length: 4
    max-message-seconds: 180
    min-message-seconds: 2
    max-silence-seconds: 6
    max-recording-attempts: 3
    min-pin-length: 4
    mailbox-full-policy: reject
    default-greetings:
      default: generic-greeting
      busy: generic-busy-greeting
    operator:
      resource-type: ring-group
      resource-id: front-desk

Field reference

Field	Default	Meaning
`timezone-default`	UTC	IANA timezone used when speaking message timestamps (the envelope). Set it — envelope times in UTC confuse subscribers.
`locale`	—	Accepted for forward compatibility; prompt language selection is not active in this release.
`default-greetings.default` / `.busy`	silence	Recordings (keys in `recordings:`) played to callers when a box has no custom greeting of that kind.
`operator`	none	Where a caller lands when they press `0` during a greeting (below).
`box-quota`	40	Maximum stored messages per box.
`mailbox-full-policy`	`reject`	What happens to a new message when a box is at quota (below).
`max-message-seconds`	180	Recording length cap.
`min-message-seconds`	2	Recordings shorter than this are discarded with a “too short” prompt — filters pocket-dials and hang-ups.
`max-silence-seconds`	6	Trailing silence that ends a recording.
`max-recording-attempts`	3	How many takes the review menu’s re-record option allows; at the cap the current take is saved rather than lost.
`box-id-length`	4	Length of digit-only box names (below).
`min-pin-length`	4	Minimum digits for a subscriber-set PIN.
`envelope-autoplay-default`	off	Default for the per-box envelope-autoplay preference: when on, each message a subscriber listens to is preceded by its spoken envelope (received time and caller). Subscribers toggle it per box in the options menu.
`enable-send-forward`	off	Enables the box-to-box messaging features: composing a new message from the main menu and forwarding a received message from the message menu.
`outbound-translation-context`	—	Translation context used by message callback (below).
`allow-callback-from-external`	off	Permits callback from PIN-authenticated external (PSTN) sessions (below).

The operator escape

operator names the destination for callers who press 0 while a greeting is playing — the classic “press zero for the front desk”. Valid target types: line, ring-group, voicemail-box, treatment, application, route. With no operator configured, 0 simply skips ahead to recording.

Mailbox-full behavior

At quota, mailbox-full-policy decides:

reject (default) — the caller hears the mailbox-full announcement and no message is taken.
overwrite-oldest — the oldest already-heard message is discarded to make room (falling back to the oldest unheard when nothing has been heard), and the new message is taken. Choose this for boxes that are checked rarely but must never refuse a caller.

Box numbering: `box-id-length`

Digit-only box names in this context must be exactly this many digits — the validator enforces it. The length is what lets the dial-in access menu parse {box} and {box}{pin} after a feature code, and what the in-menu forward/compose flows use when collecting a destination box number. Alphanumeric box names are allowed (e.g. distribution lists like all-staff) but can’t be dialed from the menus.

Message callback policy

The message menu lets a subscriber return a call to the number that left a message. Two context fields govern it:

outbound-translation-context — the translation context the stored caller-ID is walked through to place the return call. When empty, the callback uses the dialing line’s own outbound context — which only exists when the session came from an internal line.
allow-callback-from-external — by default, sessions reached from an external (PSTN) caller — someone who dialed in and entered a PIN — may not use callback. This is a deliberate toll-fraud guard: with weak PINs, an attacker could leave a message from a spoofed premium-rate caller-ID, dial in, and have your switch call it back. Enabling it requires an explicit outbound-translation-context (the validator rejects the combination without one), and that context should be written restrictively — domestic-only is a sensible ceiling.

Validation summary

operator, default-greetings.*, and outbound-translation-context must reference resources that exist.
mailbox-full-policy must be reject or overwrite-oldest (empty = reject).
Numeric knobs must be non-negative; min-message-seconds may not exceed max-message-seconds.
allow-callback-from-external requires outbound-translation-context.

Worked contexts

voicemail-contexts:
  # Everyday business voicemail.
  standard:
    timezone-default: America/New_York
    box-quota: 40
    box-id-length: 4
    mailbox-full-policy: reject
    enable-send-forward: true
    default-greetings:
      default: company-generic
    operator:
      resource-type: ring-group
      resource-id: front-desk

  # Hospitality: guests never manage boxes; housekeeping-style reset via
  # admin API; callers must always be able to leave a message.
  guestroom:
    timezone-default: America/New_York
    box-quota: 10
    box-id-length: 4
    max-message-seconds: 120
    mailbox-full-policy: overwrite-oldest
    default-greetings:
      default: guest-generic
    operator:
      resource-type: line
      resource-id: "0"        # front desk line