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

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.
uui	(optional) The value of the User-To-User header to send within the initial INVITE. Must include the encoding parameter as specified in RFC 7433. Only base64 and jwt encoding are currently allowed. This value, including the encoding specifier, may not exceed 256 characters.
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. 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"
	}
}

Initiate Event with uui 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",
    "uui"           : "eyJhbGciOiJIUzI1NiJ9.WyJoaSJd.-znkjYyCkgz4djmHUPSXl9YrJ6Nix_XvmlwKGFh5ERM;encoding=jwt,aGVsbG8gd29ybGQ;encoding=base64",
	"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"
}