Skip to main content

Widget Configuration

Auvious widget is a web component to be used on 3rd party websites to initiate a video call from the customer side, without the need to go through the chat channel.

How to setup the widget

Auvious widget requires some parameters from Genesys Cloud in order to connect properly.

All these parameters collected must be set in the html tag like this.

<app-auvious-widget
pc-environment="abc-123-abc-123"
pc-organization-id="abc-123-abc-123"
pc-deployment-id="abc-123-abc-123"
...
other
parameters
...
></app-auvious-widget>

Where abc-123-abc-123 is the actual value.

Please refer to section Plain HTML Integration on how to install the widget on the website. Please refer to section Available Configuration Options for a full list of available options.

Genesys Cloud prerequisites

  1. Create a new widget in Contact Center | Widgets. Widget type: Third Party.
  2. Once you have created the widget, you will see the Deployment Key. Copy it and paste it to the ‘pc-deployment-id’ property of Auvious Widget.
  3. Copy the queue name you wish to use for the widget (found in Admin | Queues) and set it to ‘pc-queue’.
  4. Retrieve the Organization ID from Account Settings | Organization settings | Advanced and set it to ‘pc-organization-id’.
  5. Retrieve the Application ID from Auvious | Settings | Application Configuration and set it to ‘application-id’.
  6. To enable scheduled video calls, follow the steps below:
    1. Retrieve the callback queue name found in ‘Admin | Queues | <your-callback-queue>’ and set it to ‘pc-callback-queue’.
    2. Set the ‘auvious-environment’ parameter to ‘auvious.video’
    3. Go to ‘Admin | Integrations | OAuth’ and create a new client by clicking ‘Add Client
    4. Provide a name and description and set a Grant Type of ‘Client Credentials’.
    5. Assign a role with the following permissions:
      1. Conversation>callback>create
      2. Routing>Queue>view
    6. When you save, copy the Client ID and Client Secret.
    7. Go to ‘Auvious | Settings | Application Configuration’ and paste them to ‘OAuth Client ID” and ‘OAuth Client Secret’.
    8. Enable ‘Scheduling for agents’ in ‘Auvious | Settings | Application Configuration’.
    9. Click ‘Save’.

Ensure that your website is served over https and not http.

HTML integration

Using an HTML tag

caution

Make sure your html page has <meta charset=UTF-8> as a default charset. Safari has a known issue of not loading the scripts properly if the charset is set to another type such as charset=windows-1252

  1. Add this code to the <head> tag of your html
<script
type="module"
src="https://auvious.video/widget/dist/auvious/auvious.esm.js"
></script>
<script
nomodule=""
src="https://auvious.video/widget/dist/auvious/auvious.js"
></script>
  1. Add this code to before the closing </body> tag
<app-auvious-widget
pc-environment="<your-purecloud-environment>"
pc-organization-id="<your-organization-id>"
pc-deployment-id="<your-deployment-id>"
...
></app-auvious-widget>

For more available configuration options please check the table at the Configuration Options section.

Using JavaScript

Creating a widget in code gives you more flexibility on pre-filling customer data dynamically. You can create the widget once your user has logged-in and pre-fill the customer-name field so that your user doesn't need to type it on his own. Furthermore, you can add translations.

1.Add this code to the <head> tag of your html

<script
type="module"
src="https://auvious.video/widget/dist/auvious/auvious.esm.js"
></script>
<script
nomodule=""
src="https://auvious.video/widget/dist/auvious/auvious.js"
></script>
  1. Add this code before the closing </body> tag. You can find a list of all the configuration options at the Configuration Options section.
<script>
let widgetOptions = {
'pc-environment': '<PC_ENVIRONMENT>',
'customer-avatar-url': '<CUSTOMER_AVATAR_URL>',
'pc-queue': '<PC_QUEUE>',
'registration-type': '<REGISTRATION_TYPE>',
'dark-mode': '<DARK_MODE>',
'pc-organization-id': '<PC_ORGANIZATION_ID>',
'pc-deployment-id': '<PC_DEPLOYMENT_ID>'
};

(async () => {
await customElements.whenDefined('app-auvious-widget');
showWidget();
})();

function showWidget() {

// create our widget
const widget = document.createElement('app-auvious-widget');

// get all the widget options and pass it to our widget.
Object.keys(widgetOptions).forEach(key => {
const value = widgetOptions[key];
widget.setAttribute(key, value);
})

// add the newly created widget to the body.
document.body.appendChild(widget);
}
</script>

