> ## Documentation Index > Fetch the complete documentation index at: https://docs.visitoai.com/llms.txt > Use this file to discover all available pages before exploring further. # Change AI escalation rules and knowledge-gap behavior > 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. ## OpenAPI ````yaml /openapi.json put /settings/ai/handoff-policy openapi: 3.0.3 info: title: Visito M2M API version: 1.0.0 description: >- Tenant-scoped server-to-server API for channels, conversations, commerce, custom AI tools, and WhatsApp templates. Send operations are asynchronous and return queued acknowledgements. Expansion adds conversation controls, knowledge, sales opportunities, delivery status, reporting, and signed webhooks. servers: - url: https://platform-api.visitoai.com/m2m/v1 description: Production security: - bearerAuth: [] tags: - name: Channels - name: Conversations - name: Commerce - name: Custom tools - name: WhatsApp templates - name: Properties - name: Knowledge - name: Sales CRM - name: Delivery - name: Reporting - name: Webhooks paths: /settings/ai/handoff-policy: put: summary: Change AI escalation rules and knowledge-gap behavior description: >- 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. operationId: update_ai_handoff_policy parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AiHandoffPolicyInput' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/AiHandoffPolicyResult' '400': description: Invalid policy '403': description: Missing permission '409': description: Stale policy version components: schemas: AiHandoffPolicyInput: type: object additionalProperties: false properties: expectedPolicyVersion: type: string maxLength: 128 description: >- 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: type: boolean knowledgeGapBehavior: type: string enum: - disabled - report_only - create_handoff workingHours: $ref: '#/components/schemas/AiHandoffWorkingHours' intents: type: array items: $ref: '#/components/schemas/AiHandoffIntentInput' maxItems: 100 required: - expectedPolicyVersion - enabled - intents AiHandoffPolicyResult: type: object additionalProperties: false properties: policy: $ref: '#/components/schemas/AiHandoffPolicy' required: - policy AiHandoffWorkingHours: type: object additionalProperties: false properties: enabled: type: boolean schedule: type: array items: type: object additionalProperties: false properties: day: type: string enum: - monday - tuesday - wednesday - thursday - friday - saturday - sunday open: type: boolean start: type: string maxLength: 5 pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ end: type: string maxLength: 5 pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ required: - day - open - start - end maxItems: 7 minItems: 7 required: - enabled - schedule AiHandoffIntentInput: type: object additionalProperties: false properties: id: type: string maxLength: 128 name: type: string maxLength: 1000 description: type: string maxLength: 6000 enabled: type: boolean severity: type: string enum: - hard priority: type: number propertyIds: type: array items: type: string maxLength: 128 maxItems: 100 requiredFields: type: array items: type: string maxLength: 128 maxItems: 100 fieldLabels: type: object additionalProperties: type: string maxLength: 1000 required: - name - description AiHandoffPolicy: type: object additionalProperties: false properties: tenantId: type: string maxLength: 128 enabled: type: boolean knowledgeGapBehavior: type: string enum: - disabled - report_only - create_handoff policyVersion: type: string maxLength: 128 workingHours: $ref: '#/components/schemas/AiHandoffWorkingHours' intents: type: array items: $ref: '#/components/schemas/AiHandoffIntent' required: - tenantId - enabled - knowledgeGapBehavior - policyVersion - workingHours - intents AiHandoffIntent: type: object additionalProperties: false properties: id: type: string maxLength: 128 name: type: string maxLength: 1000 description: type: string maxLength: 6000 enabled: type: boolean severity: type: string enum: - hard priority: type: number propertyIds: type: array items: type: string maxLength: 128 maxItems: 100 requiredFields: type: array items: type: string maxLength: 128 maxItems: 100 fieldLabels: type: object additionalProperties: type: string maxLength: 1000 required: - id - name - description - enabled - severity - priority - requiredFields securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Visito M2M API key description: Server-side tenant-scoped credential created from Build > API Keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.