Skip to main content

Initiate

The Initiate event is fired when an inbound call is received for a Telephone Number on your Account. It is sent to the URL specified in the application associated with the location (sip-peer) that the called telephone number belongs to.

Request Parameters

PropertyDescription
eventTypeThe event type, value is initiate.
eventTimeThe 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.
accountIdThe user account associated with the call.
applicationIdThe id of the application associated with the call.
toThe phone number that received the call, in E.164 format (e.g. +15555555555).
fromThe provided identifier string of the caller used in the from field of the original call.
directionThe direction of the call; can only be inbound. The direction never changes.
callIdThe call id associated with the event.
callUrlThe URL of the call associated with the event.
startTimeTime the call was started, in ISO 8601 format.
diversion(optional) Information from the most recent Diversion header, if any. If present, the value will be a sub-object like "diversion": {"param1": "value1", "param2": "value2"}.
Each diversion parameter gets its own key in the JSON structure, and the keys present and their values will vary depending on the parameters received in the SIP header.

Common Parameters
- origTo: always present. Indicates the last telephone number that the call was diverted from.

Note: for all of the following keys, the values listed are common values, but this list is not exhaustive. Your application must be tolerant of unlisted keys and unlisted values of those keys.
- reason: The reason for the diversion. 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
stirShaken(optional) The verification status provided by Bandwidth's STIR/SHAKEN implementation when verifying the identity header.

Common Parameters
- 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.

Expected Response

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

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

Examples

Initiate Event

POST http://yourUrl.example/initiate
Content-Type: application/json

{
"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"
}

Initiate Event with Diversion Information

POST http://yourUrl.example/initiate
Content-Type: application/json

{
"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"
}
}