Executive-assistant call delegation

{
  "data": {
    "actions": ["screen", "answer", "place", "transfer", "monitor"],
    "ring_modes": ["screen_first", "simul_ring", "assistant_first", "exec_first"],
    "default_ring_mode": "screen_first",
    "max_delegates": 10,
    "min_screen_timeout_sec": 5,
    "max_screen_timeout_sec": 120,
    "default_screen_timeout_sec": 20,
    "min_ring_priority": 0,
    "max_ring_priority": 99
  },
  "meta": {
    "request_id": "req_5c1e8a2b4d6f4e8a",
    "timestamp": "2026-10-28T09:00:00Z"
  }
}

{
  "data": {
    "actions": ["screen", "answer", "place", "transfer", "monitor"],
    "ring_modes": ["screen_first", "simul_ring", "assistant_first", "exec_first"],
    "default_ring_mode": "screen_first",
    "max_delegates": 10,
    "min_screen_timeout_sec": 5,
    "max_screen_timeout_sec": 120,
    "default_screen_timeout_sec": 20,
    "min_ring_priority": 0,
    "max_ring_priority": 99
  },
  "meta": {
    "request_id": "req_5c1e8a2b4d6f4e8a",
    "timestamp": "2026-10-28T09:00:00Z"
  }
}

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 roll-over 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. The samples in this section come in two forms: cURL, and Node.js. They also name their auth header on purpose, because the two forms are not interchangeable here. Reads — GET /api/v1/voice/delegation/capabilities and GET /api/v1/voice/delegation/policy — accept a server-to-server key (X-API-Key: dv_test_sk_* in sandbox). Preview, save, and clear act on one executive’s record and must carry that executive’s own session token (Authorization: Bearer); a key, or anyone else’s session, fails with 403 the moment executive_user_id differs from the authenticated user. The Node SDK (@devotel-orbit/node) authenticates as the key owner on every request, so it fits the reads; for the executive-session calls, the Node samples send the session header directly.

Read the bounds

curl "https://api.orbit.devotel.io/api/v1/voice/delegation/capabilities" \
  -H "X-API-Key: dv_test_sk_your_sandbox_key"

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! })

// Server-to-server read: the SDK's X-API-Key auth is the right form here.
const caps = await orbit.request('GET', '/voice/delegation/capabilities')
console.log(caps.data.max_delegates)                      // 10
console.log(caps.data.min_ring_priority, caps.data.max_ring_priority) // 0 99

{
  "data": {
    "actions": ["screen", "answer", "place", "transfer", "monitor"],
    "ring_modes": ["screen_first", "simul_ring", "assistant_first", "exec_first"],
    "default_ring_mode": "screen_first",
    "max_delegates": 10,
    "min_screen_timeout_sec": 5,
    "max_screen_timeout_sec": 120,
    "default_screen_timeout_sec": 20,
    "min_ring_priority": 0,
    "max_ring_priority": 99
  },
  "meta": {
    "request_id": "req_5c1e8a2b4d6f4e8a",
    "timestamp": "2026-10-28T09:00:00Z"
  }
}

Build the picker from this payload, not from hard-coded constants: max_delegates caps assistants at 10, screen_timeout_sec accepts 5–120 (default 20), and ring_priority accepts 0–99 with lower ringing earlier.

Preview the plan before saving

POST /api/v1/voice/delegation/plan validates the exact body PUT accepts and returns the resolved plan (ordered ring stages, per-leg permitted actions, shared-ownership decision) without persisting anything. This is the call the dashboard delegation editor makes while you type.

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/delegation/plan" \
  -H "Authorization: Bearer <executive 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
      }
    ]
  }'

// Executive-session call: send the session header yourself.
const policy = {
  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 },
  ],
}

const preview = await fetch('https://api.orbit.devotel.io/api/v1/voice/delegation/plan', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EXECUTIVE_SESSION_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(policy),
})
const { data: plan } = await preview.json()
console.log(plan.stages.map((s) => s.kind)) // [ 'screen', 'alert' ]

The preview resolves that body into the exact alert ladder the executive’s inbound calls will follow:

