OtpInstruction

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/cm-com/main/json-schema/cm-com-otp-instruction-schema.json",
  "title": "OtpInstruction",
  "description": "Instruction to send an OTP (One Time Password) to the callee.",
  "x-generated": "2026-10-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cm-com-voice-voice-api-v2-openapi.yml#/components/schemas/OtpInstruction",
  "required": [
    "caller",
    "code"
  ],
  "type": "object",
  "properties": {
    "instruction-id": {
      "maxLength": 64,
      "type": [
        "string",
        "null"
      ],
      "description": "Optional string that allows you to uniquely identify the placed outbound call. Its value is also included\r\nin the callback and Call Detail Records (CDRs)."
    },
    "callee": {
      "maxLength": 24,
      "pattern": "^(\\+|00)?[1-9]\\d{6,14}$",
      "type": [
        "string",
        "null"
      ],
      "description": "The number to dial. When the number is invalid, the request will be rejected. Must be in valid international\r\nE.164 format."
    },
    "callees": {
      "pattern": "^(\\+|00)?[1-9]\\d{6,14}$",
      "maxItems": 100,
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "description": "List of multiple numbers to dial. When the list contains one or more invalid numbers, the request will be\r\nrejected. Must be in valid international E.164 format."
    },
    "caller": {
      "maxLength": 24,
      "minLength": 1,
      "pattern": "^(\\+|00)?[1-9]\\d{6,14}$",
      "type": "string",
      "description": "The caller ID to display on the recipient's phone. Must be in valid international E.164 format."
    },
    "anonymous": {
      "type": "boolean",
      "description": "Indicates whether the caller ID should be hidden. Defaults to `false`."
    },
    "callback-url": {
      "type": [
        "string",
        "null"
      ],
      "description": "URL that will be called when the call is finished. The body of this POST request will contain details about\r\nthe call or calls.",
      "format": "uri"
    },
    "max-ringing-timeout": {
      "maximum": 60,
      "minimum": 10,
      "type": [
        "integer",
        "null"
      ],
      "description": "Determines how long the Voice API will wait for the callee to answer the call. Cancels the ringing call\r\nafter the timeout period exceeded. Defaults to `60`.",
      "format": "int32"
    },
    "intro-prompt": {
      "maxLength": 500,
      "type": [
        "string",
        "null"
      ],
      "description": "Optional prompt to play when the call is first answered. This can be either TTS or SSML, or the path to an\r\naudio file in your Voice Audio Manager."
    },
    "intro-prompt-type": {
      "$ref": "#/$defs/PromptType"
    },
    "code-prompt": {
      "maxLength": 500,
      "type": [
        "string",
        "null"
      ],
      "description": "Optional prompt to play right before playing the actual OTP code. This can be either TTS or SSML, or the\r\npath to an audio file in your Voice Audio Manager. This prompt is also replayed when the code is replayed."
    },
    "code-prompt-type": {
      "$ref": "#/$defs/PromptType"
    },
    "code": {
      "maxLength": 64,
      "minLength": 1,
      "type": "string",
      "description": "The code to read to the caller. Note that this code is read character per character, not as a word or number."
    },
    "code-type": {
      "$ref": "#/$defs/CodeType"
    },
    "replay-prompt": {
      "maxLength": 500,
      "type": [
        "string",
        "null"
      ],
      "description": "Optional prompt instructing the callee to press 1 to replay the OTP. This can be either TTS or SSML, or the\r\npath to an audio file in your Voice Audio Manager."
    },
    "replay-prompt-type": {
      "$ref": "#/$defs/PromptType"
    },
    "outro-prompt": {
      "maxLength": 500,
      "type": [
        "string",
        "null"
      ],
      "description": "Optional prompt instructing the callee to press 1 to replay the Notification. This can be either TTS or\r\nSSML, or the path to an audio file in your Voice Audio Manager."
    },
    "outro-prompt-type": {
      "$ref": "#/$defs/PromptType"
    },
    "max-replays": {
      "maximum": 3,
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ],
      "description": "The number of times the OTP can be replayed.",
      "format": "int32"
    },
    "auto-replay": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Whether to automatically replay the OTP. Defaults to `false`."
    },
    "voice": {
      "$ref": "#/$defs/Voice"
    },
    "voicemail-response": {
      "$ref": "#/$defs/VoicemailResponse"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "CodeType": {
      "title": "Code Type",
      "enum": [
        "Default",
        "TTS",
        "Custom"
      ],
      "type": "string",
      "description": "The type of the OTP code"
    },
    "Gender": {
      "title": "Gender",
      "enum": [
        "Male",
        "Female"
      ],
      "type": "string",
      "description": "Genders supported by TTS."
    },
    "PromptType": {
      "title": "Prompt Type",
      "enum": [
        "File",
        "TTS",
        "TTS_SSML"
      ],
      "type": "string",
      "description": "The type of the prompt, to distinguish between a filename and a string that needs to be tts-ed."
    },
    "Voice": {
      "title": "Voice",
      "required": [
        "gender",
        "language",
        "number"
      ],
      "type": "object",
      "properties": {
        "language": {
          "maxLength": 6,
          "minLength": 5,
          "pattern": "^[a-zA-Z]{2,3}-[a-zA-Z]{2,3}$",
          "type": "string",
          "description": "The language (5 character locale) of the voice to use. Examples: en-US, en-GB, nl-NL. Defaults to en-GB"
        },
        "gender": {
          "$ref": "#/$defs/Gender"
        },
        "number": {
          "maximum": 2147483647,
          "minimum": 1,
          "type": "integer",
          "description": "Usually `1`, but if the selected language and gender support multiple voices, you can use this to make\r\na selection between the different ones. To see the available voices, please see the\r\n<a href=\"/voice/tts/supported-languages\">TTS voices documentation</a>.",
          "format": "int32"
        },
        "volume": {
          "maximum": 4,
          "minimum": -4,
          "type": "integer",
          "description": "The volume level of the voice. Must be a value between -4 and 4. Defaults to 0.",
          "format": "int32"
        },
        "premium": {
          "type": "boolean",
          "description": "Whether to use a premium text-to-speech voice. Please be aware that additional costs will be charged for the\r\nuse of premium voices. Defaults to `false`."
        }
      },
      "additionalProperties": false,
      "description": "The properties in this class are used to select the required TTS voice."
    },
    "VoicemailResponse": {
      "title": "Voicemail Response",
      "enum": [
        "Ignore",
        "Restart",
        "Stop",
        "Disconnect"
      ],
      "type": "string",
      "description": "The type that determines the flow of Voicemail detection."
    }
  }
}