Awaken Scripting User Guide

Please email helpdesk@awaken.io for omissions or errors.
×
Menu
Search
 
   
   
   
 

Genesys Cloud Helper Functions and SDK

 
When running a Workflow in a system that is currently linked with a Genesys Cloud system (as indicated by seeing the "Genesys Cloud Connected!" Toast when loading the Desktop), a number of helper functions are available for use, as well as easy access to the unmodified Genesys-provided SDK. These allow the Workflow builder to easily perform common tasks, handled automatic actions and processes, and deepen the integration between the systems.
 
Please note that all of these functions are documented for the current release of Scripting. They may be incompatible with older releases of Scripting, or Custom/outdated Controls.
 
Important: all of these functions (except where noted otherwise) are asynchronous and make use of Promises. Promises are a form of JavaScript that allow for subsequent actions to be triggered once their asynchronous actions have been completed, and require a slightly different way of writing and designing your JavaScript. They also do not cause the usual Run Calculations process to occur when they complete, so if assigning a value to a Field then the assignment won't be visible to the agent until JavaScript is next triggered. An easy way to do this is to trigger a JavaScript Button at the end of a Promise, as this will cause the Page to execute JavaScript immediately.
 

How To

All of the items documented below are relative to the root: Script.Plugins.genesyscloud. So, to use the dial function you could use the following code:
Script.Plugins.genesyscloud.dial("01234567890", "MyQueue")
.then(function(response) {
    // The dial function automatically displays a Toast to the agent for the successful dial
 
    // Record the placed call's ID to a field:
    [Call ID] = response.id;
})
.catch(function(response) {
    // Display a Toast to the agent with the error message:
    Script.Toast.Error("Dial Error", response.body ? response.body.message : response.error);
});
 
 
The only function which is executed differently is the genesysSdk function - as this function is used to create instances of Genesys' own SDK, generating these instances require the new operator before the SDK functions can be accessed:
// Create the Genesys SDK master for easy reference later
var GenesysSDK = Script.Plugins.genesyscloud.genesysSdk();
 
// Create any desired SDK namespace objects
var ConversationsAPI = new GenesysSDK.ConversationsApi();
var OutboundAPI = new GenesysSDK.OutboundApi();
 
// Call the Genesys SDK
ConversationsAPI.getConversation("<Conversation GUID>")
.then(response => {
    [Conversation Start] = response.startTime;
    Script.Utils.GetCSObject([Process Conversation]).click();
})
.catch(function(response) {
    // Display a Toast to the agent with the error message:
    Script.Toast.Error("Check Conversation Error", response.body ? response.body.message : response.error);
});
 
 
Note: for the various functions below that include an optional conversationId parameter, this currently only accepts the GUID for a conversation that is currently active and includes the current agent as a participant. If not provided, the parameter will default to using the current value of Script.Data.GetPostDataItem("conversationId") - which is populated automatically when launching an interaction from Genesys Cloud.
 
 

General Functions

These functions cover a range of behaviour, from getting and setting data attached to the interaction in Genesys Cloud, to triggering generic actions or implementing the wider Genesys-provided SDK.
Name
Description
Example Success Response
genesysSdk
This function is distinct from the other functions: it can be used to create an instance of Genesys' own JavaScript SDK for Genesys Cloud, from which any of the SDK functions that Genesys provide can be executed.
 
This function doesn't return a promise, and doesn't accept any parameters. Instead, it is used to allow creation of an instance of each of the Genesys API namespaces. When calling functions within these created API namespaces, they will always return a Promise.
 
Refer to Genesys' JavaScript SDK documentation for Genesys Cloud for the API namespaces and the child functions that can be called. Frequently, this document will need to be cross-referenced with Genesys' master API documentation for Genesys Cloud to see examples of required parameters and returned responses for these functions.
Refer to the Genesys Cloud REST documentation for the called function
checkConversationId
Returns an object containing the details of the specified conversation. Will only return details for a conversation that is both active, and that the currently logged-in user is a participant within.
 
