# Prompt Input Event

This callback is triggered as a result of a 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 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

## Request fields (application/json):

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

  - `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).

  - `body` (object) — one of (discriminator: event):
    - iceRequest:
      - `callResourceUrl` (string)
        The path of the API resource.
      - `userRate` (object)
      - `userRate.currencyId` (string,null)
      - `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) — one of (discriminator: type):
        Known destination
        - did:
          - `type` (string, required)
            Type did for Direct Inward Dialling
            Enum: "did"
          - `endpoint` (string, required)
            Number that the caller has called
            Example: "+3197121281500"
        - username:
          - `type` (string, required)
            Type userName used for data endpoints.
            Enum: "username", "Username"
          - `endpoint` (string, required)
            For type userName the value is the username for a data endpoint.
            Example: "myUserName"
        - Username:
          - `type` (string, required)
            Type userName used for data endpoints.
            Enum: same as `type` in "username" (2 values)
          - `endpoint` (string, required)
            For type userName the value is the username for a data endpoint.
            Example: "myUserName"
        - number:
          - `type` (string, required)
            Type number used for PSTN endpoints.
            Enum: "number", "Number"
          - `endpoint` (string, required)
            If the type is number the value of the endpoint is a phone number.
            Example: "+12125550123"
        - Number:
          - `type` (string, required)
            Type number used for PSTN endpoints.
            Enum: same as `type` in "number" (2 values)
          - `endpoint` (string, required)
            If the type is number the value of the endpoint is a phone number.
            Example: "+12125550123"
        - sip:
          - `type` (string, required)
            Type sip for SIP infrastructures.
            Enum: "sip"
          - `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"
      - `originationType` (string)
        Can be either pstn for PSTN endpoint or mxp for data (app or web) clients.
        Enum: same as `domain` in "iceRequest" (4 values)
      - `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.
    - aceRequest:
      - `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
    - diceRequest:
      - `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"
      - `debit` (object)
      - `debit.currencyId` (string,null)
      - `debit.amount` (number)
      - `userRate` (object)
      - `to` (object) — one of (discriminator: type):
        Known destination
        - did:
          - `type` (string, required)
            Type did for Direct Inward Dialling
            Enum: same as `type` in "did" (1 values)
          - `endpoint` (string, required)
            Number that the caller has called
            Example: "+3197121281500"
        - username:
          - `type` (string, required)
            Type userName used for data endpoints.
            Enum: same as `type` in "username" (2 values)
          - `endpoint` (string, required)
            For type userName the value is the username for a data endpoint.
            Example: "myUserName"
        - Username:
          - `type` (string, required)
            Type userName used for data endpoints.
            Enum: same as `type` in "username" (2 values)
          - `endpoint` (string, required)
            For type userName the value is the username for a data endpoint.
            Example: "myUserName"
        - number:
          - `type` (string, required)
            Type number used for PSTN endpoints.
            Enum: same as `type` in "number" (2 values)
          - `endpoint` (string, required)
            If the type is number the value of the endpoint is a phone number.
            Example: "+12125550123"
        - Number:
          - `type` (string, required)
            Type number used for PSTN endpoints.
            Enum: same as `type` in "number" (2 values)
          - `endpoint` (string, required)
            If the type is number the value of the endpoint is a phone number.
            Example: "+12125550123"
        - sip:
          - `type` (string, required)
            Type sip for SIP infrastructures.
            Enum: same as `type` in "sip" (1 values)
          - `endpoint` (string, required)
            For type sip the value is the SIP address for a SIP endpoint.
            Example: "+19876543210@example.sip.sinch.com"
      - `duration` (integer)
        The duration of the call in seconds.
      - `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/).
      - `callHeaders.key` (string)
        The call header key of the key value pair.
      - `callHeaders.value` (string)
        The call header value of the key value pair.
    - notifyRequest:
      - `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.
      - `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: same as `amd.status` in "aceRequest" (4 values)
      - `amd.reason` (string)
        The reason that the system used to determine who answered the call.
        Enum: same as `amd.reason` in "aceRequest" (4 values)
      - `amd.duration` (integer)
        The length of the call.
        Example: 3

## Response 200 fields (application/json):

  - `instructions` (array) — one of (discriminator: name):
    The collection of instructions that can perform various tasks during the call. You can include as many instructions as necessary.
    - playFiles:
      - `name` (string, required)
        The name property. Must have the value playFiles.
        Enum: "playFiles"
      - `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!]"]
      - `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"
    - say:
      - `name` (string, required)
        The name property. Must have the value say.
        Enum: "say"
      - `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!"
      - `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"
    - sendDtmf:
      - `name` (string, required)
        The name property. Must have the value sendDtmf.
        Enum: "sendDtmf"
      - `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#"
    - setCookie:
      - `name` (string, required)
        The name property. Must have the value setCookie.
        Enum: "setCookie"
      - `key` (string)
        The name of the cookie you want to set.
        Example: "cookie_name"
      - `value` (string)
        The value of the cookie you want to set.
        Example: "cookie_value"
    - startRecording:
      - `name` (string, required)
        The name property. Must have the value startRecording.
        Enum: "startRecording"
      - `options` (object)
      - `options.destinationUrl` (string)
      - `options.credentials` (string)
      - `options.format` (string)
      - `options.notificationEvents` (boolean)
      - `options.transcriptionOptions` (object)
      - `options.transcriptionOptions.enabled` (boolean)
      - `options.transcriptionOptions.locale` (string)
    - stopRecording:
      - `name` (string, required)
        The name property. Must have the value stopRecording.
        Enum: "stopRecording"

  - `action` (object) — one of (discriminator: name):
    The action that will control the call. Each SVAML object can only include one action.
    - hangup:
      - `name` (string, required)
        The name property. Must have the value hangup.
        Enum: "hangup"
    - continue:
      - `name` (string, required)
        The name property. Must have the value continue.
        Enum: "continue"
    - connectPstn:
      - `name` (string, required)
        The name property. Must have the value connectPstn.
        Enum: "connectPstn"
      - `number` (string)
        Used to override where PSTN call is connected. If not specified, the extension the client called is used.
        Example: "+461234567890"
      - `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.
      - `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
      - `dialTimeout` (integer)
        The max duration the call will wait in ringing unanswered state before terminating with TIMEOUT/NO ANSWER on PSTN leg and NA/BUSYon MXP leg.
        Example: 3000
      - `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"
      - `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.
      - `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#"
      - `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"
      - `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.
      - `amd.enabled` (boolean)
        If set to true, then AMD is enabled for the call.
        Example: true
      - `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.
    - connectConf:
      - `name` (string, required)
        The name property. Must have the value connectConf.
        Enum: "connectConf"
      - `conferenceId` (string, required)
        The unique identifier of the conference. Shouldn't exceed 64 characters.
        Example: "myConference"
      - `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).
      - `conferenceDtmfOptions.mode` (string)
        Determines what DTMF mode the participant will use in the call.
        Enum: "ignore", "forward", "detect"
      - `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.
      - `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.
      - `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"
    - connectSip:
      - `name` (string, required)
        The name property. Must have the value connectSip.
        Enum: "connectSip"
      - `destination` (object, required)
        The type of device and number or endpoint to call.
      - `destination.type` (string, required)
        Type sip for SIP infrastructures.
        Enum: same as `type` in "sip" (1 values)
      - `destination.endpoint` (string, required)
        For type sip the value is the SIP address for a SIP endpoint.
        Example: "+19876543210@example.sip.sinch.com"
      - `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
      - `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"
      - `transport` (string)
        An optional parameter to specify the SIP transport protocol. If unspecified, UDP is used.
        Enum: "UDP", "TCP", "TLS"
      - `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.
      - `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.
      - `callHeaders.key` (string)
        The call header key of the key value pair.
      - `callHeaders.value` (string)
        The call header value of the key value pair.
      - `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: same as `moh` in "connectConf" (4 values)
    - runMenu:
      - `name` (string, required)
        The name property. Must have the value runMenu.
        Enum: "runMenu"
      - `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.
      - `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"
      - `mainMenu` (string)
        Selects the menu item from the menus array to play first.
        Example: "main"
      - `enableVoice` (boolean)
        Enables voice detection. If enabled, users can say their answers to prompts in addition to entering them using the keypad.
      - `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.
      - `menus.id` (string, required)
        The identifier of a menu. One menu must have the ID value of main.
        Example: "main"
      - `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.
      - `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.
      - `menus.repeats` (integer)
        The number of times that the repeatPrompt is played.
        Example: 3
      - `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.
      - `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.
      - `menus.maxTimeoutMills` (integer)
        Sets a limit for the maximum amount of time allowed to collect voice input.
      - `menus.options` (array)
        The set of options available in the menu.
      - `menus.options.dtmf` (string, required)
        A DTMF digit the user can press to trigger the configured action.
        Example: "1"
      - `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)"