REST API - Voice Webhooks

Modified on Thu, 2 Jul, 2020 at 5:59 PM

Voice Webhooks

Voice webhooks allow you to receive HTTP callbacks at user-defined URIs when call events occur.

You can receive webhooks using GET or POST.

Events

The following events are supported.

Event Name	Description
Call.Initiate	Fired at the start of a phone call.
Call.Complete	Fired at the end of a phone call.

Parameters

Common Parameters

The following parameters are present in every request.

Parameter	Type	Description	Call.Initiate	Call.Complete
Action	string	Value will be: `Webhook`	X	X
Event	string	The name of the event as per the event table.	X	X
Account.Sid	string	The secure identifier of the applicable account.	X	X
Property.Sid	string	The secure identifier of the applicable property.	X	X
Property.Name	string	The name of the property. For website properties, this will be the domain name.	X	X
Property.Type	string	The type of property this represents. The value currently can only be `Site`	X	X

Call Parameters

The following parameters are present in every phone call related request.

Parameter	Type	Description	Call.Initiate	Call.Complete
Call.Sid	string	The secure identifier of the call.	X	X
Call.StartDate	string	The date and time of the call in UTC and formatted as `yyyy-MM-dd HH:mm:ss`.	X	X
Call.From	string	The caller ID of the caller in E164 (international) format. Can be `anonymous` if the caller ID is unavailable.	X	X
Call.From.Country	string	The country where the call originated. Will be blank if unknown.	X	X
Call.From.Region	string	The region/state where the call originated. Will be blank if unknown or not applicable.	X	X
Call.From.City	string	The city where the call originated. Will be blank if unknown.	X	X
Call.To	string	The phone number that was dialled in E164 (international) format.	X	X
Call.To.Type	string	The type of phone number that was dialled. Can either be `Static` or `Dynamic`	-	X
Call.To.Name	string	The name of the phone number as configured in the account.	X	X
Call.Duration	integer	The duration of the call in seconds.	-	X
Call.Disposition	string	The outcome of the call.	-	X
Call.Recording.Uri	string	Optional. The URI of the call recording.	-	X
Call.Endpoint	string	Optional. The endpoint phone number where the call was transferred in E164 (international) format.	X	X
Call.Survey.Type	string	Optional. The call type selected in the agent survey.	-	X
Call.Survey.Value	integer	Optional. The value entered in the agent survey.	-	X
Call.Survey.Custom1	string	Optional. The selection in the agent survey mapped to custom field 1.	-	X
Call.Survey.Custom2	string	Optional. The selection in the agent survey mapped to custom field 2.	-	X
Call.Survey.Custom3	string	Optional. The selection in the agent survey mapped to custom field 3.	-	X
Call.Survey.UniqueCode	string	Optional. The unique code played in the agent survey.	-	X
Call.Prompts.Postcode	string	Optional. A comma-delimited list of postcodes that were entered in the call.	-	X
Call.Prompts.Keys	string	Optional. A comma-delimited list of keys that were entered in the call, including any postcodes.	-	X

Attribution Parameters

The following parameters are present in every request where attribution information is expected.

Parameter	Type	Description	Call.Initiate	Call.Complete
Attribution.Source	string	The "source" attribution parameter. e.g. "bing"	X	X
Attribution.Medium	string	The "medium" attribution parameter. e.g. "organic"	X	X
Attribution.Campaign	string	The "campaign" attribution parameter. e.g. "2019 promo"	X	X
Attribution.Content	string	The "content" attribution parameter. e.g. "variation 1"	X	X

Session Parameters

The following parameters are present in every web-session related request.

Parameter	Type	Description	Call.Initiate	Call.Complete
Session.Traffic.Type	string	The traffic type. Can be: Campaign, Direct, Organic, Referral, or Unattributed.	X	X
Session.Keywords	string	Optional. The search keywords.	X	X
Session.ConversionUri	string	The URI of the page where the event occurred.	X	X
Session.LandingUri	string	The URI of the landing page.	X	X
AnalyticsSession.CustomDimension1	string	Optional.	X	X
AnalyticsSession.CustomDimension1	string	Optional.	X	X

Integration Parameters

The following parameters are present depending on the status and type of integration.

Parameter	Type	Description	Call.Initiate	Call.Complete
Google.Analytics.ClientId	string	Optional. The Google Analytics Universal Client ID. This can be used to push events into Google Analytics Universal.	X	X
Google.AdWords.ClickId	string	Optional. The Google AdWords Click ID. Also known as the GCLID.	X	X

Call Dispositions

The call disposition will have one of the following values.

Value	Description
ANSWERED	The call was transferred to an endpoint which answered.
NO ANSWER	The call attempted a transfer to an endpoint but it did not answer.
BUSY	The call attempted a transfer to an endpoint but the endpoint reported busy.
IVR	The call did not attempt a transfer to an endpoint. This can happen when a caller hangs up during an IVR prompt or before the initiation of a transfer.
FAILED	Something went wrong with the call or the endpoint.