Optional parameters:
  • conversationId (GUID string)
{id: "<GUID>", startTime: "<ISO 8601 datetime string>", participants: [{...}], recordingState: "<State string>", divisions: [{...}], selfUri: "/api/v2/conversations/<GUID>"}
checkQueue
Returns an object containing the GUID for the specified queue. The search is case-insensitive.
 
Required parameters:
  • queueName (Name string)
{queueId: "<GUID>", name: "<Name string>", _type: "queues"}
checkUser
Returns an object containing the details for the specified user. The search is by the username (typically their email), and is case-insensitive.
 
Required parameters:
  • username (Username string)
{id: "<GUID>", name: "<Name string>", division: {...}, chat: {...}, email: "<Email string>", primaryContactInfo: [{...}], addresses: [...], state: "<State string>", username: "<Username string>", version: <Version integer>, acdAutoAnswer: <Boolean>, selfUri: "/api/v2/users/<GUID>"}
disconnect
Disconnects the specified interaction (as long as it is active, and the current agent is a participant), including hanging up the current call or leaving the current chat if applicable. When successful, it will then place the user in ACW within Genesys Cloud.
 
Optional parameters:
  • conversationId (GUID string)
{}
disconnectCallback
Disconnects the specified callback (as long as it is active, and the current agent is a participant), including hanging up the current call or terminating the current preview if applicable. When successful, it will then place the user in ACW within Genesys Cloud.
 
Optional parameters:
  • conversationId (GUID string)
{}
disconnectOnClose
Sets the awakenDisconnectOnClose key within the Script.Data layer to the specified value, controlling whether the current interaction will be disconnected within Genesys Cloud when the current script run is closed.
 
Required parameters:
  • disconnectOnClose (Boolean or "true" / "false")
""
getAgentAttributes
Returns an object containing the attributes for the most recent agent participant within the interaction.
 
Optional parameters:
  • conversationId (GUID string)
{...}
getAttributes
Returns an object containing the attributes for the most recent participant of the specified purpose within the interaction.
 
Required parameters:
  • participantType (Purpose string, e.g. "agent", "customer", "acd")
 
Optional parameters:
  • conversationId (GUID string)
{...}
getCustomerAttributes
Returns an object containing the attributes for the most recent customer participant within the interaction.
 
Optional parameters:
  • conversationId (GUID string)
{...}
getDetails
Returns an object containing basic details of the interaction, including arrays of the participants and division(s).
 
Optional parameters:
  • conversationId (GUID string)
{id: "<GUID>", startTime: "<ISO 8601 datetime string>", address: "<Address string>", participants: [{...}], recordingState: "<State string>", divisions: [{...}], selfUri: "/api/v2/conversations/<GUID>"}
getToken
Returns a string of the currently active OAuth Token used to authenticate requests to the Genesys Cloud SDK. Accepts no parameters.
 
When using all standard library functions, this OAuth token will be supplied and managed automatically. It is only likely to be needed if executing commands directly against Genesys' RESTful API (e.g. if calling API functions directly in a Table control).
"<Token>"
setAgentAttributes
Merges the provided object into the existing attributes object for the most recent agent participant within the interaction. Returns an object that contains the submitted object.
 
Required parameters:
  • attributes (Object)
 
Optional parameters:
  • conversationId (GUID string)
{attributes: {...}}
setAttributes
Merges the provided object into the existing attributes object for the most recent participant of the specified purpose within the interaction. Returns an object that contains the submitted object.
 
Required parameters:
  • attributes (Object)
  • participantType (Purpose string, e.g. "agent", "customer", "acd")
 
Optional parameters:
  • conversationId (GUID string)
{attributes: {...}}
setCustomerAttributes
Merges the provided object into the existing attributes object for the most recent customer participant within the interaction. Returns an object that contains the submitted object.
 
Required parameters:
  • attributes (Object)
 
