Executive-assistant call delegation

Executive-assistant delegation is the boss/admin pattern: an executive registers assistants as delegates and shares control of their inbound calls. The executive always owns the call; the delegates answer, screen, transfer, place on the executive’s behalf, or monitor the executive’s line, depending on the actions each one is granted. This page walks the whole lifecycle — from designing the delegation policy, through testing the ring path, to rotating the roster and auditing who delegates to whom. Delegation on Orbit is self-service: the executive saves their own policy (on the /me/voice-preferences page or over the API under GET/PUT/DELETE /api/v1/voice/delegation/policy), so an offboarding assistant is cut off the same day, without a supervisor ticket. The policy lives on the executive’s own user record, so the same controls that gate your other per-user preferences gate it.

1. The delegation model

A delegation policy is owned by exactly one executive and grants one or more assistants (delegates) a subset of on-behalf actions:

screen — answer first, announce the caller, then extend (or decline) to the executive. The classic assistant screen.
answer — answer calls on the executive’s behalf outright.
place — place outbound calls as the executive (the executive’s line is the caller id).
transfer — move the executive’s live calls (blind or attended).
monitor — watch the executive’s live-call state as an actionable surface, not just a read-only busy lamp.

The executive inherently holds answer, place, and transfer on their own line. Every delegated action is an explicit grant — a delegate performs only the actions their grant lists.

How this differs from SLA, ring groups, and per-line preferences

Delegation is an owner-grants-delegate relationship: one owner, one policy, explicit per-delegate action scopes. It is not a queue (no FIFO hold), not a shared line, and not the generic “delegate to a teammate” coverage arrow in the /me/voice-preferences ladder.

Shared Line Appearance (SLA) mirrors one named line onto a roster of devices — members ring, watch a busy lamp, and grab the answered call. A delegation across the whole tenant is still a delegation; getting the executive’s number to ring on devices is SLA’s job, and the two stack naturally.
Ring groups / queues answer “ring these devices” with no ownership and no per-user action scoping.
/me/voice-preferences covers per-user rules — delegation is one of the panels there; this page covers the tenant-wide workflow around it.

2. Identify the delegation scope per relationship

Decide, per executive–assistant pair, which actions the delegate needs — the policy accepts only what it names, so scoping down is enforcement, not documentation.

Full call-handling scope — the delegate holds every action (screen, answer, place, transfer) and behaves as a full assistant.
Answer-only — grant answer (optionally with monitor); the delegate takes calls but can’t move them or place new ones as the executive.
Screen-only — grant screen; the delegate answers, announces, and extends, but can’t transfer elsewhere or place outbound.
Transfer-only — grant transfer; the delegate moves live calls but can’t pick them up first. A delegate with no grant is denied — the per-leg check is authoritative, so a scoped delegate is genuinely scoped.

Max 10 delegates per executive, and every delegate must be an active user in the executive’s own organization (a rejected save names the unknown ids).

3. Register a delegate

Build the client picker (or the boss-admin editor) from GET /api/v1/voice/delegation/capabilities — it returns the action kinds, ring modes, and bounds (max delegates, screen-timeout and ring-priority ranges). It is static and cacheable. Preview before saving: POST /api/v1/voice/delegation/plan validates a policy and returns the resolved plan (ordered ring stages, per-leg permitted actions, shared-ownership decision) without persisting anything. Once the plan reads the way you want, persist it:

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/delegation/policy" \
  -H "Authorization: Bearer <session token>" \
  -H "Content-Type: application/json" \
  -d '{
    "executive_user_id": "user_exec_sara_kim",
    "ring_mode": "screen_first",
    "screen_timeout_sec": 20,
    "grants": [
      {
        "assistant_user_id": "user_dana_chen",
        "assistant_label": "Dana (assistant pool)",
        "actions": ["screen", "transfer"],
        "ring_priority": 0
      },
      {
        "assistant_user_id": "user_marc_hill",
        "assistant_label": "Marc (assistant pool)",
        "actions": ["screen", "transfer"],
        "ring_priority": 10
      }
    ]
  }'

The response returns the stored policy plus its resolved plan. Rules enforced at save time:

executive_user_id must be the authenticated user (else 403). This guide uses a sandbox dv_test_sk_* header form for server-to-server reads, but the save must be the executive’s own session identity.
Every assistant_user_id must be an active user in your organization (else 422 naming the unknown ids).
screen_first needs at least one delegate granted the screen action (else 400/422).
An executive cannot be their own delegate; duplicate delegates and duplicate actions are rejected.

The policy materializes on the executive’s user record immediately — there is no separate certificate object to fetch. GET /api/v1/voice/delegation/policy returns { policy, plan } or { policy: null, plan: null }.

