Line Feature Management

This page covers the runtime feature state of subscriber lines: the DND flags, forward targets, and speed-dial tables that subscribers (or your portal / support staff acting for them) change day to day. The config side — declaring lines, binding devices, and granting feature entitlements — is covered in Lines and Line Profiles.

Conventions as usual: $VSS, $TOKEN, $NSID for curl; an active vsscli profile with a namespace set. Line commands live under the realtime tree — vsscli realtime line …, short form vsscli rt line ….

The model — entitlement vs. state

Two layers cooperate on every feature:

	Entitlement	State
Where	The line profile’s calling-features list (config)	Per-line rows managed by this API
Question answered	May this line use DND / CFA / CFB / CFNA?	Is DND on? Where does busy-forward point?
Changed by	Config version + apply	The endpoints on this page
Survives a config apply	n/a	Yes — applies never touch feature state (it is purged only when the line itself is removed)

Entitlement is enforced on both fronts (details): the API refuses to enable a feature the profile doesn’t grant (403), and at call time stored state for a revoked feature is ignored. Disabling or clearing anything is always permitted — you can always turn things off.

Feature reads at call time are cached for about 5 seconds per media node, so a flip is near-real-time but not instantaneous — don’t expect the very next call to see it.

Permissions

Action	Covers	Held by
line:read	Line list, single-line view, speed-dial list	partition-admin, namespace-admin, provisioner, operator, editor, viewer, system-auditor, line-owner (own line)
line:write	Every mutation on this page	The same, minus viewer and system-auditor

line-owner is the single-line self-service role — see self-service line owners below.

Inspecting lines

curl

# Every line in the running config with its feature state
curl -s "$VSS/v1/ns/$NSID/lines" -H "Authorization: Bearer $TOKEN"

# One line
curl -s "$VSS/v1/ns/$NSID/lines/1001" -H "Authorization: Bearer $TOKEN"
# → {"success":true,"line":"1001","dnd":false,
#    "cf_always":"","cf_busy":"","cf_no_answer":"+13055551234",
#    "cf_no_answer_sec":20,"block_cid":false,
#    "speed_dials":{"22":"+13055559876"}}

vsscli

vsscli rt line list
vsscli rt line show 1001

The listing covers every configured line, not just those with feature state — untouched lines appear with all-off defaults, so the list doubles as a feature audit. A line that isn’t in the running config answers 404 everywhere on this page (feature state can never be attached to a line that doesn’t exist yet).

Do-not-disturb

curl

curl -s -X PUT "$VSS/v1/ns/$NSID/lines/1001/dnd" \
  -H "Authorization: Bearer $TOKEN" -d '{"enabled":true}'

vsscli

vsscli rt line dnd 1001 on
vsscli rt line dnd 1001 off

With DND on, calls to the line never ring its devices — they go straight to the line’s no-answer handling: voicemail when the line has a mailbox (and the profile grants the voicemail feature), the failure treatment otherwise. Two different caller experiences from the same flag — worth remembering when a subscriber reports “callers say I’m unreachable”.

Enabling requires the dnd entitlement (403 without it); disabling never does.

Call forwarding

Three independent forward variants, addressed by {kind}:

Kind	Fires when	Entitlement
always	Every call, before anything rings	cfa
busy	The line is busy (or a device rejects)	cfb
no-answer	Nothing answered within the ring timeout	cfna

curl

# Set (ring_seconds only meaningful for no-answer; 0 = profile default)
curl -s -X PUT "$VSS/v1/ns/$NSID/lines/1001/forward/no-answer" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"target":"+13055551234","ring_seconds":20}'

# Clear
curl -s -X DELETE "$VSS/v1/ns/$NSID/lines/1001/forward/no-answer" \
  -H "Authorization: Bearer $TOKEN"

vsscli

vsscli rt line forward set 1001 no-answer +13055551234 --ring-seconds 20
vsscli rt line forward clear 1001 no-answer

• ring_seconds (no-answer only): how long the devices ring before the forward fires. 0 means the profile’s max-ring-time (default 25 s); a non-zero value must be 5–120 or the request is a 400.
• A target equal to the line itself is refused (400) — the immediate forward loop is the only loop checked at write time; longer chains are broken at call time.
• The target can be anything the line itself could dial — an extension, a ring group, an external number.

A forward is a new call placed by the line

When a forward fires, the switch re-originates from the forwarding line: the target is dialed through the line’s own translation context, the original caller’s ID is presented (not the forwarding line’s), a Diversion header records the forwarding party, and — deliberately — the target is checked against the line’s toll screening. A toll-restricted line therefore cannot be forwarded to long distance: the forward set call succeeds, but forwarded calls get the toll-denied treatment. This is a fraud guard, not a bug.

Blocking caller ID