Optional parameters:
  • conversationId (GUID string)
{attributes: {...}}
wrapUp
Sets the specified wrap-up code and notes against the current step of the specified interaction, and optionally also disconnects the specified interaction.
 
Required parameters:
  • wrapName (Wrap-up string, e.g. [var_csOBOutcomeCode]. Can also be an empty string "")
  • wrapNotes (Notes string, e.g. [var_csOBComments]. Can also be an empty string "")
  • disconnect (Boolean, "true" / "false", or "1" / "0")
 
Optional parameters:
  • conversationId (GUID string)
{}
 
 

Chat

These functions relate to integrating with Chat interactions.
Name
Description
Example Success Response
chatMessages
Returns an object containing the details of the 100 most recent messages for the specified interaction. The current user must be a participant within the specified interaction to be able to execute this function.
 
Please see the Genesys Cloud Chat article for more detail on the returned data structure and handling of chat interactions.
 
Optional parameters:
  • conversationId (GUID string)
{lastCustomerMessage: "<Message string>", messages: [{...}], customerActive: <Boolean>}
chatReply
Submits the provided message to the chat for the specified interaction. Returns an object containing the details of the submitted message. The current user must be a participant within the specified interaction to be able to execute this function.
 
Required parameters:
  • message (Message string)
 
Optional parameters:
  • conversationId (GUID string)
{id: "<Message GUID>", conversation: {...}, sender: {...}, body: "<Message string>", bodyType: "standard", timestamp: "<ISO 8601 datetime string>", selfUri: "/api/v2/conversations/chats/<Conversation GUID>/messages/<Message GUID>"}
 
 

Outbound

These functions relate to integrating with Outbound interactions.
Name
Description
Example Success Response
setOutboundCampaignStage
Sets the specified stage for the current interaction for a Predictive campaign. Returns an empty string.
 
Stage is only available for Predictive campaigns, and is used to guide the predictive dialling algorithm's behaviour.
 
This function is automatically called whenever the page is transitioned using the page's name as the stage (e.g. [var_csPageName]), so this function is only required if you are using a Predictive campaign and wish to include more granular staging than page transfer.
 
Required parameters:
  • stage (Stage string)
""
startPreviewCall
Initiates a call to the specified number within the Preview record's remaining available callback numbers. Returns an object containing details of the interaction.
 
Starting a preview call is only possible within a Preview campaign, and can only select from the remaining available callback numbers rather than being able to specify an arbitrary phone number to call. The available numbers are contained within the interaction's agent participant's callbacks array , in the callbackNumbers  property.
 
Optional parameters:
  • indexToCall (Index integer, default of 0)
  • conversationId (GUID string)
{id: "<GUID>", startTime: "<ISO 8601 datetime string>", participants: [{...}], recordingState: "<State string>", divisions: [{...}], selfUri: "/api/v2/conversations/<GUID>"}
skipPreviewCall
Skips the current number within the Preview record, and disconnects the current callback interaction. Returns an empty object.
 
Skipping a preview call is only possible within a Preview campaign, and will cause the current call to be disconnected if already dialling or connected. The wrap-up code will be automatically set to the Genesys Cloud default code of ININ-OUTBOUND-PREVIEW-SKIPPED
 
Optional parameters:
  • conversationId (GUID string)
{}
 
 

Telephony

These functions relate to managing common telephony actions.
Name
Description
Example Success Response
dial
Creates a new call conversation, initiating a phone call to the specified number from the specified queue. Only works when not already within an existing conversation. Displays a toast to the agent with the result.
 
Required parameters:
  • numberToDial (E.164-formatted phone number string)
  • callFromQueueName (Queue name string)
{id: "<GUID>", selfUri: "/api/v2/conversations/calls/<GUID>"}
hold
Enables/disables placing the call on hold for the specified interaction. Returns an empty object.
 
Required parameters:
  • holdState (Boolean or "true" / "false")
 