ES5 & Google Tag Manager

Google Tag Manager requests the code in the page to be writtern in ES5 and not ES6. To support this, we replace arrow functions and async-await with simple functions and promises. Use this sample code to create a custom HTML Tag in GTM.

  <script>

(function () {
var s = document.createElement('script');
s.setAttribute('src', 'https://auvious.video/widget/dist/auvious/auvious.esm.js');
s.setAttribute('type', 'module');
document.head.appendChild(s);

var n = document.createElement('script');
n.setAttribute('src', 'https://auvious.video/widget/dist/auvious/auvious.js');
n.setAttribute('nomodule', '');
document.head.appendChild(n);

})();

var widgetOptions = {
'pc-environment': '<your-environment>',
'pc-queue': '<your-queue>',
'pc-organization-id': '<your-organization-id>',
'pc-deployment-id': '<your-deployment-id>'
};


window.customElements.whenDefined('app-auvious-widget')
.then(function () {
showWidget();
});


function showWidget() {

// create our widget
var widget = document.createElement('app-auvious-widget');

// get all the widget options and pass it to our widget.
Object.keys(widgetOptions).forEach(function (key) {
var value = widgetOptions[key];
widget.setAttribute(key, value);
})

// add the newly created widget to the body.
document.body.appendChild(widget);
}

</script>

Localization

If you want to provide your own translations there are two ways. Add this script after the app-auvious-widget tag. If both ways are implemented on the same page, the external json file prevails.

Supported languages

de, el, en, es, fi, nl, pl, sv, tr, zh, pt

1st way. Override specific translation strings inline

The first param must be a valid json. Second param is the language it refers to. This is optional. If none is provided, it will default to the locale language. If no locale is provided, it will default to english.

<script>
(async () => {
await customElements.whenDefined("app-auvious-widget");
const widget = document.querySelector("app-auvious-widget");

// inline
// second param is optional. If none provided, it will default to locale language
widget.setTranslations(
{ "Connecting...": "connecting in german..." },
"de"
);
})();
</script>

2nd way. Set translations from an external json file

The first param must be a url of a valid json file. Second param is the language it refers to. This is optional. If none is provided, it will default to the locale language. If no locale is provided, it will default to english.

note

You can provide translations to languages that we don't currently support. All dates in the widget and all copy in the video call will fall back to english.

<script>
(async () => {
await customElements.whenDefined("app-auvious-widget");
const widget = document.querySelector("app-auvious-widget");

// from external repository
// second param is optional. If none provided, it will default to locale language
widget.setTranslationFile("https://myserver.com/assets/de.json", "de");
})();
</script>

Events

The Auvious Widget exposes the following events.

NameDescription
readyFired when the widget is loaded.
callStartingFired when the customer has landed to the room but has not joined yet, testing his/her devices.
callStartedFired when the customer has joined the call
callEndedFired when the customer has left the call
conversationStartedFired when the chat communication has started. Get the event.detail for the conversation id.
conversationEndedFired when the chat communication has ended with the agent.
agentConnectedFired when the agent has connected but not yet started the call.
agentDisconnectedFired when the agent has left the conversation.
queueTimeChangedFired when the waiting time in queue has changed. Fires every second. Get the event.detail for an object containing seconds and minutes. Ex {seconds: "04", minutes: "00"}
errorHandledFired when an exception or error was caught by our widget. Does NOT fire for unhandled exceptions or errors in the video call.A HandledError object is returned in event.detail.
notificationOpenedFired when a notification is shown. The event.detail carries the notification type. Can be one of these: info, greeting, success, warning, error
notificationClickedFired when a notification was clicked to dismiss it. The event.detail carries the notification type. Can be one of these: info, greeting, success, warning, error
transferFired when a conversation is transferred to another agent. The event.detail carries the conversation id. Once a new agent joins the call, an agentConnected event is triggered

HandledError

PropertyTypeDescription
codenumberOne of the available error codes below.
namestringName of the handled error.
messagestringDescription of the handled error.
stackstringStack trace

Error codes

