Introduction
Webhooks facilitate real-time communication between websites or applications by allowing one application to send HTTP requests, including payload data, to another application when a predefined event or trigger occurs.
With the Voiso Webhooks feature, developers can subscribe to call events, offering numerous advantages for custom integrations and automated tasks:
- Real-time updates: Receive instant notifications or data updates when specific call events occur.
- Simplified integration: Transmit data between applications seamlessly without continuous polling.
- Efficient resource usage: Data is only sent when an event occurs, reducing unnecessary network traffic and server load.
- Automation: Streamline workflows and enhance overall efficiency in application development and management.
The Webhooks page
Add and manage your webhooks using the Webhooks page. For more information, refer to Webhooks in the Voiso Documentation Portal.
Webhook response
When coding your response to the webhook, note that Voiso expects an HTTP 200 status code to indicate a successful operation. If no response is received, Voiso assumes that the request timed out or an error occurred.
Supported events
The Webhooks feature supports the following call events:
| Event | Description | Webhook |
|---|---|---|
| outbound.call.answered | A contact answers an outbound call. | Outbound calls |
| outbound.call.hangup | An outbound call ends. | Outbound calls |
| outbound.call.ended | An outbound call is completed. | Outbound calls |
| inbound.call.answered | An agent answers an inbound call. | Inbound calls |
| inbound.call.hangup | An inbound call ends. | Inbound calls |
| inbound.call.ended | An inbound call is completed. | Inbound calls |
| dialer.call.answered | An agent is connected to a Dialer call answered by a contact. | Outbound dialer campaigns |
| dialer.call.hangup | A Dialer call ends. | Outbound Dialer campaigns |
| dialer.call.ended | A Dialer call is completed. | Outbound Dialer campaigns |
| message.received | An agent receives a new reply in an ongoing conversation. | Digital interactions |
| conversation.ended | A digital conversation is archived (ends), and an agent assigns a wrap-up code. | Digital interactions |
Voiso webhook structure
Voiso webhooks employ the POST method with the HTTP request protocol when sending data. Requests are structured as follows:
| Parameter | Description | Data type |
|---|---|---|
| name | The name of the webhook. | string |
| event | One of the supported Voiso contact center events. Refer to Supported events. | string |
| object | The name of the contact center object associated with the webhook data. Objects include call, message, and conversation |
string |
| timestamp | The timestamp indicates when the event triggering the webhook occurred. | string |
| secret | Each webhook should have a unique contact center key, secret key, or user-defined token. The external system uses this key to validate the authenticity of the webhook. | string |
| contact_center_id | The UUIS of your contact center. | string |
| data | The payload data contained within the webhook. The structure and content of the payload vary depending on the specific event and object involved. It can be a simple or nested structure, accommodating different scenarios. Refer to individual webhook descriptions for payload details. | Simple or nested structure |
Common call event objects
The webhooks for outbound, inbound, and dialer events use one or more of the following common objects:
- Call object
- Duration object
- Wrap-up code object
- Campaign object
Call object
| Parameter | Description | Data type | Notes |
|---|---|---|---|
| id | UUID of the call | string | |
| type | The type of call. | string | Valid values are: outbound, click to call, queue callback, scheduled callback,inbound, and dialer. |
| start_time | The start time of the call. | string | A timestamp in ISO 8601 format (UTC time zone). |
| end_time | The end time of the call. | string | A timestamp in ISO 8601 format (UTC time zone). |
| agent_start_time | The timestamp when the agent was connected. | string | A timestamp in ISO 8601 format (UTC time zone). |
| duration | Details of the duration of the call. | structure | Refer to the Duration object table. |
| disposition | A disposition code to specify whether the interaction was successfully completed, and if not, why not. | string | Refer to Disposition codes. |
| queue | The name of the inbound queue. | string | For inbound calls. |
| end_reason | And end reason code to specify why the interaction was terminated. | string | Refer to End reasons. |
| script | The name of the inbound flow script. | string | |
| flow | The name of the inbound flow. | string | Refer to Flows. |
| calling_number | The ANI of the call. | string | In E.164 format without the preceding '+'. For example: 447414992548 |
| called_number | The DNIS of the call. | string | In E.164 format without the preceding '+'. For example: 447414992548 |
| wrapup_code | The call outcome specified by the agent. | structure | Refer to the Wrap-up code object table. For information about wrap-up codes, refer to Wrap-up codes. |
| notes | Call notes added by the agent. | string | Up to 280 characters. Refer to Call notes |
| ext_user_id | The external CRM ID for the contact. | string | The account_id received from the Start call API. |
| cdr_url | The URL of the call recording. | string | |
| campaign | Information about the Dialer campaign associated with the call. | structure | Refer to the Campaign object table. |
Duration object
The Duration object is a sub-object of the Call object.
| Parameter | Description | Data type | Notes |
|---|---|---|---|
| total | The total duration of the call in seconds. | number | |
| queue_time | The duration, in seconds, that the inbound call remained in the queue. | number | |
| dialing_time | The duration, in seconds, from when a call was initiated until the call was successfully connected. | number | |
| dialer_waiting | The duration, in seconds, that the Dialer was in the waiting state. | number | |
| talk_time | The duration, in seconds, of the interaction Talk Time. | number | |
| hold_time | The duration, in seconds, that the interaction was in the Hold state. | number | |
| postcall_time | The duration, in seconds, that the call was in the Postcall state. | number |
Wrap-up code object
The Wrap-up code object is a sub-object of the Call object. Refer to Wrap-up codes.
| Parameter | Description | Data type | Notes |
|---|---|---|---|
| code | The wrap-up code value. | string | |
| description | The text description of the wrap-up code. | string |
Agent object
The Agent object is a sub-object of the Call object. Refer to Users.
| Parameter | Description | Data type | Notes |
|---|---|---|---|
| id | The ID of the agent who handled the interaction. | number | |
| name | The name of the agent who handled the interaction. | string | |
| The sign-in email address of the agent who handled the interaction. | string | ||
| extension | The contact center extension of the agent who handled the interaction. | string |
Campaign object
The Campaign object is a sub-object of the Call object. Refer to Campaigns page.
| Parameter | Description | Data type | Notes |
|---|---|---|---|
| id | The ID of the Dialer campaign. | number | |
| name | The name of the Dialer campaign. | string | |
| is_live | Whether or not the Dialer campaign is of type Live. | string | Supported values are True or False. |
Common digital interaction event objects
The webhooks for digital events use one or more of the following common objects:
- Conversation object
- SLA object
- Agent object
- Message object
- Content Data objects
- Contact object
- Channel object
Conversation object
| Parameter | Description | Data type | Notes |
|---|---|---|---|
| id | The UUID of the conversation. | string | |
| wrapup_code | The interaction outcome specified by the agent. | structure | For information about wrap-up codes, refer to Wrap-up codes. |
| queue | The name of the inbound queue. | string | For inbound interactions. |
| disposition | A disposition code to specify whether the interaction was successfully completed, and if not, why not. | string | The following values are supported: waiting, active, archived, and initiated. Refer to Disposition codes. |
| source | The source of the interaction. | string | The following values are supported: user and business. |
| cpc | The cost of the interaction. | number | In US dollars. |
| sla | Service level agreement values. | object | Refer to the SLA object table. |
SLA object
The SLA object is a sub-object of the Conversation object.
| Parameter | Description | Data type | Notes |
|---|---|---|---|
| time_to_first_response | The time in seconds to the first agent's response to the interaction. | number | |
| time_to_resolution | The time in seconds to the first resolution/archive of the interaction. | number | |
| time_to_reply | The average waiting time in seconds for the agent's replies | number |
Agent object
| Parameter | Description | Data type | Notes |
|---|---|---|---|
| id | The ID of the agent who handled the interaction. | number | |
| name | The name of the agent who handled the interaction. | string | |
| The sign-in email address of the agent who handled the interaction. | string | ||
| extension | The contact center extension of the agent who handled the interaction. | string |
Message object
| Parameter | Description | Data type | Notes |
|---|---|---|---|
| id | The UUID of the message. | string | |
| conversation_id | The UUID of the associated conversation. | string | Refer to the Conversation object table. |
| reference_id | The Reference Message ID. | string | |
| content_type | The content type of the message. | string enum | Supported values are: text, image, document, video, voice, and audio. Refer to the Content Data objects table. |
Content Data objects
The Content Data objects are sub-objects of the Message object.
The following table describes the content data for text messages:
| Parameter | Description | Data type | Notes |
|---|---|---|---|
| text | The body of the message sent by the contact. | string |
The following table describes the content data for media messages (attachments):
| Parameter | Description | Data type | Notes |
|---|---|---|---|
| filename | The name of the attached file. | string | |
| size | The size in bytes of the attached file. | number | |
| caption | Text description of the file. | string | Can be empty. |
| media_url | The URL of the attached file. | string |
Contact object
| Parameter | Description | Data type | Notes |
|---|---|---|---|
| id | The ID number of the channel in your contact center. | number | |
| username | The username or name of the contact. | string | |
| channel_identifier | The identifier of the channel. | string | This can be a username or a UUID. |
Channel object
| Parameter | Description | Data type | Notes |
|---|---|---|---|
| id | The UUID of the channel in your contact center. | string | |
| type | The digital channel type. | string | Supported values include: whatsapp, chat, facebook, instagram, telegram, and viber. |
| name | The name associated with the channel in your contact center. | string |