# Prompt Input Event

This callback is triggered as a result of a [runMenu](https://developers.sinch.com/docs/voice/api-reference/svaml/actions/#runmenu) action. It can be triggered from either a user pressing a number of DTMF digits, or by the `return` command.
It's a POST request to the specified calling callback URL. Your application can respond with [SVAML](https://developers.sinch.com/docs/voice/api-reference/svaml/) logic.
Note: PIE callbacks are not issued for DATA Calls, only PSTN and SIP calls.

Endpoint: POST pie
Version: 1.0.1
Security: Basic, Signed

## Security:

  - `Basic` (unknown)
    http basic

  - `Signed` (unknown)
    apiKey in header Authorization

## Request fields (application/json):

  - `event` (string, required)
    Must have the value `pie`.
    Enum: "pie"

  - `callid` (string)
    Used in some types of events, it presents the unique ID assigned to this call.

  - `conferenceId` (string)
    Used in some types of events, it presents the unique Conference ID assigned to this call.

  - `version` (integer)
    The current API version.

  - `timestamp` (string)
    The timestamp in UTC format.
    Example: 2023-04-21T14:45:51Z

  - `menuResult` (object)
    An object containing information about the returned menu result.

  - `menuResult.menuId` (string)
    The ID of the menu that triggered the prompt input event.

  - `menuResult.type` (string)
    The type of information that's returned.
    Enum: "error", "return", "sequence", "timeout", "hangup", "invalidinput"

  - `menuResult.value` (string)
    The value of the returned information.

  - `menuResult.inputMethod` (string)
    The type of input received.
    Enum: "dtmf", "voice"

  - `custom` (string)
    A string that can be used to pass custom information related to the call.

  - `applicationKey` (string)
    The unique application key. You can find it in the Sinch [dashboard](https://dashboard.sinch.com/voice/apps).

  - `event` (string)
    Must have the value `ice`.
    Enum: "ice", "ace", "dice", "pie", "notify"

  - `callResourceUrl` (string)
    The path of the API resource.

  - `userRate` (object)

  - `userRate.currencyId` (string)

  - `userRate.amount` (number)

  - `cli` (string)
    The number that will be displayed to the recipient of the call. To set your own CLI, you may use your verified number or your Dashboard virtual number and add it to the `connectPSTN` SVAML response to the Incoming Call Event request.  It must be in [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537) format.

  - `to` (object)
    Known destination

  - `to.type` (string, required)
    Type `did` for Direct Inward Dialling
    Enum: "did"

  - `to.endpoint` (string, required)
    Number that the caller has called
    Example: +3197121281500

  - `to.type` (string, required)
    Type `userName` used for data endpoints.
    Enum: "username", "Username"

  - `to.endpoint` (string, required)
    For type `userName` the value is the username for a data endpoint.
    Example: myUserName

  - `to.type` (string, required)
    Type `number` used for PSTN endpoints.
    Enum: "number", "Number"

  - `to.endpoint` (string, required)
    If the type is `number` the value of the endpoint is a phone number.
    Example: +12125550123

  - `to.type` (string, required)
    Type `sip` for SIP infrastructures.
    Enum: "sip"

  - `to.endpoint` (string, required)
    For type `sip` the value is the SIP address for a SIP endpoint.
    Example: +19876543210@example.sip.sinch.com

  - `domain` (string)
    Can be either `pstn` for PSTN endpoint or `mxp` for data (app or web) clients.
    Enum: "pstn", "mxp", "PSTN", "MXP"

  - `duration` (integer)
    The duration of the call in seconds.

  - `rdnis` (string)
    The redirected dialled number identification service.

  - `callHeaders` (array)
    If the call is initiated by a Sinch SDK client, call headers are the headers specified by the *caller* client. Read more about call headers [here](https://developers.sinch.com/docs/voice/api-reference/call-headers).

  - `callHeaders.key` (string)
    The call header key of the key value pair.

  - `callHeaders.value` (string)
    The call header value of the key value pair.

  - `event` (string)
    Must have the value `ace`.
    Enum: "ace"

  - `amd` (object)
    If [Answering Machine Detection](https://developers.sinch.com/docs/voice/api-reference/amd_v2) (AMD) is enabled, this object contains information about whether the call was answered by a machine.

  - `amd.status` (string)
    The determination by the system of who answered the call.
    Enum: "machine", "human", "notsure", "hangup"

  - `amd.reason` (string)
    The reason that the system used to determine who answered the call.
    Enum: "longgreeting", "initialsilence", "beep", "n/a"

  - `amd.duration` (integer)
    The length of the call.
    Example: 3

  - `event` (string)
    Must have the value `dice`.
    Enum: "dice"

  - `reason` (string)
    The reason the call was disconnected.
    Enum: "N/A", "ESTABLISHED", "OTHERPEERANSWERED", "TIMEOUT", "CALLERHANGUP", "CALLEEHANGUP", "BLOCKED", "MANAGERHANGUP", "NOCREDITPARTNER", "CLIENTNETWORK", "CONGESTION", "GENERALERROR", "CANCEL", "USERNOTFOUND", "CALLBACKERROR"

  - `result` (string)
    Contains the result of a call.
    Enum: "N/A", "ANSWERED", "BUSY", "NOANSWER", "FAILED"

  - `from` (string)
    Information about the initiator of the call.

  - `callHeaders` (array)
    If the call was initiated by a Sinch SDK client, call headers are the headers specified by the *caller* client. Read more about call headers [here](https://developers.sinch.com/docs/voice/api-reference/call-headers/).

  - `event` (string)
    Must have the value `notify`.
    Enum: "notify"

  - `type` (string)
    The type of information communicated in the notification.

  - `destination` (string)
    Used in some types of events, it presents the destination of the generated recording or transcription files.

  - `custom` (string)
    An optional parameter containing notification-specific information.

## Request examples:

  - `PIE Example` (unknown)
    An example of a Prompt Input Event.

## Response 200:

  - `200` (unknown)
    The Prompt Input Event (PIE) can accept a valid SVAML object in response.

## Response 200 fields (application/json):

  - `instructions` (array)
    The collection of instructions that can perform various tasks during the call. You can include as many instructions as necessary.

  - `instructions.name` (string, required)
    The `name` property. Must have the value `playFiles`.
    Enum: "playFiles"

  - `instructions.ids` (array, required)
    The IDs of the files which will be played. These can be a URL to a file, SSML commands using the `#ssml[]` element, or text using the `#tts[]` element.
    Example: ["#ssml[Thank you for calling Sinch!]"]

  - `instructions.locale` (string)
    If using SSML or TTS, this is a required field. The voice and language you want to use for the text-to-speech message. This can either be defined by the ISO 639 locale and language code or by specifying a particular voice. Supported languages and voices are detailed [here](https://developers.sinch.com/docs/voice/api-reference/voice-locales).
    Example: en-US

  - `instructions.name` (string, required)
    The `name` property. Must have the value `say`.
    Enum: "say"

  - `instructions.text` (string)
    Contains the message that will be spoken. Default maximum length is 600 characters. To change this limit, please contact support.
    Example: Hello, thank you for calling Sinch!

  - `instructions.locale` (string)
    The voice and language you want to use for the text-to-speech message. This can either be defined by the ISO 639 locale and language code or by specifying a particular voice. Supported languages and voices are detailed [here](https://developers.sinch.com/docs/voice/api-reference/voice-locales).
    Example: en-US

  - `instructions.name` (string, required)
    The `name` property. Must have the value `sendDtmf`.
    Enum: "sendDtmf"

  - `instructions.value` (string)
    A string that determines the DTMF tones to play to the callee when the call is picked up.
Valid characters are: `0-9`, `#`, and `w`. `w` renders a 500ms pause. For example, the string `ww1234#w#`, plays a 1 second pause, the DTMF tones for `1`, `2`, `3`, `4`, and `#`, followed by a 500ms pause and finally the `#` tone.
This is useful if the callout destination requires a conference PIN code or an extension. If there is a calling party, it will hear progress while the DTMF is sent.
    Example: ww1234#w#

  - `instructions.name` (string, required)
    The `name` property. Must have the value `setCookie`.
    Enum: "setCookie"

  - `instructions.key` (string)
    The name of the cookie you want to set.
    Example: cookie_name

  - `instructions.value` (string)
    The value of the cookie you want to set.
    Example: cookie_value

  - `instructions.name` (string, required)
    The `name` property. Must have the value `startRecording`.
    Enum: "startRecording"

  - `instructions.options` (object)

  - `instructions.options.destinationUrl` (string)

  - `instructions.options.credentials` (string)

  - `instructions.options.format` (string)

  - `instructions.options.notificationEvents` (boolean)

  - `instructions.options.transcriptionOptions` (object)

  - `instructions.options.transcriptionOptions.enabled` (boolean)

  - `instructions.options.transcriptionOptions.locale` (string)

  - `instructions.name` (string, required)
    The `name` property. Must have the value `stopRecording`.
    Enum: "stopRecording"

  - `action` (object)
    The action that will control the call. Each SVAML object can only include one action.

  - `action.name` (string, required)
    The name property. Must have the value `hangup`.
    Enum: "hangup"

  - `action.name` (string, required)
    The name property. Must have the value `continue`.
    Enum: "continue"

  - `action.name` (string, required)
    The name property. Must have the value `connectPstn`.
    Enum: "connectPstn"

  - `action.number` (string)
    Used to override where PSTN call is connected. If not specified, the extension the client called is used.
    Example: +461234567890

  - `action.locale` (string)
    Specifies the locale. Uses the language code according to `ISO 639`, a dash (`-`), and a country code according to `ISO 3166-1 alpha-2`. If not specified, the default locale of `en-US` is used.

  - `action.maxDuration` (integer)
    The max duration of the call in seconds (max 14400 seconds). If the call is still connected at that time, it will be automatically disconnected.
    Example: 3000

  - `action.dialTimeout` (integer)
    The max duration the call will wait in ringing unanswered state before terminating with `TIMEOUT/NO ANSWER` on PSTN leg and `NA/BUSY`on MXP leg.
    Example: 3000

  - `action.cli` (string)
    Used to override the CLI (or caller ID) of the client. The phone number of the person who initiated the call is shown as the CLI. To set your own CLI, you may use your verified number or your Dashboard virtual number.
    Example: private

  - `action.suppressCallbacks` (boolean)
    If enabled, suppresses [ACE](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ace) and [DICE](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/dice) callbacks for the call.
    Example: false

  - `action.dtmf` (string)
    A string that determines the DTMF tones to play to the callee when the call is picked up.
Valid characters are: `0-9`, `#`, and `w`. `w` renders a 500ms pause. For example, the string `ww1234#w#`, plays a 1 second pause, the DTMF tones for `1`, `2`, `3`, `4`, and `#`, followed by a 500ms pause and finally the `#` tone.
This is useful if the callout destination requires a conference PIN code or an extension. If there is a calling party, it will hear progress while the DTMF is sent.
    Example: ww1234#w#

  - `action.indications` (string)
    The locale's tone to play while ringing.
    Enum: "at", "au", "bg", "br", "be", "ch", "cl", "cn", "cz", "de", "dk", "ee", "es", "fi", "fr", "gr", "hu", "il", "in", "it", "lt", "jp", "mx", "my", "nl", "false", "nz", "ph", "pl", "pt", "ru", "se", "sg", "th", "uk", "us", "tw", "ve", "za"

  - `action.amd` (object)
    The `amd` object enables [Answering Machine Detection](https://developers.sinch.com/docs/voice/api-reference/amd_v2) (AMD) and sets whether it works synchronously or asychronously.

  - `action.amd.enabled` (boolean)
    If set to `true`, then AMD is enabled for the call.
    Example: true

  - `action.amd.async` (boolean)
    Determines if AMD is set to operate synchronously or asychronously. Refer to the [AMD](https://developers.sinch.com/docs/voice/api-reference/amd_v2) documentation for more information about this setting.

  - `action.name` (string, required)
    The name property. Must have the value `connectConf`.
    Enum: "connectConf"

  - `action.conferenceId` (string, required)
    The unique identifier of the conference. Shouldn't exceed 64 characters.
    Example: myConference

  - `action.conferenceDtmfOptions` (object)
    Options to control how DTMF signals are used by the participant in the conference. For information on how to use this feature, read more [here](https://developers.sinch.com/docs/voice/api-reference/conference-dtmf).

  - `action.conferenceDtmfOptions.mode` (string)
    Determines what DTMF mode the participant will use in the call.
    Enum: "ignore", "forward", "detect"

  - `action.conferenceDtmfOptions.maxDigits` (integer)
    The maximum number of accepted digits before sending the collected input via a PIE callback. The default value is `1`. If the value is greater than `1`, the PIE callback is triggered by one of the three following events:
- No additional digit is entered before the `timeoutMills` timeout period has elapsed.
- The `#` character is entered.
- The maximum number of digits has been entered.

  - `action.conferenceDtmfOptions.timeoutMills` (integer)
    The number of milliseconds that the system will wait between entered digits before triggering the PIE callback. The default value is `3000`.

  - `action.moh` (string)
    Means "music on hold". If this optional parameter is included, plays music to the first participant in a conference while they're alone and waiting for other participants to join. If `moh` isn't specified, the user will only hear silence while alone in the conference.
    Enum: "ring", "music1", "music2", "music3"

  - `action.name` (string, required)
    The name property. Must have the value `connectSip`.
    Enum: "connectSip"

  - `action.destination` (object, required)
    The type of device and number or endpoint to call.

  - `action.destination.type` (string, required)
    Type `sip` for SIP infrastructures.
    Enum: "sip"

  - `action.destination.endpoint` (string, required)
    For type `sip` the value is the SIP address for a SIP endpoint.
    Example: +19876543210@example.sip.sinch.com

  - `action.transport` (string)
    An optional parameter to specify the SIP transport protocol. If unspecified, UDP is used.
    Enum: "UDP", "TCP", "TLS"

  - `action.callHeaders` (array)
    [Private SIP headers](https://developers.sinch.com/docs/voice/api-reference/sip-trunking/#receiving-calls-from-sinch-platform-to-your-sip-infrastructure) to send with the call.

  - `action.callHeaders.key` (string)
    The call header key of the key value pair.

  - `action.callHeaders.value` (string)
    The call header value of the key value pair.

  - `action.moh` (string)
    Means "music on hold". If this optional parameter is included, plays music to the connected participant if the SIP call is placed on hold. If `moh` isn't specified and the SIP call is placed on hold, the user will only hear silence while during the holding period .
    Enum: "ring", "music1", "music2", "music3"

  - `action.name` (string, required)
    The name property. Must have the value `runMenu`.
    Enum: "runMenu"

  - `action.barge` (boolean)
    'Barging' means that the user can press a DTMF digit before the prompt has finished playing. If a valid input is pressed, the message will stop playing and accept the input. If `barge` is disabled, the user must listen to the entire prompt before input is accepted. By default, barging is enabled.

  - `action.locale` (string)
    The voice and language you want to use for the text-to-speech message. This can either be defined by the ISO 639 locale and language code or by specifying a particular voice. Supported languages and voices are detailed [here](https://developers.sinch.com/docs/voice/api-reference/voice-locales). If using the `enableVoice` to enable voice detection, the `locale` property is required in order to select the input language.
    Example: en-US

  - `action.mainMenu` (string)
    Selects the menu item from the `menus` array to play first.
    Example: main

  - `action.enableVoice` (boolean)
    Enables voice detection. If enabled, users can say their answers to prompts in addition to entering them using the keypad.

  - `action.menus` (array)
    The list of menus available. The menu with the `id` value of `main` will always play first. If no menu has an `id` value of `main`, an error is returned.

  - `action.menus.id` (string, required)
    The identifier of a menu. One menu must have the ID value of `main`.
    Example: main

  - `action.menus.mainPrompt` (string)
    The main voice prompt that the user hears when the menu starts the first time.
You can use text-to-speech using the `#tts[]` element, SSML commands using the `#ssml[]` element, pre-recorded messages, or URL references to external media resources. You can use multiple prompts by separating each prompt with a semi-colon (`;`). If multiple prompts are used, they will be played in the order they are specified, without any pauses between playback. For external media resources, you can use an `#href[...]` or directly specify the full URL. Check the [Supported audio formats](https://developers.sinch.com/docs/voice/api-reference/supported-audio-formats) section for more information.

  - `action.menus.repeatPrompt` (string)
    The prompt that will be played if valid or expected DTMF digits are not entered.
You can use text-to-speech using the `#tts[]` element, SSML commands using the `#ssml[]` element, pre-recorded messages, or URL references to external media resources. You can use multiple prompts by separating each prompt with a semi-colon (`;`). If multiple prompts are used, they will be played in the order they are specified, without any pauses between playback. For external media resources, you can use an `#href[...]` or directly specify the full URL. Check the [Supported audio formats](https://developers.sinch.com/docs/voice/api-reference/supported-audio-formats) section for more information.

  - `action.menus.repeats` (integer)
    The number of times that the `repeatPrompt` is played.
    Example: 3

  - `action.menus.maxDigits` (integer)
    The maximum number of digits expected for a user to enter. Once these digits are collected, a [Prompt Input Event (PIE)](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/pie) is triggered containing these digits.

  - `action.menus.timeoutMills` (integer)
    Determines silence for the purposes of collecting a DTMF or voice response in milliseconds. If the timeout is reached, the response is considered completed and will be submitted.

  - `action.menus.maxTimeoutMills` (integer)
    Sets a limit for the maximum amount of time allowed to collect voice input.

  - `action.menus.options` (array)
    The set of options available in the menu.

  - `action.menus.options.dtmf` (string, required)
    A DTMF digit the user can press to trigger the configured action.
    Example: 1

  - `action.menus.options.action` (string, required)
    Determines which action is taken when the DTMF digit is pressed. The following values are accepted:
- If you want to navigate to another menu, use `menu(value)`.
- If you want to perform another behavior you have coded in your application, use `return (value)`, where `(value)` is the name of the method you want to execute.
    Example: menu(sub)

## Response 200 examples:

  - `Hangup response SVAML` (unknown)
    A SVAML response to an Prompt Input Event that plays a message to the callee and then hangs up the call.