CodeDescription
1Auvious event client error.
2Browser detection failed.
3Copy-to-clipboard failed.
4Error log failed.
5HTML parsing for media player failed. Probably malformed HTML passed to setQueueEmbeddableVideoCode.
6Error while calling a Genesys API. Description has more details.
10Could not start Genesys chat service. Probably bad configuration at CXBus.
11A required widget property was not provided. The widget cannot load.
12Not a valid/known Genesys pcEnvironment.
20Co-browse invalid PIN provided. Could not authenticate user. Check your auvious-environment if it points to the correct environment or the PIN has expired.
21Co-browse API error.
22Co-browse authentication error. Probably an invalid PIN
23Co-browse leave failed.
24Co-browse join failed.
25Co-browse resume session failed.
30Genesys Premise File transfer API error.
40Not valid custom fields. Check the ICustomField model
41Missing custom fields. registration-type is set to custom but custom fields are missing.
42A required field is missing
43Not valid customer metadata. setCustomerMetadata expects an object but something else was provided.
50Could not start a new conversation. Check your widget parameters for any typos (deployment-id, organization-id) or if a conversation is already active
51Could not end conversation.
52Could not parse auvious URL to open a pop-up.
53iFrame was already destroyed while trying to send a message.
54Could not join a co-browse session.
55iFrame sent invalid metadata.
56Could not parse Gensys web chat message received.
57Genesys client was not able to connect.
60Media devices are not available. Check browser permissions.
61Could not request for camera or microphone. Check if already used by another application.
70Could not start a new Sketch session.
71Sketch API error.
80Could not authenticate with the OTP provided.
81Could not create a Genesys Cloud Callback.
90Could not load list of Country codes.
91Could not load translation file. Check if json is valid.

Example

...
const widget = document.createElement('app-auvious-widget');
widget.addEventListener("callStarted", () => {
// do stuff
});
widget.addEventListener("queueTimeChanged", (event) => {
// do stuff
console.log(event.detail)
});
...

Methods

The Auvious Widget exposes the following methods

