{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/UpdateHandoffToolDTO",
  "title": "UpdateHandoffToolDTO",
  "type": "object",
  "properties": {
    "messages": {
      "type": "array",
      "description": "These are the messages that will be spoken to the user as the tool is running.\n\nFor some tools, this is auto-filled based on special fields like `tool.destinations`. For others like the function tool, these can be custom configured.",
      "items": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/ToolMessageStart",
            "title": "ToolMessageStart"
          },
          {
            "$ref": "#/components/schemas/ToolMessageComplete",
            "title": "ToolMessageComplete"
          },
          {
            "$ref": "#/components/schemas/ToolMessageFailed",
            "title": "ToolMessageFailed"
          },
          {
            "$ref": "#/components/schemas/ToolMessageDelayed",
            "title": "ToolMessageDelayed"
          }
        ]
      }
    },
    "defaultResult": {
      "type": "string",
      "description": "This is the default local tool result message used when no runtime handoff result override is returned."
    },
    "destinations": {
      "type": "array",
      "description": "These are the destinations that the call can be handed off to.\n\nUsage:\n1. Single destination\n\nUse `assistantId` to handoff the call to a saved assistant, or `assistantName` to handoff the call to an assistant in the same squad.\n\n```json\n{\n  \"tools\": [\n    {\n      \"type\": \"handoff\",\n      \"destinations\": [\n        {\n          \"type\": \"assistant\",\n          \"assistantId\": \"assistant-123\", // or \"assistantName\": \"Assistant123\"\n          \"description\": \"customer wants to be handed off to assistant-123\",\n          \"contextEngineeringPlan\": {\n            \"type\": \"all\"\n          }\n        }\n      ],\n    }\n  ]\n}\n```\n\n2. Multiple destinations\n\n2.1. Multiple Tools, Each With One Destination (OpenAI recommended)\n\n```json\n{\n  \"tools\": [\n    {\n      \"type\": \"handoff\",\n      \"destinations\": [\n        {\n          \"type\": \"assistant\",\n          \"assistantId\": \"assistant-123\",\n          \"description\": \"customer wants to be handed off to assistant-123\",\n          \"contextEngineeringPlan\": {\n            \"type\": \"all\"\n          }\n        },\n      ],\n    },\n    {\n      \"type\": \"handoff\",\n      \"destinations\": [\n        {\n          \"type\": \"assistant\",\n          \"assistantId\": \"assistant-456\",\n          \"description\": \"customer wants to be handed off to assistant-456\",\n          \"contextEngineeringPlan\": {\n            \"type\": \"all\"\n          }\n        }\n      ],\n    }\n  ]\n}\n```\n\n2.2. One Tool, Multiple Destinations (Anthropic recommended)\n\n```json\n{\n  \"tools\": [\n    {\n      \"type\": \"handoff\",\n      \"destinations\": [\n        {\n          \"type\": \"assistant\",\n          \"assistantId\": \"assistant-123\",\n          \"description\": \"customer wants to be handed off to assistant-123\",\n          \"contextEngineeringPlan\": {\n            \"type\": \"all\"\n          }\n        },\n        {\n          \"type\": \"assistant\",\n          \"assistantId\": \"assistant-456\",\n          \"description\": \"customer wants to be handed off to assistant-456\",\n          \"contextEngineeringPlan\": {\n            \"type\": \"all\"\n          }\n        }\n      ],\n    }\n  ]\n}\n```\n\n3. Dynamic destination\n\n3.1 To determine the destination dynamically, supply a `dynamic` handoff destination type and a `server` object.\n    VAPI will send a handoff-destination-request webhook to the `server.url`.\n    The response from the server will be used as the destination (if valid).\n\n```json\n{\n  \"tools\": [\n    {\n      \"type\": \"handoff\",\n      \"destinations\": [\n        {\n          \"type\": \"dynamic\",\n          \"server\": {\n            \"url\": \"https://example.com\"\n          }\n        }\n      ],\n    }\n  ]\n}\n```\n\n3.2. To pass custom parameters to the server, you can use the `function` object.\n\n```json\n{\n  \"tools\": [\n    {\n      \"type\": \"handoff\",\n      \"destinations\": [\n        {\n          \"type\": \"dynamic\",\n          \"server\": {\n            \"url\": \"https://example.com\"\n          },\n        }\n      ],\n      \"function\": {\n        \"name\": \"handoff\",\n        \"description\": \"Call this function when the customer is ready to be handed off to the next assistant\",\n        \"parameters\": {\n          \"type\": \"object\",\n          \"properties\": {\n            \"destination\": {\n              \"type\": \"string\",\n              \"description\": \"Use dynamic when customer is ready to be handed off to the next assistant\",\n              \"enum\": [\"dynamic\"]\n            },\n            \"customerAreaCode\": {\n              \"type\": \"number\",\n              \"description\": \"Area code of the customer\"\n            },\n            \"customerIntent\": {\n              \"type\": \"string\",\n              \"enum\": [\"new-customer\", \"existing-customer\"],\n              \"description\": \"Use new-customer when customer is a new customer, existing-customer when customer is an existing customer\"\n            },\n            \"customerSentiment\": {\n              \"type\": \"string\",\n              \"enum\": [\"positive\", \"negative\", \"neutral\"],\n              \"description\": \"Use positive when customer is happy, negative when customer is unhappy, neutral when customer is neutral\"\n            }\n          }\n        }\n      }\n    }\n  ]\n}\n```\n\nThe properties `customerAreaCode`, `customerIntent`, and `customerSentiment` will be passed to the server in the webhook request body.",
      "items": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/HandoffDestinationAssistant",
            "title": "Assistant"
          },
          {
            "$ref": "#/components/schemas/HandoffDestinationDynamic",
            "title": "Dynamic"
          },
          {
            "$ref": "#/components/schemas/HandoffDestinationSquad",
            "title": "Squad"
          }
        ]
      }
    },
    "rejectionPlan": {
      "description": "This is the plan to reject a tool call based on the conversation state.\n\n// Example 1: Reject endCall if user didn't say goodbye\n```json\n{\n  conditions: [{\n    type: 'regex',\n    regex: '(?i)\\\\b(bye|goodbye|farewell|see you later|take care)\\\\b',\n    target: { position: -1, role: 'user' },\n    negate: true  // Reject if pattern does NOT match\n  }]\n}\n```\n\n// Example 2: Reject transfer if user is actually asking a question\n```json\n{\n  conditions: [{\n    type: 'regex',\n    regex: '\\\\?',\n    target: { position: -1, role: 'user' }\n  }]\n}\n```\n\n// Example 3: Reject transfer if user didn't mention transfer recently\n```json\n{\n  conditions: [{\n    type: 'liquid',\n    liquid: `{% assign recentMessages = messages | last: 5 %}\n{% assign userMessages = recentMessages | where: 'role', 'user' %}\n{% assign mentioned = false %}\n{% for msg in userMessages %}\n  {% if msg.content contains 'transfer' or msg.content contains 'connect' or msg.content contains 'speak to' %}\n    {% assign mentioned = true %}\n    {% break %}\n  {% endif %}\n{% endfor %}\n{% if mentioned %}\n  false\n{% else %}\n  true\n{% endif %}`\n  }]\n}\n```\n\n// Example 4: Reject endCall if the bot is looping and trying to exit\n```json\n{\n  conditions: [{\n    type: 'liquid',\n    liquid: `{% assign recentMessages = messages | last: 6 %}\n{% assign userMessages = recentMessages | where: 'role', 'user' | reverse %}\n{% if userMessages.size < 3 %}\n  false\n{% else %}\n  {% assign msg1 = userMessages[0].content | downcase %}\n  {% assign msg2 = userMessages[1].content | downcase %}\n  {% assign msg3 = userMessages[2].content | downcase %}\n  {% comment %} Check for repetitive messages {% endcomment %}\n  {% if msg1 == msg2 or msg1 == msg3 or msg2 == msg3 %}\n    true\n  {% comment %} Check for common loop phrases {% endcomment %}\n  {% elsif msg1 contains 'cool thanks' or msg2 contains 'cool thanks' or msg3 contains 'cool thanks' %}\n    true\n  {% elsif msg1 contains 'okay thanks' or msg2 contains 'okay thanks' or msg3 contains 'okay thanks' %}\n    true\n  {% elsif msg1 contains 'got it' or msg2 contains 'got it' or msg3 contains 'got it' %}\n    true\n  {% else %}\n    false\n  {% endif %}\n{% endif %}`\n  }]\n}\n```",
      "allOf": [
        {
          "$ref": "#/components/schemas/ToolRejectionPlan"
        }
      ]
    },
    "function": {
      "description": "This is the optional function definition that will be passed to the LLM.\nIf this is not defined, we will construct this based on the other properties.\n\nFor example, given the following tools definition:\n```json\n{\n  \"tools\": [\n    {\n      \"type\": \"handoff\",\n      \"destinations\": [\n        {\n          \"type\": \"assistant\",\n          \"assistantId\": \"assistant-123\",\n          \"description\": \"customer wants to be handed off to assistant-123\",\n          \"contextEngineeringPlan\": {\n            \"type\": \"all\"\n          }\n        },\n        {\n          \"type\": \"assistant\",\n          \"assistantId\": \"assistant-456\",\n          \"description\": \"customer wants to be handed off to assistant-456\",\n          \"contextEngineeringPlan\": {\n            \"type\": \"all\"\n          }\n        }\n      ],\n    }\n  ]\n}\n```\n\nWe will construct the following function definition:\n```json\n{\n  \"function\": {\n    \"name\": \"handoff_to_assistant-123\",\n    \"description\": \"\n         Use this function to handoff the call to the next assistant.\n         Only use it when instructions explicitly ask you to use the handoff_to_assistant function.\n         DO NOT call this function unless you are instructed to do so.\n         Here are the destinations you can handoff the call to:\n         1. assistant-123. When: customer wants to be handed off to assistant-123\n         2. assistant-456. When: customer wants to be handed off to assistant-456\n    \",\n    \"parameters\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"destination\": {\n          \"type\": \"string\",\n          \"description\": \"Options: assistant-123 (customer wants to be handed off to assistant-123), assistant-456 (customer wants to be handed off to assistant-456)\",\n          \"enum\": [\"assistant-123\", \"assistant-456\"]\n        },\n      },\n      \"required\": [\"destination\"]\n    }\n  }\n}\n```\n\nTo override this function, please provide an OpenAI function definition and refer to it in the system prompt.\nYou may override parts of the function definition (i.e. you may only want to change the function name for your prompt).\nIf you choose to override the function parameters, it must include `destination` as a required parameter, and it must evaluate to either an assistantId, assistantName, or a the string literal `dynamic`.\n\nTo pass custom parameters to the server in a dynamic handoff, you can use the function parameters, with `dynamic` as the destination.\n```json\n{\n  \"function\": {\n    \"name\": \"dynamic_handoff\",\n    \"description\": \"\n         Call this function when the customer is ready to be handed off to the next assistant\n    \",\n    \"parameters\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"destination\": {\n          \"type\": \"string\",\n          \"enum\": [\"dynamic\"]\n        },\n        \"customerAreaCode\": {\n          \"type\": \"number\",\n          \"description\": \"Area code of the customer\"\n        },\n        \"customerIntent\": {\n          \"type\": \"string\",\n          \"enum\": [\"new-customer\", \"existing-customer\"],\n          \"description\": \"Use new-customer when customer is a new customer, existing-customer when customer is an existing customer\"\n        },\n        \"customerSentiment\": {\n          \"type\": \"string\",\n          \"enum\": [\"positive\", \"negative\", \"neutral\"],\n          \"description\": \"Use positive when customer is happy, negative when customer is unhappy, neutral when customer is neutral\"\n        }\n      },\n      \"required\": [\"destination\", \"customerAreaCode\", \"customerIntent\", \"customerSentiment\"]\n    }\n  }\n}\n```",
      "allOf": [
        {
          "$ref": "#/components/schemas/OpenAIFunction"
        }
      ]
    }
  }
}