---
title: "Change AI escalation rules and knowledge-gap behavior"
method: PUT
path: "/settings/ai/handoff-policy"
---

# Change AI escalation rules and knowledge-gap behavior

`PUT /settings/ai/handoff-policy`

## Request

- Base URL: `https://platform-api.visitoai.com/m2m/v1`
- URL: `https://platform-api.visitoai.com/m2m/v1/settings/ai/handoff-policy`
- Auth: HTTP bearer

Update the existing guest-facing escalation policy using a fresh get_ai_handoff_policy read and expectedPolicyVersion. enabled and the complete intents array are required; preserve IDs/fields of rules you intend to retain. Omit knowledgeGapBehavior or workingHours to preserve them. New rules may omit id and receive a service-generated stable ID; inspect returned IDs. Normally at most eight rules; existing oversized policies can only shrink without adding IDs. propertyIds must reference active properties from list_properties. Working hours require all seven distinct days with valid HH:mm times in the business timezone. A 409 conflict requires reload/reconciliation. The service schedules existing handoff projections after saving; on uncertain failure read current policy before retrying. This affects future escalation and projection state; it does not resolve cases, send a guest reply, or enable server knowledge-gap rollout gates. Required permission: ai_settings:write. Connected business only.

## Request body

- AiHandoffPolicyInput
  - `expectedPolicyVersion` string, required: Copy policy.policyVersion from get_ai_handoff_policy, including default when no stored policy exists. Stale versions return HANDOFF_POLICY_VERSION_CONFLICT (409); reload and reconcile.
  - `enabled` boolean, required
  - `knowledgeGapBehavior` 'disabled' | 'report_only' | 'create_handoff'
  - `workingHours` AiHandoffWorkingHours
    - `enabled` boolean, required
    - `schedule` object[], required
      - `day` 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday', required
      - `open` boolean, required
      - `start` string, required
      - `end` string, required
  - `intents` AiHandoffIntentInput[], required
    - `id` string
    - `name` string, required
    - `description` string, required
    - `enabled` boolean
    - `severity` 'hard'
    - `priority` number
    - `propertyIds` string[]
    - `requiredFields` string[]
    - `fieldLabels` object

## Response `200`

Success

- AiHandoffPolicyResult
  - `policy` AiHandoffPolicy, required
    - `tenantId` string, required
    - `enabled` boolean, required
    - `knowledgeGapBehavior` 'disabled' | 'report_only' | 'create_handoff', required
    - `policyVersion` string, required
    - `workingHours` AiHandoffWorkingHours, required
      - `enabled` boolean, required
      - `schedule` object[], required
        - `day` 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday', required
        - `open` boolean, required
        - `start` string, required
        - `end` string, required
    - `intents` AiHandoffIntent[], required
      - `id` string, required
      - `name` string, required
      - `description` string, required
      - `enabled` boolean, required
      - `severity` 'hard', required
      - `priority` number, required
      - `propertyIds` string[]
      - `requiredFields` string[], required
      - `fieldLabels` object

## Other responses

- `400`: Invalid policy
- `403`: Missing permission
- `409`: Stale policy version

---

[API](https://skmtc.dev/visitoai/apis/visito-m2m-api.md) - [All operations](https://skmtc.dev/visitoai/apis/visito-m2m-api/llms.txt) - [OpenAPI document](https://skmtc.dev/visitoai/apis/visito-m2m-api/revisions/98377d35c234?raw)