Agent SDK

Install

// add to project via yarn or npm
yarn add @ringcentral/engage-voice-agent

// then import into your project
import AgentSDK from '@ringcentral/engage-voice-agent';

Note: If you are using an amd loader like webpack, you may need to define a custom load function for the engage-voice-agent

import AgentSDK from 'imports-loader?define=>false!@ringcentral/engage-voice-agent';

// OR

module: {
    rules: [
        ...,
        {
            // force Agent SDK to load without amd. this provides
            // the library with the window context
            test: require.resolve('@ringcentral/engage-voice-agent'),
            use: ['imports-loader?define=>false']
        }
    ]
}

Initialization

var config = {
    authHost: window.location.origin,
    callbacks: callbacks,
    allowMultiSocket: true,
    isSecureSocket: ENV_VARS.isSecureSocket,
};
Lib = new AgentLibrary(config);

Documentation

The publicly exposed methods in this library are documented in the /doc directory.

Getting Started

There are a few steps needed to authenticate and sign in an agent before being able to send and receive requests from the Engage Voice system.

1. Initialize the AgentSDK, pass in any needed callback functions and the host for the engage-auth server. If you need to set up an unsecured web socket, use localTesting = true flag. The AgentLibrary constructor expects an object of callbacks that are set up as key/value pairs, the key representing the name of the callback and the value being the callback function. var Lib = new AgentLibrary({callbacks: objectOfCallbacks, authHost: "http://localhost:81", localTesting: true});
2. Authenticate the AgentSDK in one of three ways: username/password (legacy), RC JWT (API use), Engage Auth Access Token (Single Point of Entry). Each of these authenticate methods will return a list of available agents associated with the provided credentials. - authenticateAgentWithUsernamePassword(username, password, platformId, callback) - authenticateAgentWithRcAccessToken(rcAccessToken, tokenType, callback) - authenticateAgentWithEngageAccessToken(token, callback)
3. Initialize the socket. Pass in the agent id to the openSocket() method for the agent you wish to sign in. This call will return all the config options for the selected agent. Lib.openSocket(agentId, callback);
4. Log in the agent by passing in the selected configuration settings

   Lib.loginAgent(dialDest, queueIds, chatIds, skillProfileId, dialGroupId, updateFromAdminUI, isForce, callback);

• Note, in production, authHost should be set to https://engage.ringcentral.com
• Note, in production, isSecureSocket should be set to true (as boolean, not string), unless running on non SSL browser location.
• Note, allowMultiSocket is optional. It should be set to true (as boolean, not string) if you want to initialize Library in Multi Socket mode. If this param is not specified, then its default value will be false.
• Note, Multi socket is not supported for Agent-js, hence it should not be passed as true for Agent-js.

Setting Callbacks

The callbacks object passed to your AgentLibrary can provide functions to call on that message type. Passing the callback attribute to the Library instance config will initialize them for the library.

const callbacks = {
loginPhase1Response: loginPhase1Response,
…<more callbacks defined here>
}

…
function loginPhase1Response(response) {

}

Most Agent sdk methods also allow passing a callback as the final attribute ex.

Lib.getAgentConfig(agentConfigCallback); // callback is an optional param
Function agentConfigCallback(response) { … }

To set callbacks after initialization use

Lib.setCallback(type, callback);
Lib.setCallbacks(type, callback);

• Note: this will override any other callback associated with this function

Login

Engage auth js is a helper library that manages the user auth session and state. These examples will utilize engage auth js.

SSO (stage 1)

1. Lib.authenticateAgentWithEngageAccessToken(EngageAuth.Session.getAccessToken( ));
2. Continue to post auth config

Username/password (stage 1)

1. Initialize the agent library (as noted above)
2. Gather username and password and correct platform id for the user (c01/aws80, c02/aws82, or lab env)
3. Using engage auth, execute a legacyLogin
   1. EngageAuth.Session.legacyLogin({Username, Password, platformId: ..., loginType: ‘admin’ | ‘agent’})
4. Once legacyLogin.then resolves, you can get the user details
   1. const deets = EngageAuth.Session.getUserDetails();
5. Lib.authenticateAgentWithUsernamePassword(username, password, platformId, callback);
6. Continue to post auth config

Post auth configure (stage 2)

These steps are the same, regardless of SSO or Legacy login

