Webhooks
The Voxtelesys Voice API provides robust webhook support, enabling your web application to receive real-time notifications for various voice call events. Webhooks allow you to dynamically respond to incoming calls, track call statuses, manage call recordings, and more — all without the need for continuous polling. By integrating webhooks into your application, you can build highly responsive and automated voice solutions tailored to your business needs.
For a general overview of how webhooks work, refer to the Webhooks overview.
Voice Webhooks
For the Voice API, webhooks are triggered in the following scenarios:
-
Incoming Voice Call: This webhook is triggered when someone dials a phone number associated with your Voxtelesys account. You can process the incoming call request within your web application.
-
Status Changes: This webhook is sent after completing an outbound call through Voxtelesys. It provides information about the status of the call.
-
Recording: After a call recording is completed and the audio has been processed into a file, Voxtelesys sends this webhook. It notifies you when the recording status changes, such as when it’s ready for download.
-
VoXML Verbs: The VoXML
<Dial>,<Gather>,<Record>, and<Pay>verbs trigger webhooks when theiractionattribute is specified.
Voice Webhook Payload
When Voxtelesys sends a request to your application to retrieve instructions for how to handle a call, it always includes the following parameters. These parameters are sent as either POST data or URL query parameters, depending on the HTTP method you've configured.
Basic Parameters
| Parameter | Description |
|---|---|
CallSid | A unique identifier for this call, generated by Voxtelesys. |
AccountID | Your Voxtelesys account ID. |
TrunkID | Your Voxtelesys trunk group ID. |
From | The phone number that initiated the call. |
To | The phone number of the called party. |
CallStatus | A descriptive status for the call. |
ApiVersion | The version of the Voxtelesys API used to handle this call. |
Direction | A string describing the direction of the call: inbound, outbound-api, outbound-dial |
CallerName | The caller name CNAM |
ParentCallSid | A unique identifier for the call that created this leg. This parameter is not passed if this is the first leg of a call. |
Vars | Set if there are any custom variables set on the call. |
Geographical Data (Optional)
Voxtelesys also attempts to look up geographical data based on the To and From phone numbers. If available, Voxtelesys will send the following additional parameters:
| Parameter | Description |
|---|---|
FromCity | The city of the caller |
FromState | The state or province of the caller |
FromZip | The postal code of the caller |
FromCountry | The country of the caller |
ToCity | The city of the called party |
ToState | The state or province of the called party |
ToZip | The postal code of the called party |
ToCountry | The country of the called party |
These parameters will be sent when Voxtelesys makes a request to your application. This could happen when an inbound call comes to your Voxtelesys number or after a VoXML verb has completed and you've provided an action URL for Voxtelesys to retrieve the next set of instructions. Depending on the situation, additional variables may also be sent.