Page History

LiveVox REST APIs:

Details regarding each API referenced below can be found in the LiveVox Session, Call Control and Contact APIs on the LiveVox Developer portal.

LiveVox Developer Portal access:

https://docs.livevox.com/display/DP/Developer+Portal

username: prospect

password: Livevox12345^

Start with “LiveVox API Overview”-> ”LiveVox API Quick Start Guide”

Virtual Agent Management and Data Collection

Introduction

This document provides a model for integrating LiveVox with an artificial intelligence speech vendor (AI Vendor). The document is intended for AI Vendors and their clients.

LiveVox REST APIs 

You can find details about each API that is referenced in this document in the Call Control API, Contact API, and Session API sections of the LiveVox Developer Portal.

Virtual Agent Management and Data Collection

A set of virtual agents is configured on the LiveVox Portal. A one-to-one ratio of virtual agents exists for calls handled by the AI Vendor. The client must plan for the appropriate number of virtual agents to handle their call volume, in addition to determining the maximum number of simultaneous calls for each service that is connected to the AI Vendor.

1. The AI Vendor must ensure that the virtual agents are ready on the platform. To do so:

   1. Obtain the virtual agent session ID.

      Info
      POST https://{{APIHost}}/session/login Header:

...

1. 1. API token provided by LiveVox Body example: {"clientName": "Training2", "userName": "AI Vendor1", "password": "xxxx", "agent": "true"}

      
      

   2. Add the

...

1. 1. virtual agent to the appropriate

...

1. 1. service.

      Info
      POST https://{{APIHost}}/callControl/agent/service/join?serviceId=XXXXXX&phoneNumber=899XXXXXXX (see below for more info related assigning agent 899#s) Header:

...

1. 1. Session ID from

...

1. 1. 1a

      
      

   2. Set the

...

1. 1. virtual agent to the Ready state.

      Info
      POST https://{{APIHost}}/callControl/agent/status/ready Header:

...

1. 1. Session ID from 1a

      
      

      Note
      The LiveVox session ID expires after two hours of inactivity. If a virtual agent does not change the state (

...

1. 1. that is, receive a call), the

...

1. 1. session ID

...

1. 1. expires.

...

1. 1. Therefore, the client must move virtual agents in the Ready state to the Not Ready state and then back to the Ready state, every hour.

...

1. 1. Virtual agents must be logged on only during the defined open hours of the LiveVox call center

...

1. 1. . If

...

1. 1. they are expected to receive calls outside

...

1. 1. the open hours, additional planning related to routing and other factors, such as maintenance windows

...

1. 1. , must be considered. Virtual

...

1. 1. agent support during closed hours

...

1. 1. must be addressed as part of phase 2+

...

1. 1. .

      
      

2. When a call is routed to

...

1. the virtual agent through the LiveVox standard routing services, LiveVox

...

1. conferences the AI Vendor using a unique

...

1. 899 number for the agent.

...

1. This unique number passes as part of the

...

1. invite. This allows the AI

...

1. Vendor to identify the

...

1. calls associated with each agent.

...

1.  

   An example is as follows.
   

   LiveVox Virtual Agent	INVITE

...

1. Virtual_Agent_1	INVITE sip:+18990000001@XX.XXX.XX.XX:5070 SIP/2.0^M
   Virtual_Agent_2	INVITE sip:+18990000002@XX.XXX.XX.XX:5070 SIP/2.0^M
   Virtual_Agent_3	INVITE sip:+18990000003@XX.XXX.XX.XX:5070 SIP/2.0^M

See below for a detailed INVITE example.

...

1. 
   

2. To obtain additional data associated with the call, the AI Vendor can access the screen pop data that is typically presented to a human agent. The data can include the customer account number, customer phone number, customer address, and so on. Screen pop data is configured through the LiveVox Portal of the client.

   Info
   To obtain the screen pop data for the call: https://{{APIHost}}/callControl/agent/screenpop Header: Session ID from 1a

   
   

3.  If the AI Vendor collects additional data that

...

1. must be associated with

...

1. a contact, use the LiveVox Update Contact API.

...

1. Info
   PUT https://{{APIHost}}/contact/contacts/{account} Header:

...

1. Session ID from

...

If the AI Vender collects call specific data that should be screen popped to a Human Agent, use the LiveVox AI Integration App(AIA) API.

1. Update the AIA

2. URL is client specific (will be provided as part of the client specific project)

3. A Separate Specification document will be provided for the Method, Headers, Parameters and Body of the AIA

4. Data fields include:

   1. transactionId
   2. sessionId
   3. ani
   4. accountNumber
   5. nextAction
   6. callOutcome
   7. lvresult
   8. Other1
      thru
   9. Other20