{
  "data": {
    "owner_user_id": "user_exec_sara_kim",
    "ring_mode": "screen_first",
    "screen_timeout_sec": 20,
    "shared_ownership": true,
    "stages": [
      {
        "order": 0,
        "kind": "screen",
        "participants": [
          { "user_id": "user_dana_chen", "label": "Dana (assistant pool)", "is_executive": false, "actions": ["screen", "transfer"], "is_screening": true },
          { "user_id": "user_marc_hill", "label": "Marc (assistant pool)", "is_executive": false, "actions": ["screen", "transfer"], "is_screening": true }
        ]
      },
      {
        "order": 1,
        "kind": "alert",
        "participants": [
          { "user_id": "user_exec_sara_kim", "label": null, "is_executive": true, "actions": ["answer", "place", "transfer"], "is_screening": false }
        ]
      }
    ]
  },
  "meta": {
    "request_id": "req_9b3d7e1f5a2c4d80",
    "timestamp": "2026-10-28T09:05:00Z"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "ring_mode screen_first requires at least one grant with the screen action",
    "status": 422
  },
  "meta": {
    "request_id": "req_2a8c4e6d1b3f5970",
    "timestamp": "2026-10-28T09:06:00Z"
  }
}

Stage 0 (kind: "screen") rings the delegates granted screen, ordered by ring_priority (Dana at 0 before Marc at 10); stage 1 (kind: "alert") rings the executive when nobody screens in time. simul_ring puts everyone in one stage; assistant_first and exec_first swap the stage order. Section 5 tests the live ring path against these same stages[].kind and stages[].participants fields. A 422 names what the save would reject — as above, a screen_first draft where no delegate holds screen — so preview, fix the draft, re-preview.

Save the policy

Once the plan reads the way you want, persist it with the same body. The save must be the executive’s own session:

curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/delegation/policy" \
  -H "Authorization: Bearer <executive 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
      }
    ]
  }'

const saved = await fetch('https://api.orbit.devotel.io/api/v1/voice/delegation/policy', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.EXECUTIVE_SESSION_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(policy), // same body as the preview above
})
const { data } = await saved.json()
console.log(data.plan.stages.map((s) => s.kind)) // [ 'screen', 'alert' ]

The response returns the stored policy plus its resolved plan:

