Agent assist API

This page outlines the technical specifications of the Agent Assist API protocol. For guidance on integrating this API with your bot, see Agent assist.

An agent assist client application allows a contact center agent, to receive real time insights about the conversation they are currently having with a customer. Once the user logs in, and is in a phone conversation, they can request the assistance of a bot. The bot essentially listens in on the conversation, picking up on patterns and phrases, and sends useful data to the client that can be displayed on the user’s screen. This data can include, for example, the call transcript, boxed responses to customer questions, information pulled from a database (based on customer ID), questions to ask, pictures, audio, and more.

Different bots can be written for different types of tasks. The agent assist client application development must be done in conjunction with the bot development. The agent assist client application can request assistance from a single bot for all purposes, or request the assistance from several bots.

AudioCodes agent assist service connects to the AudioCodes VoiceAI Connect, which in turn is connected to the AudioCodes SBC, text-to-speech, speech-to-text, and the bot service. Many different speech and bot frameworks are supported. For more information see VoiceAI Connect documentation.

The agent assist API is based on socket.io. Socket.io has a JavaScript client as well as implementations in several other languages. For more information about how to develop a socket.io client, click here.

This feature is applicable only to VoiceAI Connect Enterprise (Version 3.4 and later).

API overview

Authentication

The agent starts by opening a socket.io connection with the service.

Authentication with the service is performed using a token and will be passed at the socket.io connection

Example:

const socket = io('https://vaicCenterIp', { 
path: '/agentAssist/socket.io',
query: {
	token: 'thisisthetoken'
}
});

The token is configured in the agentAssist section in VoiceAI Connect configuration.

Sending and receiving messages

Once a socket is open, the client can emit events, and listen for events from the server.

For each outgoing message, the client emits an event with the message name, and a single parameter which is a JSON object.

socket.emit('message name', JSON object);

Example:

socket.emit('stopBotAssist', {
    callKey: activeCallKey,
    botName: activeBotName
});

The client can listen for incoming events, execute a callback, where the event is the message name, and a single parameter which is a JSON object.

socket.on('message name', callback);

Example:

socket.on('callEnded', obj => {
	const {callKey, src} = obj;
	// handle the message
});

API messages

init

Once the WebSocket is established, the agent sends an init message over the WebSocket.

Parameter:

agentId (string): Used by the service to identify the agent if the WebSocket has restarted.
callsNotification (Boolean): (optional) Set to true to receive notifications for active calls for this agent.
for clients that are not aware of the active calls and the callKeys on their own. This option can be disallowed by setting the parameter disableCallNotifications in the Agent assist section.

Example:

{
   "agentId":"+97239761234"
}

initResponse

On init request, the service will return this message to the agent.

Parameters:

activeCalls: This field is present if callsNotification is set to "true" in the init request. A list of the currently active calls, where each call contains:

callKey (string): The ID of the call used by the SBC to identify the session. In Genesys, this is the UUID received by the agent in the call notification from the contact center. In Microsoft Teams, this is the callKey received from the service which in turn received it from the SBC in the start call CDR.
activeBotAssists (array of objects): A list of all of objects representing the agent assist sessions on this call (the list is empty if there are no sessions).

Each object contains a botName (string).
botName (optional string): The name of the bot. If not sent, the value configured in the parameter botName will be used.

Example:

{
   "activeCalls":[
    {
         "callKey":"14e334973660494882111k54406rmwp",
         "activeBotAssists": [{
         "botName": ""
      }]
    }
  ]
}

getBotAssist

The client application will send this message to start an agent assist session.

Parameters:

callKey (string): The ID of the call used by the SBC to identify the session. In Genesys, this is the UUID received by the agent in the call notification from the contact center. In Microsoft Teams, this is the callKey received from the service which in turn received it from the SBC in the start call CDR.
metadataToBot: Any other information about the call that should be passed to the bot, in JSON format.
botName (optional string): The name of the bot. If not sent, the value configured in the parameter botName will be used.

Example:

{
   "callKey":"14e334973660494882111k54406rmwp",
   "metadataToBot":{
      "agentName":"John Smith"
   },
   "botName":"technicalSupportAssist"
}