Optional parameters:
  • conversationId (GUID string)
{}
mute
Enables/disables placing the call on mute for the specified interaction. Returns an empty object.
 
Required parameters:
  • muteState (Boolean or "true" / "false")
 
Optional parameters:
  • conversationId (GUID string)
{}
 
 

Transfer - Blind

These functions relate to placing blind transfers (also known as "cold transfers").
 
For all of the functions in this group, if closeScript is true, then the wrap-up and comments will be set according to the standard wrap-up and comments process. If [var_csOBOutcomeCode] isn't set, then a value of "Transfer" will be used.
Name
Description
Example Success Response
blindTransfer
Initiates a blind transfer to the specified destination for the specified interaction, optionally closing & wrapping-up the script automatically. Returns an empty object.
 
The values available for transferType are defined in this API reference, and the voicemail modifier cannot be used.
 
Required parameters:
  • transferType (Type string, e.g. "userId", "address", "userName", "queueId")
  • transferTo (Destination string)
 
Optional parameters:
  • closeScript (Boolean or "true" / "false", default of true)
  • conversationId (GUID string)
{}
blindTransferAddress
Initiates a blind transfer to the specified phone number for the specified interaction, optionally closing & wrapping-up the script automatically. Returns an empty object.
 
Required parameters:
  • phoneNumber (E.164-formatted phone number string)
 
Optional parameters:
  • closeScript (Boolean or "true" / "false", default of true)
  • conversationId (GUID string)
{}
blindTransferUserId
Initiates a blind transfer to the specified user (identified by their GUID) for the specified interaction, optionally closing & wrapping-up the script automatically. Returns an empty object.
 
Required parameters:
  • userId (User GUID string)
 
Optional parameters:
  • closeScript (Boolean or "true" / "false", default of true)
  • conversationId (GUID string)
{}
blindTransferUsername
Initiates a blind transfer to the specified user (identified by their username) for the specified interaction, optionally closing & wrapping-up the script automatically. Returns an empty object.
 
Required parameters:
  • userName (Username string)
 
Optional parameters:
  • closeScript (Boolean or "true" / "false", default of true)
  • conversationId (GUID string)
{}
blindTransferQueueId
Initiates a blind transfer to the specified queue (identified by its GUID) for the specified interaction, optionally closing & wrapping-up the script automatically. Returns an empty object.
 
Required parameters:
  • queueId (Queue GUID string)
 
Optional parameters:
  • closeScript (Boolean or "true" / "false", default of true)
  • conversationId (GUID string)
{}
blindTransferQueueName
Initiates a blind transfer to the specified queue (identified by its name) for the specified interaction, optionally closing & wrapping-up the script automatically. Returns an empty object.
 
Required parameters:
  • queueName (Queue name string)
 
Optional parameters:
  • closeScript (Boolean or "true" / "false", default of true)
  • conversationId (GUID string)
{}
 
 

Transfer - Consult

These functions relate to placing consult transfers (also known as "warm transfers").
Name
Description
Example Success Response
startConsultToAddress
Initiates a consult transfer to the specified phone number for the specified interaction. Returns an object containing the destination participant's GUID.
 
Required parameters:
  • phoneNumber (E.164-formatted phone number string)
 
Optional parameters:
  • conversationId (GUID string)
{destinationParticipantId: "<GUID>"}
startConsultToQueue
Initiates a consult transfer to the specified queue (identified by its name) for the specified interaction. Returns an object containing the destination participant's GUID.
 
Required parameters:
  • queueName (Queue name string)
 
Optional parameters:
  • conversationId (GUID string)
{destinationParticipantId: "<GUID>"}
startConsultToUser
Initiates a consult transfer to the specified user (identified by their username) for the specified interaction. Returns an object containing the destination participant's GUID.
 
Required parameters:
  • username (Username string)
 
Optional parameters:
  • conversationId (GUID string)
{destinationParticipantId: "<GUID>"}