{
  "data": {
    "policy": {
      "executive_user_id": "user_exec_sara_kim",
      "ring_mode": "screen_first",
      "screen_timeout_sec": 20,
      "shared_ownership": true,
      "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 }
      ]
    },
    "plan": {
      "owner_user_id": "user_exec_sara_kim",
      "ring_mode": "screen_first",
      "screen_timeout_sec": 20,
      "shared_ownership": true,
      "stages": [
        {
          "order": 0,
          "kind": "screen",
          "participants": [
            { "user_id": "user_dana_chen", "label": "Dana (assistant pool)", "is_executive": false, "actions": ["screen", "transfer"], "is_screening": true },
            { "user_id": "user_marc_hill", "label": "Marc (assistant pool)", "is_executive": false, "actions": ["screen", "transfer"], "is_screening": true }
          ]
        },
        {
          "order": 1,
          "kind": "alert",
          "participants": [
            { "user_id": "user_exec_sara_kim", "label": null, "is_executive": true, "actions": ["answer", "place", "transfer"], "is_screening": false }
          ]
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_6e2f9a3c7b1d4580",
    "timestamp": "2026-10-28T09:10:00Z"
  }
}

Rules enforced at save time:

executive_user_id must be the authenticated user (else 403) — this is why every write sample above carries the executive’s session, while the reads may use the sandbox dv_test_sk_* key form.
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 (a read, so a key is fine) returns { policy, plan } or { policy: null, plan: null }.

Revoke the policy

Offboarding and same-day revocation use DELETE /api/v1/voice/delegation/policy, again as the executive:

curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/delegation/policy" \
  -H "Authorization: Bearer <executive session token>"

const gone = await fetch('https://api.orbit.devotel.io/api/v1/voice/delegation/policy', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.EXECUTIVE_SESSION_TOKEN}` },
})
console.log((await gone.json()).data.deleted) // true when a policy existed

{
  "data": { "deleted": true },
  "meta": {
    "request_id": "req_4d7b2e9a6c3f1850",
    "timestamp": "2026-10-28T17:45:00Z"
  }
}

Revocation is immediate: the grants stop applying on the executive’s next inbound call, which reverts to their normal routing. deleted is false when there was nothing to remove. Rotation is a full-policy replace, not an append. The firm’s Friday script in section 9 re-PUTs each partner’s roster; to bump Marc ahead of Dana for a busy week, re-save the same roster with the priorities swapped:

curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/delegation/policy" \
  -H "Authorization: Bearer <executive 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_marc_hill",
        "assistant_label": "Marc (assistant pool)",
        "actions": ["screen", "transfer"],
        "ring_priority": 0
      },
      {
        "assistant_user_id": "user_dana_chen",
        "assistant_label": "Dana (assistant pool)",
        "actions": ["screen", "transfer"],
        "ring_priority": 10
      }
    ]
  }'

const rotated = await fetch('https://api.orbit.devotel.io/api/v1/voice/delegation/policy', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.EXECUTIVE_SESSION_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ...policy,
    grants: [
      { ...policy.grants[1], ring_priority: 0 }, // Marc rings first this week
      { ...policy.grants[0], ring_priority: 10 },
    ],
  }),
})
console.log((await rotated.json()).data.policy.grants.map((g) => [g.assistant_user_id, g.ring_priority]))

The re-PUT returns the same { policy, plan } shape as the save above; capture it as the week’s audit snapshot, exactly as the Friday script does.

4. Console walkthrough: the delegation editor

Everything above also works from the dashboard. The Call delegation (boss-admin) card on Me → Voice preferences (/me/voice-preferences) edits and saves the exact same policy the cURL examples persist with PUT /api/v1/voice/delegation/policy — the console and the API are two paths to the same routes, so a policy saved in either place loads in the other.

The card appears on every signed-in user’s own Voice preferences page, but the policy it saves is the boss/admin model from this guide: one executive who owns the calls, and assistants granted on-behalf actions.

Open the card. On /me/voice-preferences, scroll to the Call delegation (boss-admin) card. It loads your saved policy if one exists, otherwise it opens on a blank draft with the default ring mode and one empty assistant row. The badge in the card header reads Saved when a policy is persisted on your user record and Not saved while the form holds only a draft.
Set the executive. Enter the executive’s user ID in the Executive field. The policy is self-scoped: saving it as anyone other than the authenticated user is rejected with 403, so in practice you enter your own id (the API section above covers this rule in full).
Add assistants. Each assistant row takes a user ID, an optional label, and a ring priority; Add assistant appends rows up to your organization’s delegate limit (10), and it disables at the cap. Every assistant must be an active user in your own organization — a save that names unknown or inactive ids fails with 422 and lists them. Start with one assistant; a policy with no complete assistant row can’t be previewed or saved.
Grant actions per assistant. Tick any of Screen, Answer, Place on behalf, Transfer, Monitor — the same five grants the API accepts, with the same meaning as section 1: an assistant performs only the actions you tick.
Choose the ring distribution. The dropdown offers the four modes from section 5: screen first (assistant announces, then extends), simul-ring (executive and assistants together), assistant first (rolls to the executive on no-answer), executive first (rolls to the assistants on no-answer). Screen first requires at least one assistant with the Screen grant — without one the save fails validation. The Screen / alert window field sets screen_timeout_sec (5–120 seconds, default 20), and Shared ownership mirrors the hand-to-exec behavior in section 6.
Read the live preview before saving. As you edit, the card resolves your draft with POST /api/v1/voice/delegation/plan and renders the result as ordered stages: each stage lists its participants, their role (executive or assistant, screening or not), and the actions permitted on that leg, plus the owner, ring mode, shared/exclusive ownership, and timeout. If the draft is invalid, the preview area shows the validation error instead. Compare the ladder against what you intend before you save.
Save or clear. Save policy (or Save changes once saved) persists with PUT /api/v1/voice/delegation/policy; a failed save reports the validation error in a toast and leaves your draft intact. Clear policy asks for confirmation, then removes the stored policy (DELETE /api/v1/voice/delegation/policy) and resets the form to the defaults — after clearing, the executive’s inbound calls revert to their normal routing. If the card cannot load a saved policy, it shows a distinct error state with a Retry button instead of opening an editable blank form over a policy it could not read.
Clear on offboarding. When an assistant leaves the organization, remove their row and save, or use Clear policy when the whole arrangement ends. Clearing is immediate: the assistant’s grants stop applying on the executive’s next inbound call, with no admin ticket — the same-day revocation section 7 describes.

5. 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).

6. 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.

7. 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.

8. 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 roll-over 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.

9. 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

Developer console

Contact center

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

Read the bounds

Preview the plan before saving

Save the policy

Revoke the policy

4. Console walkthrough: the delegation editor

5. Test the ringing path

6. Hand-to-exec flow

7. Delegate lifecycle

8. Relationship to shared lines

9. 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

​Read the bounds

​Preview the plan before saving

​Save the policy

​Revoke the policy

​4. Console walkthrough: the delegation editor

​5. Test the ringing path

​6. Hand-to-exec flow

​7. Delegate lifecycle

​8. Relationship to shared lines

​9. 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

Read the bounds

Preview the plan before saving

Save the policy

Revoke the policy

4. Console walkthrough: the delegation editor

5. Test the ringing path

6. Hand-to-exec flow

7. Delegate lifecycle

8. Relationship to shared lines

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