CreateCallRequestAnswerUrl

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/vonage/main/json-schema/vonage-create-call-request-answer-url-schema.json",
  "title": "CreateCallRequestAnswerUrl",
  "x-generated": "2026-10-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vonage-voice-openapi.yml#/components/schemas/CreateCallRequestAnswerUrl",
  "allOf": [
    {
      "$ref": "#/$defs/CreateCallRequestBase"
    },
    {
      "type": "object",
      "title": "With Answer URL",
      "required": [
        "answer_url"
      ],
      "properties": {
        "answer_url": {
          "description": "The webhook endpoint where you provide the [Nexmo Call Control Object](/voice/voice-api/ncco-reference) that governs this call.\n",
          "type": "array",
          "x-nexmo-developer-collection-description-shown": true,
          "items": {
            "type": "string",
            "format": "uri"
          }
        },
        "answer_method": {
          "description": "The HTTP method used to send event information to answer_url.",
          "type": "string",
          "default": "GET",
          "enum": [
            "POST",
            "GET"
          ]
        }
      }
    }
  ],
  "$defs": {
    "AddressE164": {
      "description": "The phone number to connect to",
      "type": "string",
      "minLength": 7,
      "maxLength": 15,
      "pattern": "\\d{7,15}"
    },
    "AddressSip": {
      "description": "The SIP URI to connect to",
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "AddressWebsocket": {
      "type": "string",
      "minLength": 1
    },
    "CreateCallRequestBase": {
      "type": "object",
      "required": [
        "to"
      ],
      "properties": {
        "to": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "$ref": "#/$defs/EndpointPhoneTo"
              },
              {
                "$ref": "#/$defs/EndpointSip"
              },
              {
                "$ref": "#/$defs/EndpointWebsocket"
              },
              {
                "$ref": "#/$defs/EndpointVBCExtension"
              },
              {
                "$ref": "#/$defs/EndpointApp"
              }
            ]
          }
        },
        "from": {
          "$ref": "#/$defs/EndpointPhoneFrom"
        },
        "random_from_number": {
          "description": "Set to `true` to use random phone number as `from`. The number will be selected from the list of the numbers assigned to the current application. This property is mutually exclusive with `from`: you must specify one (`random_from_number: true`) or the other (`from`).",
          "type": "boolean",
          "default": false
        },
        "event_url": {
          "description": "**Required** unless `event_url` is configured at the application\nlevel, see [Create an Application](/api/application.v2#createApplication)\n\nThe webhook endpoint where call progress events are\nsent to. For more information about the values sent, see\n[Event webhook](/voice/voice-api/webhook-reference#event-webhook).\n",
          "type": "array",
          "x-nexmo-developer-collection-description-shown": true,
          "items": {
            "type": "string",
            "format": "uri"
          }
        },
        "event_method": {
          "description": "The HTTP method used to send event information to `event_url`.",
          "type": "string",
          "default": "POST",
          "enum": [
            "POST",
            "GET"
          ]
        },
        "machine_detection": {
          "description": "Configure the behavior when Vonage detects that the call is answered by voicemail. If `continue`, Vonage sends an HTTP request to `event_url` with the Call event machine. If `hangup`, Vonage ends the call.",
          "type": "string",
          "enum": [
            "continue",
            "hangup"
          ]
        },
        "advanced_machine_detection": {
          "description": "Configure the behavior of Vonage's advanced machine detection. Overrides `machine_detection` if both are set. Note that this is a beta feature which will be chargeable; exact rates can be found on the [Voice API Pricing](https://www.vonage.co.uk/communications-apis/voice/pricing/) page under 'Programmable Features'.",
          "type": "object",
          "properties": {
            "behavior": {
              "description": "When `hangup` is used, the call will be terminated if a machine is detected. When `continue` is used, the call will continue even if a machine is detected.",
              "type": "string",
              "enum": [
                "continue",
                "hangup"
              ]
            },
            "mode": {
              "description": "Detect if machine answered and sends a human or machine status in the webhook payload. The modes are as follows:\n\n* `default` - async mode, the next NCCO action will be processed immediately in parallel with machine detection, the application will receive both machine detection status and beep events and can reply with new NCCO to any of them;\n\n* `detect` - sync mode, the next NCCO action will be processed only when machine detection is finished, the application will receive only machine detection status event;\n\n* `detect_beep` - sync mode, the next NCCO action will be processed only when machine detection is finished, the application will receive only a beep event.\n",
              "type": "string",
              "default": "detect",
              "enum": [
                "default",
                "detect",
                "detect_beep"
              ]
            },
            "beep_timeout": {
              "description": "Maximum time in seconds Vonage should wait for a machine beep to be detected. A machine event with `sub_state` set to `beep_timeout` will be sent if the timeout is exceeded.",
              "type": "integer",
              "minimum": 30,
              "maximum": 120
            }
          }
        },
        "length_timer": {
          "description": "Set the number of seconds that elapse before Vonage hangs up after the call state changes to answered.",
          "minimum": 1,
          "maximum": 86400,
          "default": 7200,
          "type": "integer"
        },
        "ringing_timer": {
          "description": "Set the number of seconds that elapse before Vonage hangs up after the call state changes to ‘ringing’.",
          "minimum": 1,
          "maximum": 120,
          "default": 60,
          "type": "integer"
        }
      }
    },
    "EndpointApp": {
      "type": "object",
      "description": "Connect to an App User",
      "required": [
        "type",
        "user"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of connection. Must be `app`"
        },
        "user": {
          "type": "string",
          "description": "The username to connect to"
        }
      }
    },
    "EndpointPhoneFrom": {
      "type": "object",
      "description": "Connect to a Phone (PSTN) number. This property is mutually exclusive with `random_from_number`: you must specify one (`from`) or the other (`random_from_number: true`).",
      "required": [
        "number",
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of connection. Must be `phone`."
        },
        "number": {
          "type": "string",
          "description": "The phone number to connect to. It can be either an E.164 formatted number or a SIP URI."
        }
      }
    },
    "EndpointPhoneTo": {
      "type": "object",
      "description": "Connect to a Phone (PSTN) number",
      "required": [
        "number",
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of connection. Must be `phone`"
        },
        "number": {
          "$ref": "#/$defs/AddressE164"
        },
        "dtmfAnswer": {
          "description": "Provide [DTMF digits](https://developer.nexmo.com/voice/voice-api/concepts/dtmf) to send when the call is answered",
          "type": "string"
        },
        "shaken": {
          "description": "For Vonage customers who are required by the FCC to sign their own calls to the USA, we allow you to place Voice API calls with your own signature. This feature is available by request only. Please be aware calls with an invalid signature will be rejected. For more information please contact us. In this option, you must place the STIR/SHAKEN Identity Header content that Vonage must use for this call. Expected format is composed of the JWT with the header, payload and signature, an info parameter with a link for the certificate, the algorithm (alg) parameter indicating which encryption type was used and the passport type (ppt) which should be shaken.",
          "type": "string"
        }
      }
    },
    "EndpointSip": {
      "type": "object",
      "description": "Connect to a SIP Endpoint",
      "required": [
        "type",
        "uri"
      ],
      "properties": {
        "type": {
          "description": "The type of connection. Must be `sip`",
          "type": "string"
        },
        "uri": {
          "$ref": "#/$defs/AddressSip"
        },
        "headers": {
          "description": "Metadata to include in the request. The headers are transmitted as part of the SIP INVITE as `X-key: value` headers.",
          "type": "object"
        },
        "standard_headers": {
          "description": "Standard SIP INVITE headers. Unlike the `headers` property, these are not prepended with `X-`.",
          "type": "object",
          "required": [
            "User-to-User"
          ],
          "properties": {
            "User-to-User": {
              "description": "Transmit user-to-user information if supported by the CC / PBX vendor, as per [RFC 7433](https://datatracker.ietf.org/doc/html/rfc7433).",
              "type": "string"
            }
          }
        }
      }
    },
    "EndpointVBCExtension": {
      "type": "object",
      "description": "Connect to a VBC extension",
      "required": [
        "type",
        "extension"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of connection. Must be `vbc`"
        },
        "extension": {
          "type": "string"
        }
      }
    },
    "EndpointWebsocket": {
      "type": "object",
      "description": "Connect to a Websocket",
      "required": [
        "type",
        "content-type"
      ],
      "properties": {
        "type": {
          "description": "The type of connection. Must be `websocket`",
          "type": "string"
        },
        "uri": {
          "$ref": "#/$defs/AddressWebsocket"
        },
        "content-type": {
          "type": "string",
          "enum": [
            "audio/l16;rate=8000",
            "audio/l16;rate=16000",
            "audio/l16;rate=24000"
          ]
        },
        "headers": {
          "description": "Details of the Websocket you want to connect to",
          "type": "object",
          "properties": {
            "customer_id": {
              "type": "string",
              "description": "This is an example header. You can provide any headers you may need"
            }
          }
        },
        "authorization": {
          "description": "Optional configuration defining how the Authorization HTTP header is set in the WebSocket opening handshake.",
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "default": "vonage",
              "description": "Defines the authorization mode. \"vonage\" – the Voice API includes the same JWT used for signed webhooks in the Authorization header ('Bearer {JWT}'). \"custom\" – a developer-supplied Authorization header value is sent verbatim.",
              "enum": [
                "vonage",
                "custom"
              ]
            },
            "value": {
              "type": "string",
              "description": "Required only when authorization.type = \"custom\". The raw header value to include, e.g. \"Bearer abc123\" or \"ApiKey X9Z...\". Ignored when authorization.type = \"vonage\"."
            }
          }
        }
      }
    }
  }
}