If the Client wants to route non LiveVox validated Consumers to the AI Vendor, AI Vendor can collect info and Update Contact via ‘Update Contact API’ or Create a Contact via ‘Create Contact API’

...

1. 1a Body: See the LiveVox Developer Portal for details and work with the client to determine which fields in Contact Manager

...

1. must be updated

   
   

2. If the client wants to route non-LiveVox validated consumers to the AI Vendor, the AI Vendor can collect data and update the contact through the Update Contact API or create a contact through the Create Contact API.
   

   Info
   To update the contact: PUT https://{{APIHost}}/contact/contacts/{account} Header: Session ID from 1a Body: See the LiveVox Developer Portal for options to update

   
   

3. When the bot completes a call with the customer, and if the call need not be routed to a human agent, the AI Vendor must set the term code for the call and move the virtual agent back to the Ready state. If a transfer to a human agent is required, the AI Vendor must transfer the call to a human agent using the LiveVox Phonebook feature, set a term code for the call, and move the virtual agent back to the Ready state.

   1. To set a term code for the call and move the virtual agent back to the Ready state, the AI Vendor must set a specific term code for the call. To complete this step, use the following APIs.

      Info
      To obtain the TransID, SessionID, and ServiceID for the call: POST https://{{APIHost}}/callControl/agent/status Header: Session ID from 1a Body example: {"stateChangedAfter": "1573809480000"}

      
      

      Info
      To obtain the list of term codes available for the call: GET

1. 1. https://{{APIHost}}/

...

1. 1. callControl/

...

1. 1. agent/termCode?serviceId={

...

1. 1. serviceId}

...

1. 1. Header:

...

1. 1. Session ID from 1a

      
      

      Info
      To assign the agent term code:

1. 1. PUT https://{{APIHost}}/callControl/

...

1. 1. agent/

...

1. 1. call/termCode Header:

...

1. 1. Session ID from

...

When the AI Vendor completes the call, a term code will be assigned to the call indicating either the call is done, or the call needs to be transferred to a Human Agent:

1. 1. 1a Body example: {"callTransactionId": "108821676850", "callSessionId": "U5EF8FT5DFC07F9@10.101.21.216", "termCodeId": "101416228", "phoneDialed":"2134634007", "moveAgentToNotReady": "false"}

      
      

   2. To transfer the call to a human agent, set a term code for the call and move the virtual agent back to the Ready state. The AI vendor must use the phonebook transfer process to transfer the call to the appropriate group of human agents and then set a specific term code for the call.
      To complete this step, use the following APIs.

      Info
      To obtain the TransID, SessionID, and Service ID

...

1. 1. for the call: POST https://{{APIHost}}/callControl/agent/status Header:

...

1. 1. Session ID from

...

1. 1. 1a Body example: {"stateChangedAfter": "1573809480000"}

      
      

      Info
      To obtain the phonebooks available to the virtual agent: GET https://{{APIHost}}/callControl/agent/phonebook/ext?serviceId={serviceId} Header: Session ID from 1a

      
      

      Info
      To complete the phonebook transfer: POST https://{{APIHost}}/callControl/agent/conference/phonebook?lineNumber=ACD Header: Session ID from 1a Body example: {"phoneBookId": "2237", "phoneBookContactId": "24590"}

...

1. 1. 
      

      Info
      To leave the phonebook transfer: POST https://{{APIHost}}/callControl/agent/conference/leave Header: Session ID from 1a

      
      

      Info
      To obtain the list of term codes available for the call: GET https://{{APIHost}}/callControl/agent/termCode?serviceId={serviceId} Header: Session ID from 1a

      
      

      Info
      To assign the agent term

...

1. 1. code: PUT https://{{APIHost}}/callControl/agent/call/termCode Header:

...

1. 1. Session ID from

...

1. 1. 1a Body example: {"callTransactionId": "108821676850", "callSessionId": "U5EF8FT5DFC07F9@10.101.21.216", "termCodeId": "101416228", "phoneDialed":"2134634007", "moveAgentToNotReady": "false"}

...

Customer Portal Config Requirements

...

1. Create

...

1. or configure virtual agents.

   Note
   LiveVox is required to configure virtual agents.

   
   

2. Set the

...

1. Service ACD mode to

...

1. Agent Call

...

1. Out.
2. Set Service Groups for

...

1. virtual agents to LONGEST_AVAILABLE_

...

1. AGENT.
2. Create

...

1. term codes to support transfers to

...

1. human agents.
2. Create term codes for virtual agents to complete calls.
3. Load contacts into the Contact Manager.
4. Update

...

1. contact flows to validate

...

1. inbound customer calls against the Contact Manager.
2. Configure the virtual agent desktop with the data required for the virtual agent screen popup.
3. Configure the agent phonebook to allow the virtual agent to transfer calls to a human agent.

Sample Session Initiation Protocol (SIP) INVITE