Download PDF
Download page Shadow Audio Integration Guide.
Shadow Audio Integration Guide
LiveVox Shadow Audio Package is a real-time audio stream package that allows LiveVox to be integrated with third-party providers of speech analytics (vendors). This document provides a model for such integration and is intended for the vendors.
Prerequisites
Any off-platform recording systems that use LiveVox Shadow Audio must have the following capabilities:
- Support SIP/RTP to stream audio for agents and customers for each connected call.
- Read the SIP header.
Record audio.
LiveVox Shadow Audio simply streams the audio to the recording system.
In addition, the SIP URI must be an IP address that LiveVox can reach.
IPSEC VPN is typically used for network connectivity.
SIP Header
The following table describes the SIP header fields.
The data provided in the SIP header are used for API calls.
Field | Description |
x-transaction-id | Account transaction ID. |
x-session-id | Session ID for the call. This session ID, which is one of the parameters required when requesting the call metadata, is different from the session ID that is related to your API logon (for example, "714b4a68-1b6a-4a39-924d-749e79a59ade"), which is to be included in the header of your API call. |
x-agent-logon-id | Logon ID of the agent who is talking to the caller. |
x-client-id | ID of the client that is associated with the call. |
x-caller-leg | Indicates if the connection is caller leg (1: yes; 0: no). |
x-agent-leg | Indicates if the connection is agent leg (1: yes; 0: no). |
If LiveVox Shadow Audio is set for a service, you will receive an SIP INVITE for any call that is connected to an agent.
An example of the SIP INVITE, where the metadata is highlighted in bold, is as follows.
INVITE sip:111@10.7.18.108 SIP/2.0
To: sip:111@10.7.18.108
Contact: < sip:10.7.18.99:5060 >
Call-ID: 529e6511-0085-00004d7b-745f4be9-fd925b6a@10.7.18.99
CSeq: 18468 INVITE
Content-Length: 850
Content-Type: application/sdp
From: < sip:123@10.7.18.99 >;tag=telstage-18be-529e6511
x-transaction-id: 121212
x-session-id: 123@10.7.18.99
x-skill-id: 21426
x-agent-logon-id: jbrown
x-client-id: 4199
x-caller-leg: 1
x-agent-leg: 0
Allow: INVITE, ACK, CANCEL, BYE, REFER, NOTIFY, OPTIONS, INFO, REGISTER, SUBSCRIBE, MESSAGE
User-Agent: Telurix
Max-Forwards: 70
Via: SIP/2.0/UDP 10.7.18.99:5060;branch=z9hG4bK529e6511-0086-00004d7c-745f4be9-fd925b6a
Call Data
LiveVox public APIs (REST) provide additional call metadata during and after a call for the current day. The metadata uses the session ID, the transaction ID, and the client ID to identify a call.
The password to access the APIs are defined by the client's portal. When logging on to the client's portal, the response body includes the number of days until a password expires (daysUntilPasswordExpires).
APIs
Read In Call Metadata
This API method can be called only when a call is in progress. It gets the call metadata during the call by using the session ID, the transaction ID, and the client ID.
User roles: Sysadmin, Superuser, and Report Admin
Method: GET /realtime/callData/inCall?[client={clientId}&]session={sessionId}&transaction={transactionId}
Parameters
| Path/Query Parameter Name | Variable Name | Type | Mandatory? | Description |
|---|---|---|---|---|
| client | clientId | Integer (ID) | No | ID of the client with which the call is associated. |
| session | sessionId | String | Yes | Session ID of the call to be read. |
| transaction | transactionId | Integer | Yes | Transaction ID of the call to be read. |
Body: None
Response Code: 200 OK
LiveVox Shadow Audio is configured within the client's portal at the service level. A service is where the agents log on and to which LiveVox routes calls. A client can have multiple services due to which the services could be split across many SIP URIs. However, a service can have only one SIP URI. Therefore, the only way to load balance is to have the SIP 200 OK respond with varying SDP media addresses and ports.
Body
| Key | Type | Mandatory? | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| serviceId | Integer (ID) | Yes | ID of the service with which the call is associated. | ||||||||||||
| callCenterId | Integer (ID) | Yes | ID of the call center that contains the service. | ||||||||||||
| account | String | No | Account number for the call. | ||||||||||||
| totalDue | Decimal | No | Total amount due for the call. | ||||||||||||
| callDirectionOutbound | Boolean | Yes | Indicates if the call is outbound or inbound (true: outbound; false: inbound). | ||||||||||||
| callStartTime | DateTime | Yes | Date and time when the call started. | ||||||||||||
| zipCode | String | No | ZIP Code for the call. | ||||||||||||
| consumer | Array | No | Name of the customer who is associated with the call.
|
Read In Call Metadata
#Request (JSON)
GET /realtime/callData/inCall?client=4199&session=UD6134T518A1E40@10.10.112.81&transaction=21162784221
Host: localhost.com
Content-Type: application/json
Accept: application/json
#Response
200 OK
Content-Type: application/json
{
"consumer": {
"firstName": "John",
"lastName": "Mcgee"
},
"serviceId": 4199,
"callCenterId": 15,
"account": "087764164",
"zipCode": null,
"totalDue": 216.04,
"callDirectionOutbound": true,
"callStartTime": 1368006208000
}
Read Post Call Metadata
Description: This API method can be called only after a call has ended. It gets the call metadata after the call by using the session ID and the transaction ID.
User roles: Sysadmin, Superuser, and Report Admin
Method: GET /realtime/callData/postCall?[client={clientId}&]session={sessionId}&transaction={transactionId}
Parameters
| Path/Query Parameter Name | Variable Name | Type | Mandatory? | Description |
|---|---|---|---|---|
| client | clientId | Integer (ID) | No | ID of the client with which the call is associated. |
| session | sessionId | String | Yes | Session ID of the call to be read. |
| transaction | transactionId | Integer | Yes | Transaction ID of the call to be read. |
Body: None
Response Code: 200 OK
Body
| Key | Type | Mandatory? | Description |
|---|---|---|---|
| serviceId | Integer (ID) | Yes | ID of the service with which the call is associated. |
| callEndTime | DateTime | Yes | Date and time when the call ended. |
| lvResult | String | Yes | LiveVox result name for the call. |
| phoneDialed | Integer | Yes | Phone number dialed or ANI of the caller. |
| termCodeName | String | Yes | Termination code for the call. |
Read Post Call Metadata
#Request (JSON)
GET /realtime/callData/postCall?client=4199&session=UD6134T518A1E40@10.10.112.81&transaction=21162784221
Host: localhost.com
Content-Type: application/json
Accept: application/json
#Response
200 OK
Content-Type: application/json
{
"serviceId": 4199,
"callEndTime": 1368006243000,
"lvResult": "Invalid Phone Number",
"phoneDialed": "6503517508",
"termCodeName": null
}