4. Test the ringing path

Call the executive’s DID (or dial their extension internally) and watch against the resolved plan:

screen_first — stage 0 rings the delegates (kind: "screen"); on no answer within screen_timeout_sec it rolls to the executive (stage 0 → stage 1). Verify the assistant’s softphone rings first and the executive’s device rings only if no delegate answers.
simul_ring — executive plus every delegate ring together; first answer takes it. Verify all devices light at once.
assistant_first — delegates are the primary answer point; roll to the executive on no answer.
exec_first — executive rings first, delegates are the no-answer backup.

In every mode, compare what you observe against stages[].kind and stages[].participants[] in the saved plan — the plan is the exact alert ladder. Tune screen_timeout_sec between 5 and 120 seconds (default 20); ring_priority orders delegates within a stage (lower rings earlier, ties break on the user id).

5. Hand-to-exec flow

With shared_ownership enabled (the default), whichever delegate answers shares ownership of the call with the executive — the delegate screens, announces the caller, then extends it to the executive; the caller experiences a bridged live handoff, not a cold transfer with a new ring. Either party can then transfer or end the call. Disable shared_ownership and the answering delegate holds the leg until they explicitly extend it — a tighter screen, but a longer stay for the caller. Against a plain /api/v1/voice/calls/:id/transfer, the difference is the relationships: the plane consults the executive’s saved delegation plan on the inbound call, so a delegate extends to their own executive without a lookup, while a plain transfer targets any destination with no delegation context.

6. Delegate lifecycle

Rotation is a full-policy replace, not an append: PUT /api/v1/voice/delegation/policy overwrites the grants list — re-PUT the desired roster each time. Deregister one delegate by re-saving without them; revoke everything with DELETE /api/v1/voice/delegation/policy ({ deleted: true } when a policy existed). Audit who delegates to whom by reading each executive’s GET /policy on rotation day and capturing { policy, plan } — the current grants and resolved stage ladder in one payload. Every save, revoke, or re-grant is written to the tenant audit log with actor, timestamp, and the policy payload’s before/after diff, so a roster dispute is answered in the log, not in email (see the audit log guide). On a role change — for instance when an assistant leaves the pool — revoke their grant the same day; the self-scoped policy means the executive can do it without waiting on an admin.

7. Relationship to shared lines

Shared Line Appearance handles the per-line-attention model: a roster of devices sharing a line’s identity, with a busy lamp and a grab action. Delegation (this page) covers the executive-assistant workflow across the whole tenant: who the executive’s delegates are, what actions each may take, and the assistant-to-executive handoff. Use them together — SLA for the shared line, delegation for the on-behalf relationship. Related sibling surfaces: the /me/voice-preferences ladder’s per-user coverage arrow is narrower (roll-to-one-teammate; see Self-service calling rules), and inbound DID routing is where the executive’s number is pointed at the right surface.

8. Worked example: a law firm’s assistant pool

A firm with 40 partners keeps a shared assistant pool. Partner Sara Kim delegates to pool members Dana and Marc, screen-first, as in section 3. Dana screens, sees the caller is a client Sara will take, and extends — Sara’s phone rings with the call already announced. Friday rotation: the firm’s rotation script re-PUTs each partner’s policy with the next week’s pool roster — a put, not an append, so Friday’s save replaces Thursday’s delegates. ring_priority keeps the pool deterministic: Dana at 0, Marc at 10, and the pool lead can be bumped to ring earlier for busy partners. An assistant leaving the pool drops out of every pool policy at the next rotation; a partner can also revoke individually the same day. The Friday script captures each partner’s GET /policy payload, so the firm holds an audit snapshot of who delegates to whom for each rotation week.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

1. The delegation model

How this differs from SLA, ring groups, and per-line preferences

2. Identify the delegation scope per relationship

3. Register a delegate

4. Test the ringing path

5. Hand-to-exec flow

6. Delegate lifecycle

7. Relationship to shared lines

8. Worked example: a law firm’s assistant pool

​1. The delegation model

​How this differs from SLA, ring groups, and per-line preferences

​2. Identify the delegation scope per relationship

​3. Register a delegate

​4. Test the ringing path

​5. Hand-to-exec flow

​6. Delegate lifecycle

​7. Relationship to shared lines

​8. Worked example: a law firm’s assistant pool

1. The delegation model

How this differs from SLA, ring groups, and per-line preferences

2. Identify the delegation scope per relationship

3. Register a delegate

4. Test the ringing path

5. Hand-to-exec flow

6. Delegate lifecycle

7. Relationship to shared lines

8. Worked example: a law firm’s assistant pool