# Notification Event

This is the general callback used to send notifications. It's a POST request to the specified calling callback URL.

If there is no response to the callback within the timeout period, the notification is discarded.

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

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

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

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

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

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

## Request examples:

  - `Recording finished notification` (unknown)
    An example of a Notify Event that a recording is finished.

  - `Recording available notification` (unknown)
    An example of a Notify Event that a recording is available for download.

  - `Answering Machine Detection finished notification` (unknown)
    An example of a Notify Event issued after the AMD engine has finished detection.

  - `Answering Machine Beep detected` (unknown)
    An example of a Notify Event issued after the AMD engine has finished detection and the beep is detected, signalling the machine is ready to gather the message.

## Response 200:

  - `200` (unknown)
    Return a 200 status to indicate that the data was received successfully