/handoff-router-configuration

--- name: handoff-router-configuration description: Creates, reads, updates, and deletes Chili Piper Handoff routers — the rep-to-rep handoff routing configurations that decide who receives a handoff and which meeting type gets booked. Always-live writes with dry-run diffs, representability checks, and delete confirmation. version: 0.1.7 references:

• api-reference
• write-procedures
• output-format

inputs:

• name: workspace

type: string description: "Workspace name or ID containing the router." required: true

• name: action

type: string description: "One of: list, get, create, update, delete." required: true

• name: router

type: string description: "Router name (substring) or router ID. Required for get/update/delete." required: false

• name: changes

type: string description: "Desired state for create/update in plain language (e.g. 'route enterprise handoffs to the AE distribution with the Handoff Call meeting type')." required: false

• name: dry_run

type: boolean description: "If true, show what would be done without making any changes. Always recommended before first run." required: false default: true outputs:

• name: plan

description: Dry-run diff — routing rows rendered as rule → assignment + meeting type, and every object that would change

• name: result

description: Applied changes with post-write verification (only when dry_run=false)

• name: audit_trail

description: Which tool calls were made, on which IDs, with before/after values tools_required: [chili-piper-mcp] human_decision_point: "Review the dry-run plan before any write — Handoff routers are ALWAYS-LIVE: create and update publish immediately with no inactive staging state, so the plan is the only preview. Confirm delete separately; it is irreversible." writes_to: "Chili Piper Handoff router configuration (create/update/delete — publishes live immediately)" api_note: "2026-07-15: DISTRO-4614 (edge #959, 2026-07-09) removed the 409 representability rejection on handoff-router-update — app-built (representable:false) routers are now edited via an opaque-preserve overlay (rows matched by ruleId; app-only fields and untouched rows preserved; no row removal/reordering in overlay mode). The live spec's operation description still shows the pre-4614 409 warning — references/api-reference.md is the truth. Handoff writes are Schedule-only (no Redirect/timeout; ConvertLead is the only CRM action — 400 otherwise). 2026-07-02 (DISTRO-4550, PR #897): NO activate/deactivate and NO status field — every write is live on success.; 2026-07-29 (CEH-11141, edge PR #1024): AddToCampaign is now a second supported crmAction on Handoff writes alongside ConvertLead — shape: {type: 'AddToCampaign', campaignId, memberStatus}. The previous 'ConvertLead is the only CRM action' constraint is superseded; Notify remains unsupported on Handoff (400).; 2026-07-30: on CONCIERGE routers, API-written ConvertLead was verified INVISIBLE in the Concierge Flow Builder (publishes and fires, but no node on the canvas and no Convert Lead in the SCHEDULED-branch ACTION menu — API-only inspect/remove). Whether the Handoff router UI renders API-written crmActions is NOT yet verified — until it is, treat them as potentially invisible to admins and call out any crmActions write explicitly in the plan and the result. 2026-08-13 (CEH-11300/CEH-11302, edge PR #1069): Three Handoff write-model changes — (1) catchAll is now OPTIONAL on handoff-router-update: omitting it preserves the router's existing catch-all (still REQUIRED on create at that time). (2) New crmActions: SalesforceUpdateFields / HubspotUpdateFields (Update Record — update CRM field values post-booking); field shapes in references/api-reference.md. (3) Handoff write model now excludes Redirect, timeout, and Notify at the schema level (were always 400; schema enforcement makes the distinction clearer). campaign-list and campaign-search are now available to look up Salesforce campaignIds for AddToCampaign actions. 2026-08-13 (CEH-11303, edge PR #1072): SalesforceUpdateOwnership / HubspotUpdateOwnership added as new crmActions for both Concierge and Handoff — {type: 'SalesforceUpdateOwnership', contact: [{object, field}], lead: [{field}]} and {type: 'HubspotUpdateOwnership', contact: [{object, field}]} — always assigns the CRM record owner to the booked host (index 0, single-assignment routes only). Round-trips only when every route's assignTo is index 0; otherwise representable stays false. 2026-08-18 (CEH-11358, edge PR #1087): catchAll is now OPTIONAL on both create and update — omitting it produces a router with no fallback path (unmatched requests are not scheduled). The 'required on create' constraint is lifted.; 2026-09-03 (CEH-11588/CEH-11589, edge PR #1151): Two changes. (1) SalesforceCreateEvent and HubspotCreateEngagement added as new Handoff crmActions (Create Event — post-booking calendar event in CRM). Settings: relatedTo is optional (omit for no relation; Handoff rejects ExplicitObject/RelationDisabled relations with 400), meetingCancellationBehavior (default DoNothing), guestsBehavior (default DoNothing), owner (default Assignee). Full field shapes in references/api-reference.md. (2) handoff-router-get and handoff-router-list now return the COMPLETE crmActions chain — previously unmodellable nodes collapsed the whole array to null; now they become an Other{kind} read-only placeholder and the walk continues down the chain so representable siblings are preserved. Other is read-only and REJECTED on write; representable becomes false when any placeholder was emitted. 2026-09-04 (CEH-11599, edge PR #1154): the read-only ContactOptions outcome variant now exposes its three CRM-action chains — {type: 'ContactOptions', meeting?, callSuccess?, callMissed?}, each branch an ordered list of the same crmAction union incl. Other (null = branch absent, [] = present with no actions). Kept in the variant list for ac