stopBotAssist

The agent will send this message once the user clicks the end agent assist button.

Parameters:

callKey (string): The ID of the call used by the SBC to identify the session. In Genesys, this is the UUID received by the agent in the call notification from the contact center. In Microsoft Teams, this is the callKey received from the service which in turn received it from the SBC in the start call CDR.
botName (optional string): The name of the bot. If not sent, the value configured in the parameter botName will be used.

Example:

{
   "callKey":"14e334973660494882111k54406rmwp",
   "botName":"technicalSupportAssist"
}

botAssistSessionStarted

VoiceAI Connect sends the client this message indicating that the agent assist session has been successfully started.

Parameters:

callKey (string): The ID of the call used by the SBC to identify the session. In Genesys, this is the UUID received by the agent in the call notification from the contact center. In Microsoft Teams, this is the callKey received from the service which in turn received it from the SBC in the start call CDR.
botName (string): The name of the bot. If not sent, the value configured in the parameter botName will be used.

Example:

{
   "callKey":"14e334973660494882111k54406rmwp",
   "botName":"technicalSupportAssist"
}

botAssistSessionFailed

VoiceAI Connect shall send the client this message if it has failed to set up the agent assist session.

Parameters:

callKey (string): The ID of the call used by the SBC to identify the session. In Genesys, this is the UUID received by the agent in the call notification from the contact center. In Microsoft Teams, this is the callKey received from the service which in turn received it from the SBC in the start call CDR.
botName (optional string): The name of the bot. If not sent, the value configured in the parameter botName will be used.
reason (string): The reason that the session failed to initialize.

Example:

{
   "callKey":"14e334973660494882111k54406rmwp",
   "botName":"technicalSupportAssist"
   "reason":"SipRec request timed out"
}

botAssistSessionEnded

VoiceAI Connect sends this client this message indicating that the agent assist session has ended.

Parameters:

callKey (string): The ID of the call used by the SBC to identify the session. In Genesys, this is the UUID received by the agent in the call notification from the contact center. In Microsoft Teams, this is the callKey received from the service which in turn received it from the SBC in the start call CDR.
botName (string): The name of the bot. If not sent, the value configured in the parameter botName will be used.

Example:

{
   "callKey":"14e334973660494882111k54406rmwp",
   "botName":"technicalSupportAssist"
}

metadata

The bot can send Metadata (containing a JSON object) to the session manager. VoiceAI Connect forwards the metadata received from the bot to the client in this message.

If the bot wishes to send binary data (e.g., image files) it can encode the data, and send it encapsulated in the JSON object.

Parameters:

callKey (string): The ID of the call used by the SBC to identify the session. In Genesys, this is the UUID received by the agent in the call notification from the contact center. In Microsoft Teams, this is the callKey received from the service which in turn received it from the SBC in the start call CDR.
botName (string): The name of the bot. If not sent, the value configured in the parameter botName will be used.
data (json): The data of the metadata event received from the bot, in json format.

Example:

{
   "callKey":"14e334973660494882111k54406rmwp",
   "botName":"technicalSupportAssist"
   "data":{
      "participant":"participant-1",
      "text":"I would like a pizza"
   }
}

callStarted

If callsNotification is set to true in the init request, this message is sent to the client when a call starts.

Parameters:

callKey (string): The ID of the call used by the SBC to identify the session. In Genesys, this is the UUID received by the agent in the call notification from the contact center. In Microsoft Teams, this is the callKey received from the service which in turn received it from the SBC in the start call CDR.
src (string): The source URI of the call.

Example:

{
   "callKey":"14e334973660494882111k54406rmwp",
   "src":"+97239764444"
}

callEnded

If callsNotification is set to true in the init request, this message is sent to the client wrequest an agent

Parameters:

callKey (string): The ID of the call used by the SBC to identify the session. In Genesys, this is the UUID received by the agent in the call notification from the contact center. In Microsoft Teams, this is the callKey received from the service which in turn received it from the SBC in the start call CDR.
src (string): The source URI of the call.

Example:

{
   "callKey":"14e334973660494882111k54406rmwp",
   "src":"+97239764444"
}