# Answered Call Event

This callback is made when the call is picked up by the callee (person receiving the call). It's a POST request to the specified calling callback URL. Look here for allowed [instructions](https://developers.sinch.com/docs/voice/api-reference/svaml/instructions) and [actions](https://developers.sinch.com/docs/voice/api-reference/svaml/actions).
If there is no response to the callback within the timeout period, the call is connected.
If you have [Answering Machine Detection](https://developers.sinch.com/docs/voice/api-reference/amd_v2) (AMD) enabled, the `amd` object will also be present on ACE callbacks.
Note: ACE Callbacks are not issued for InApp Calls (`destination:` `username`), only PSTN and SIP calls.

Endpoint: POST ace
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 `ace`.
    Enum: "ace"

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

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

  - `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 `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 `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 `pie`.
    Enum: "pie"

  - `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"

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

## Response 200:

  - `200` (unknown)
    The Answered Call Event (ACE) requires 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 `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 `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 `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 Answered Call Event that plays a message to the callee and then hangs up the call.

  - `Play menu response SVAML` (unknown)
    A SVAML response to an Answered Call Event that plays a menu to the callee.