Initiate Event

The Initiate event is fired when an inbound call is received for an application. Sent to the URL specified in the application.

Expected response

HTTP/1.1 200
Content-Type: application/xml; charset=utf-8

<Response>
    <!-- BXML verbs to process in the call -->
</Response>

Properties

Property Description
eventType The event type, value is initiate.
eventTime The approximate UTC date and time when the event was generated by the Bandwidth server, in ISO 8601 format. This may not be exactly the time of event execution.
accountId The user account associated with the call.
applicationId The id of the application associated with the call.
to The phone number that received the call, in E.164 format (e.g. +15555555555).
from The provided identifier string of the caller used in the from field of the original call.
direction The direction of the call; can only be inbound. The direction never changes.
callId The call id associated with the event.
callUrl The URL of the call associated with the event.
startTime Time the call was started, in ISO 8601 format.
diversion (optional) Information from the most recent Diversion header, if any.
identity (optional) The value of the Identity header from the inbound invite request. Only present if the account is configured to forward this header.
stirShaken (optional) The verification status provided by Bandwidth STIR/SHAKEN implementation.

Diversion properties

The Diversion header is parsed into a JSON object. Note that the attributes vary depending on the parameters received in the SIP header. Some common attributes and values are listed below.

Note: it is not an exhaustive list. Your application must be tolerant to unlisted attributes and values.

Property Description
origTo Indicates the last telephone number that the call was diverted from. This attribute is always present.
reason The diversion reason. Common values: unknown, user-busy, no-answer, unavailable, unconditional, time-of-day, do-not-disturb, deflection, follow-me, out-of-service, away.
screen no if the number was provided by the user, yes if the number was provided by the network.
privacy off or full.
counter The number of diversions that have occurred.
limit The maximum number of diversions allowed for this session.

STIR/SHAKEN properties

The Bandwidth STIR/SHAKEN implementation will verify the information provided in the inbound invite request Identity header. The verification status is included in the Initiate event stirShaken property as follows.

Property Description
verstat (optional) The verification status indicating whether the verification was successful or not. Possible values are TN-Verification-Passed and TN-Verification-Failed.
attestationIndicator (optional) The attestation level verified by Bandwidth. Possible values are A (full), B (partial) or C (gateway).
originatingId (optional) A unique origination identifier.

More information: Understanding STIR/SHAKEN

Example: Initiate event with Diversion information

POST http://[External server URL]
{
    "eventType"     : "initiate",
    "eventTime"     : "2019-06-20T15:56:11.554Z",
    "accountId"     : "55555555",
    "applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086",
    "from"          : "+15551112222",
    "to"            : "+15553334444",
    "direction"     : "inbound",
    "callId"        : "c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d",
    "callUrl"       : "https://voice.bandwidth.com/api/v2/accounts/55555555/calls/c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d",
    "startTime"     : "2019-06-20T15:54:22.234Z",
    "diversion": {
        "origTo"    : "+15558884444",
        "reason"    : "unavailable",
        "privacy"   : "off",
        "unknown"   : "unknownValue"
    }
}

results matching ""

    No results matching ""