1. We can now authenticate with agent library
   1. Listen for the authenticateResponse callback
      • If valid Lib.openSocket(agentId, function(result) { … } );
   2. Listen for the loginPhase1Response callback
      • Phase 1 login is now complete, continue to phase 2, use the following properties from the loginPhase1Response to configure our agents session
      • response.inboundSettings
      • response.outboundSettings
      • response.chatSettings
      • response.agentSettings
      • response.scriptSettings
      • response.agentPermissions
      • response.applicationSettings
      • response.agentPermissions.defaultAutoAnswerOn
2. You can now configure the agent session -
   1. dial dest using a RC extension will be “RC_PHONE”
   2. dial dest using a RC integrated softphone will be “RC_SOFTPHONE”
   3. Available ids are provided on the loginPhase1Response
   4. Lib.loginAgent(dialDest, queueIds, chatIds, skilProfileId, dialGroupId, updateFromAdminUi, isForce, function(loginResult){ if(loginResult.status === "SUCCESS") { // yay } } _ updateFromAdminUi - is true when a login update is triggered from the admin ui. _ isForce - used when a login record exists, if true, this new login will override the old one.
3. You are now logged in

Setup softphone

Prerequisites: Lib config, agent login and config complete

If login type === ‘integrated’ and using the web rtc softphone

1. Lib.sipInit();
2. Lib.sipRegister();
   1. Listen for sipRegisteredCallback

Multi Socket

Prerequisites: Lib config.

In order to enable multi socket at first time login, you just need to pass the allowMultiSocket flag as true while initializing the Agent Library. The Stage 2 login method will use this flag internally.

Post multi socket login for first time login, you need to use the below method for every new multi socket connection (new socket) for the same login.

1. Lib.multiLoginRequest(); (callback) // callback function or multiSocketResponse
   1. Listen for multiSocketResponse

Off-hook

Prerequisites: Lib config, agent login, config & softphone setup complete

1. Lib.offhookInit(callback) // callback function or offhookInitResponse on lib
   1. Listen for offhookInitResponse
      • Status === ‘OK’ = success!
      • Else, off hook error
2. To end off-hook session Lib.offhookTerm()
   1. Listen for offhookTermNotification

Agent state

Prerequisites: Lib config, agent login and config complete

Agent state list is available on loginPhase1Response.agent_states.agent_state

1. Lib.setAgentState(agentState, agentAuxState);
   1. Listen for agentStateResponse
      • Status === ‘OK’

New Call

Prerequisites: Lib config, agent login and config complete & agent in available state

• Listen for newCallNotification
• Listen for addSessionNotification

Note: The order of these notifications is not guaranteed. You may receive an addSession before the new call is delivered. Or you may receive a new call before the add session is sent. It’s best to keep this in mind.

Inbound call

Prerequisites: Lib config, agent login and config complete, agent in available state & softphone type is ‘integrated’

Auto answer is a flag tracked in your app. You can manage when the call is answered based on your logic.

On-hook

1. Listen for offhookInitResponse
2. Continue to off-hook logic

Off-hook

1. Listen for sipRingingNotification
2. To answer or after a prompt to confirm answer - Lib.sipAnswer()
   1. Listen for newCallNotification
      • New call notification contains queue, outdial_disposition, lead and additional baggage objects
   2. Listen for addSessionNotification
      • Add session is sent once the agent is added to the call
3. To reject the call - Lib.sipReject()

Outbound call

Prerequisites: Lib config, agent login and config complete & softphone setup complete

On-hook

1. Off-hook does not exist,
   1. Lib.offhookInit()
   2. Listen for offhookInitResponse then continue request
2. Continue to off-hook step

Off-hook

1. Lib.manualOutdial(destination, callerId, ringTime, countryId, gateId);
   1. Destination is the number you are dialing
   2. Caller id is what the customer will see, must be valid for legal reasons
   3. ringTime [optional] how long will the call ring. Default 30 sec.
   4. countryId [optional] country the call originates from. Default ‘USA’
   5. gateId [optional] gate to associate the call with.
2. Listen for newCallNotification
   1. New call notification contains queue, outdial_disposition, lead and additional baggage objects
3. Listen for addSessionNotification
   1. Add session is sent once the agent is added to the call

Transfer

Prerequisites: Lib config, agent login and config complete, softphone setup complete & active call. Call must have allowTransfer = true

Phonebook entries can be found on the currentCall transferPhoneBook

Warm (stay on the line)

• Request Lib.internationalWarmXfer(dialDest, callerId, customSipHeaders, countryId, callback);
• Listen for warmXferResponse
• To cancel Lib.warmXferCancel(xferDest);

Cold (hangup my session)

• Request Lib.internationalColdXfer(dialDest, callerId, customSipHeaders, countryId, callback);
• Listen for coldXferResponse, endCallNotification

Direct agent transfer

Prerequisites: Lib config, agent login and config complete, softphone setup complete & active call. Call must have allowTransfer = true and allowDirectAgentTransfer = true

Get list

• Request Lib.directAgentXferList(callback); // inline callback optional
• Listen for directAgentTransferListResponse or callback

Warm (stay on the line)

• Request Lib.warmDirectAgentXfer(targetAgentId);
• Listen for directAgentTransferNotification
• To cancel Lib.cancelDirectAgentXfer(xferDest);

Cold (hangup my session)

• Request Lib.coldDirectAgentXfer(targetAgentId);
• Listen for endCallNotification

Direct voicemail

• Request Lib.voicemailDirectAgentXfer(targetAgentId);

Call controls

Prerequisites: Lib config, agent login and config complete, softphone setup complete & active call.

• Hold - current call allowHold must be true
  • Request - Lib.hold();
  • Callback - holdResponse
• Mute
  • Request - Lib.sipToggleMute(currentState: true|false); // pass in false to unmute, true to mute
• Record - current call agentRecording.agentRecording must be true
  • Request - Lib.record(recordingState, callback); // state is true|false
  • Lib.pauseRecord(recordingState, callback); // state is true|false
    • Pause recording timing needs to be tracked in your application
• Requeue - current call allowRequeue must be true
  • Request - Lib.requeueCall(queueId, skillId, stayOnCall, callback);
• Transfer - current call allowTransfer must be true
  • Warm - Lib.internationalWarmXfer(dialDest, callerId, customSipHeaders, countryId)
    • To cancel Lib.warmXferCancel(dialDest)
  • Cold - Lib.internationalColdXfer(dialDest, callerId, customSipHeaders, countryId)
    • This will end your call
• Hangup
  • Request - Lib.hangup(sessionId); // session to hangup, omit to hangup all

Dispositions

Prerequisites: Lib config, agent login and config complete, softphone setup complete & active call.

Dispositions for the call are available on currentCall.outdialDispositions.dispositions

Lib.dispositionCall(uii, dispId, notes, isCallback, callbackDTS, contactForwardNum, script, externId, leadId, requestId);

• uii - call unique id
• dispId - disposition selected
• notes - agent notes associated to the disposition
• isCallback - true|false, if we are setting up a callback
• callbackDTS - if isCallback is true, the dts you would like to set the callback for
• contactForwardNum - number for contact forwarding
• Script - script data to save for this disposition
  • [ { label: "", externId: "", leadUpdateColumn: ""} ]

Only for Outbound Dispositions

• externId - external id associated to the lead
• leadId - lead id associated to the disposition
• requestId - request id associated with a preview fetched lead

Hangup

Prerequisites: Lib config, agent login and config complete, softphone setup complete & active call.

Provide the session id you would like to hang up. You can hang up legs other than yours on the call if this is a transfer. If you omit the session id, all legs of the call will be hung up.

1. Lib.hangup(sessionId); // end call
2. Listen for endCallCallback

WebRTC SIP

Requests

• Lib.sipInit(); // setup SipJS session
• Lib.sipAnswer();
• Lib.sipRegister(); // register session
  • Callback - sipRegisteredNotification
• Lib.sipHangUp(); // end call AND close sip session
• Lib.sipReject(); // reject a pending (ringing) call
• Lib.sipSendDTMF(dtmf) // dtmf number 0-9
• Lib.sipToggleMute(state) // current state - true|false. Pass in true to mute, false to unmute

Callbacks

• sipConnectedNotification
  • Will notify once offhook session is connected
• sipEndedNotification
• sipMuteResponse
• sipUnmuteResponse
• sipRegisteredNotification
  • Sip registration session is active
• sipUnregisteredNotification
• sipRegistrationFailedNotification
• sipRingingNotification
• sipDialDestChangedNotification
• sipSwitchRegistrarNotification

Call history

Call history is not managed in the agent sdk. To track history, keep a record of all newcall and add session packets. Update these records on call end.

Callbacks

Agent SDK - Callbacks can be setup during the AgentLibrary initialization via the config object.

Requests

Refer to the auto generated sdk docs found in AgentLibrary/doc/index.html