curl

curl -s -X PUT "$VSS/v1/ns/$NSID/lines/1001/block-cid" \
  -H "Authorization: Bearer $TOKEN" -d '{"enabled":true}'

vsscli

vsscli rt line block-cid 1001 on

With block-CID on, the line’s outbound calls go out anonymous — the From identity is replaced with Anonymous and a Privacy: id header asks downstream carriers to withhold the real identity (which still travels in P-Asserted-Identity for the network’s own use, per standard SIP privacy practice). Block-CID is not in the calling-features list and needs no entitlement.

Speed dials

A speed dial maps a short code to a full number, per line:

curl

curl -s "$VSS/v1/ns/$NSID/lines/1001/speed-dials" -H "Authorization: Bearer $TOKEN"

curl -s -X PUT "$VSS/v1/ns/$NSID/lines/1001/speed-dials/22" \
  -H "Authorization: Bearer $TOKEN" -d '{"number":"+13055559876"}'

curl -s -X DELETE "$VSS/v1/ns/$NSID/lines/1001/speed-dials/22" \
  -H "Authorization: Bearer $TOKEN"

vsscli

vsscli rt line speed-dial list 1001
vsscli rt line speed-dial set 1001 22 +13055559876
vsscli rt line speed-dial delete 1001 22

How the code is matched at dial time, in order:

1. Special numbers win. Emergency/special numbers (911 …) are matched before speed dials — a speed-dial code can never shadow them.
2. Feature codes win. *98 and friends are also matched first.
3. Then the dialed string is compared against the line’s speed-dial codes — an exact match on the whole dialed string, not a prefix.
4. The mapped number then goes through the normal translation walk and toll screening as if the subscriber had dialed it — a speed dial is a typing shortcut, not a screening bypass.

Codes and numbers are free-form (no whitespace); deleting an absent code succeeds silently. Keep codes short and outside your extension plan — a code that collides with a real extension hides that extension from this line (the speed-dial match runs before translations).

Setting several features at once

PUT /lines/{line}/opts is a merge-patch over the scalar features — useful for portals saving a settings page in one call. A key that is absent is untouched; a present key is applied (blank string clears a forward; false turns a toggle off). Speed dials are deliberately not part of it — they have their own endpoints above.

curl

curl -s -X PUT "$VSS/v1/ns/$NSID/lines/1001/opts" \
  -H "Authorization: Bearer $TOKEN" -d '{
    "dnd": false,
    "cf_always": "",
    "cf_no_answer": "+13055551234",
    "cf_no_answer_sec": 20,
    "block_cid": true
  }'

vsscli

vsscli rt line set 1001 --dnd=false --clear-cf-always \
  --cf-no-answer +13055551234 --ring-seconds 20 --block-cid=true

Booleans take an explicit value (--dnd=false); strings pair with a --clear-* twin.

The patch is all-or-nothing: every entitlement it needs is checked up front, so a patch that enables one permitted and one forbidden feature applies neither (403, nothing written).

Resetting a line

Purge every feature row — DND, all forwards, block-CID, and the whole speed-dial table — in one call. This is what offboarding a subscriber looks like on the feature side (the same purge happens automatically when the line itself is removed — by a config apply in document mode, or a managed /resources delete):

curl

curl -s -X DELETE "$VSS/v1/ns/$NSID/lines/1001" -H "Authorization: Bearer $TOKEN"

vsscli

vsscli rt line clear 1001      # prompts; --yes to skip

Note the URL: DELETE on the line-features resource clears feature state. It does not — cannot — remove the line from the config.

Self-service line owners

Like mailboxes, a single line can be handed to its subscriber with a resource-scoped line-owner grant:

vsscli user grant add <sub-user-id> --role line-owner \
  --scope "resource:$NSID!line!1001"

The owner can read and manage every feature on this page for their own line only. The namespace-wide line listing stays out of reach — it carries no concrete line, so the resource grant never applies to it. The pattern (and the helpdesk role built to support such accounts) is worked through in user administration.

Troubleshooting

Response	Meaning	Do
404 line not found	The line isn’t in the running config	Check spelling; if just added to config, apply first
403 feature not entitled	The line’s profile doesn’t grant the feature you’re enabling	Add the flag to the profile’s calling-features and apply, or use a different profile
400 ring seconds out of range	Non-zero ring_seconds outside 5–120	Use 5–120, or 0 for the profile default
400 forward loop	Target equals the line itself	Pick a real target
400 invalid speed dial	Blank code/number or embedded whitespace	Fix the values
Feature flip “not working”	Call-time cache	Wait ~5 s and place a fresh call
Forwarded calls toll-denied	The line’s screening context rejects the forward target	Intentional fraud guard — widen the line’s screening context if the destination is legitimate