MethodValue
launch(action: 'video')Directly start a subflow, without the user having to press a button. Available options: audio,video,cobrowse,callback
setTranslations(map: <key, value> json, language?: string)Override translation keys. If language is not provided, override for current language set inlocale. If no locale is set, override for default language (english)
setTranslationFile(url: string, language?:string)Fetch translation json. URL must serve a valid json. If language is not provided, override translations for current language set inlocale. If no locale is set, override for default language (english)
setCobrowseFilters(filters: string[]Set an array of css selectors that will be filtered out on the agent side. Used mainly to filter out credit card or password forms.
terminate(confirm: boolean = true)Ends any active flow. Like clicking the ( X ) button. Expects an optional boolean parameter, whether to show the confirmation panel or not. Defaults to true.
setQueueEmbeddableVideoCode(code: string)set an <iframe /> embeddable code (youtube etc) to be show to the customer while on queue.
setCustomFields(fields: ICustomField[])sets custom fields to the contact form. Needs registration-type to be custom.
setCustomerMetadata(map:<key, value> json) : Promise<void>Set extra fields to customer metadata object. Throws a promise rejection if metadata are not a valid object. Can be retrieved in Genesys PureCloud with the prefix context.. Ex. if we set this object {token: '123'} we can retrieve it with this key: context.token
playNotificationSound()Plays the default notification sound or the sound that was set with the property notification-sound-url
setSchedule(schedule: ISchedule)Set the working hours for which one can schedule a callback

ICustomField

PropertyRequiredTypeDescription
typeyestext,selectRender either a text field or a select field.
nameyesstringThe form field name. Will be sent in the customFields as is. Prefer camelCase
requiredyesbooleanSets the form field as required or not
labelnostringLabel of the form field.
optionsno (yes if type='select')ISelectOption[]List of available options for this field

ISelectOption

PropertyRequiredTypeDescription
valueyesstringValue of the field. This will be comminucated back to the server.
labelyesstringLabel of the select option.

ISchedule

PropertyRequiredTypeDescription
timeZoneyesstringThe IANA time zone name (column TZ database name in wikipedia )
opennoIScheduleEntry[]An array defining open hours
closednoIScheduleEntry[]An array defining closed hours

By default, it is assumed the store is always open. You can restrict its schedule to a certain periodic time range or specific dates by providing open. The closed takes precedence over open, and excludes ranges from it. Each entry in both properties only apply to one or more days interval, all having a common inter-day time schedule. Order does matter, as the first one that matches a day, is the one enforced.

IScheduleEntry

PropertyRequiredTypeDescription
datenostring OR string[]One or more, single day or days interval, with format [YYYY-]MM-DD[/[YYYY-]MM-DD]
timenostring OR string[]One or more time intervals with format HH:MM/HH:MM
weekdaysnonumber OR number[]Days of the week from Sunday (1) to Saturday (7)
reasonnostringFormal reason for being closed, if applied, to inform user

When both weekdays and date are supplied, only days of the week that are included in the date interval are matched. A date without year, matches all years and more generally, anything not provided, its whole interval is assumed by default.

Example

<script>
(async () => {
await customElements.whenDefined('app-auvious-widget');
const widget = document.querySelector('app-auvious-widget');

// launch action
widget.launch(‘video’);

// co-browse filters
widget.setCobrowseFilters(['.password-field', '#credit-card-container input']);

// set custom fields. Don't forget to set 'registration-type' to 'custom'
widget.setCustomFields([
{ type: "text", name: 'firstName', required: true, label: 'First name *' },
{ type: 'text', name: 'lastName', required: false, label: 'Last name' },
{
type: 'select', name: 'subject', required: true, label: 'Subject', options: [
{ value: 'subject-returns', label: 'Returns' },
{ value: 'subject-tech', label: 'Techical support' }
]
},
{
type: 'select', name: 'testField', required: false, label: 'Test field', options: [
{ value: null, label: '-- please choose --' },
{ value: 'test-1', label: 'Test Field 1' },
{ value: 'test-2', label: 'Test Field 2' }
]
}
])

// set embeddable video (iframe) to be shown while waiting on queue.
widget.setQueueEmbeddableVideoCode(
'<iframe width="560" height="315" src="https://www.youtube.com/embed/abc" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>'
)

// Customer metata. Can be retrieved in PureCloud as 'context.myproperty' etc.
widget.setCustomerMetadata({ 'myproperty': 'value' });

// set schedule
widget.setSchedule({
timeZone: "Europe/Athens",
schedule: {
open: [
{ weekdays: [2, 4, 6], time: "09:00/14:30" },
{ weekdays: [3, 5], time: ["09:00/15:00", "17:30/21:00"] },
],
closed: [
{ date: "2022-09-30", time: "12:45/13:30", reason: "Maintenance" },
{ date: "2022-12-30/2023-01-02", reason: "New Year" },
{ date: "05-01", reason: "International Workers' Day" },
],
},
});

//....

//terminate
widget.terminate();

// Please check “Localisation” on how to use setTranslations | setTranslationFile
})();
</script>

Theming

There are two layers of customisation for our widget

  1. You can use the configuration options below to select a primary and accent color as well as set a dark mode or change the launcher icon if needed. Read the Configuration options section for more details.
  2. You can use our exposed css variables to do more fine-grained customisation.
note

If you set both css variables and configuration options, the configuration options are used.

note

The CSS variables are also passed into the call, meaning you can further theme the call UI. Read the theming section for more information.

CSS Variables

Add this code snippet to the <head> node of your HTML page and use and modify only the css variables that are needed for your theming

<style type="text/css">
html:root {
--av-font-family: /* font family to be used. Don't forget to include the link for the fonts. Defaults to sans-serif */ ;
--av-border-radius-container: /* roundness of corners for all containers. Defaults to 10px */ ;
--av-border-radius-button: /* roundness of corners for square buttons. Defaults to 5px */ ;
--av-box-shadow-container: /* shadow of containers. */ ;
--av-box-shadow-confirm: /* shadow of confirmation notification. */ ;
--av-background-color-tray: /* background color of the tray area. Defaults to black. */ ;
--av-color-tray: /* font color of the tray area. Defaults to white. */ ;
--av-font-color-dark: /* text color in all light containers (dark-mode off). */ ;
--av-font-color-light: /* text color in all dark containers (dark-mode on) */ ;
--av-color-primary: /* background color of primary buttons (launcher ) */ ;
--av-color-accent: /* background color of secondary buttons */ ;
--av-color-error: /* background color of errors. Used in text as well as backgrounds */ ;
--av-color-success: /* background color of success messages. used in text as well as backgrounds */ ;
}
</style>

Configuration options

This widget exposes the following properties:

PropertyRequiredDefaultValuesDescription
pc-environmentYesmypurecloud.de, mypurecloud.comThe purecloud instance it will send API calls to. Possible values`mypurecloud.
pc-queueYesThe queue name it will connect to.
pc-organization-idYesThe purecloud organization id.
organizationNoAuviousName of your organization. Used in OTP SMS text as the sender’s name.
pc-deployment-idYesThe deployment id located in purecloud
chat-modeNogenesys-cloudgenesys-api, genesys-cloud, genesys-premise, genesys-web-messagingRequired. Sets what chat service to use.
auvious-environmentYes*genesys.auvious.comAuvious region instance it will send API calls to.
Required if callback is enabled
application-idYes*Can be found in Genesys purecloud / auvious virtual counselor integration / settings
Required if callback is enabled.
registration-typeNonamename nameEmailSubject customIndicate whether to caputer only name or show a popup that captures first name, last name,email and subject before the video call begins. Set to custom to load your own fields.
customer-avatar-urlNoAuvious logoThe avatar that will be shown for the customer in the PureCloud Conversation. Defaults to auvious logo.
customer-display-nameNoPrefill customer name and jump right into a conversation without the need to register a name. Makesregistration-type redundant.
customer-subjectNoOptional. Requirescustomer-display-name
customer-emailNoOptional. Requirescustomer-display-name
dark-modeNofalseEnable dark mode . White panels become dark.
color-primaryNoblackCss color such as red, green etc, or hex ex: #333333Optional. Changes black color to value provided. Must be a valid css color value.
color-accentNoauvious blueCss color such as red, green etc, or hex ex: #333333Optional. Changes blue color to value provided.Must be a valid css color value.
color-warnNoAuvious redOptional. Changes red color to value provided.Must be a valid css color value.
localeNoen-GRAvailable language optionsen, el, de, es, fi, nl, pl, sv, tr, zh or any custom translation provided. Country: all ISO country codes.First part is the language, second part is the country (2-digit-ISO). Note: the country ISO is used as the default country in the callback panel.
languageDeprecated. Please uselocale
queue-extra-secondsNo30Extra seconds to wait for an agent if none of the agents are responding. Starts counting when in queue and the agent didnt answer the call and is waiting to 'make eligible for interactions'
wait-for-greeting-secondsNo3Set to -1 if you don't want any greeting popup. Otherwise, any positive number.How many seconds to wait before it shows the greeting.
active-widgetsNovideochat, video, callback, audio, cobrowse. Example "video,callback"String in csv format.
pc-callback-queueYes*The genesys callback queue name the interaction will be routed to *Required if callback widget is enabled.
kiosk-modeNofalsetrue,falseSets the video call to the full width/height of the browser window. The customer is not presented with the ‘check your devices’ screen and directly joins the call. To fully automate customer joining to the call, set the customer-display-name as well.
queue-max-minutesNo5After X minutes on queue, the customer will get a notification that no agents are available. Set -1 to disable and have the customer wait as long as he wants.
position-horizontalNorightleft, center, rightWhere to position the widget horizontally.
position-verticalNobottomtop,bottomWhere to position the widget vertically
data-urlNoHttp url pointing to Genesys Engage GMS channel.Sets the dataURL parameter in Genesys Widgets webchat configuration. Only in combination with chat-mode: “genesys-premise”. Either this or comet-url must be supplied for connecting to Genesys Engage.
comet-urlNoHttp url pointing to Genesys Engage CometD serviceSets the cometD.cometURL parameter in Genesys Widgets webchat configuration. Only in combination with chat-mode: “genesys-premise”
comet-channelNoString denoting the channel to use for cometDSets the cometD.channel parameter in Genesys Widgets webchat configuration. Only in combination with chat-mode: “genesys-premise”. Must be supplied if comet-url is defined.
comet-api-urlNoHttp url pointing to Genesys Engage api url service.Sets cometD.apiURL parameter in Genesys Widgets webchat configuration. Only in combination with chat-mode: “genesys-premise”. Necessary for file transfers to work.
close-hiddenNofalsetrue,falseHides X button when on an active interaction.
pop-out-hiddenNofalsetrue,falseHides pop-out button on video card.
incoming-chat-messages-blockedNofalsetrue,falseBlocks incoming chat messages (from agent). Chat panel will not be shown if on a video call and an incoming message arrives.
queue-video-urlNoFile url (preferably .mp4) to load in a video player while the customer is waiting in queue.
queue-video-delay-secondsNo3Number of seconds to dealy the appearance of the video, from the time the customer is on queue.
launcher-image-urlNoChange the default widget launcher image. This image will be applied either you have only one active widget or multiple.
confirm-callNofalsetrue, falseShow a confirmation popup before starting the call with the agent. If rejected, the agent will have to send a new link via chat to ask again for a call
greeting-actionNoaudio, video, callback, chat, cobrowseDefine what widget to launch when the greeting notification was clicked
greeting-sound-onNotruetrue, falsePlays a notification sound once the greeting is shown
notification-sound-urlNoAny valid sound file url (preferably https)Use this sound instead of the default one when the greeting sound plays or when the playNotificationSound() method is called.