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
- Create a new widget in Contact Center | Widgets. Widget type: Third Party.
- 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.
- Copy the queue name you wish to use for the widget (found in Admin | Queues) and set it to ‘pc-queue’.
- Retrieve the Organization ID from Account Settings | Organization settings | Advanced and set it to ‘pc-organization-id’.
- Retrieve the Application ID from Auvious | Settings | Application Configuration and set it to ‘application-id’.
- To enable scheduled video calls, follow the steps below:
- Retrieve the callback queue name found in ‘Admin | Queues |
<your-callback-queue>
’ and set it to ‘pc-callback-queue’. - Set the ‘auvious-environment’ parameter to ‘auvious.video’
- Go to ‘Admin | Integrations | OAuth’ and create a new client by clicking ‘Add Client’
- Provide a name and description and set a Grant Type of ‘Client Credentials’.
- Assign a role with the following permissions:
- Conversation>callback>create
- Routing>Queue>view
- When you save, copy the Client ID and Client Secret.
- Go to ‘Auvious | Settings | Application Configuration’ and paste them to ‘OAuth Client ID” and ‘OAuth Client Secret’.
- Enable ‘Scheduling for agents’ in ‘Auvious | Settings | Application Configuration’.
- Click ‘Save’.
- Retrieve the callback queue name found in ‘Admin | Queues |
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
- 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>
- 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>
- 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.
Name | Description |
---|---|
ready | Fired when the widget is loaded. |
callStarting | Fired when the customer has landed to the room but has not joined yet, testing his/her devices. |
callStarted | Fired when the customer has joined the call |
callEnded | Fired when the customer has left the call |
conversationStarted | Fired when the chat communication has started. Get the event.detail for the conversation id. |
conversationEnded | Fired when the chat communication has ended with the agent. |
agentConnected | Fired when the agent has connected but not yet started the call. |
agentDisconnected | Fired when the agent has left the conversation. |
queueTimeChanged | Fired 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"} |
errorHandled | Fired 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 . |
notificationOpened | Fired when a notification is shown. The event.detail carries the notification type. Can be one of these: info , greeting , success , warning , error |
notificationClicked | Fired 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 |
transfer | Fired 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
Property | Type | Description |
---|---|---|
code | number | One of the available error codes below. |
name | string | Name of the handled error. |
message | string | Description of the handled error. |
stack | string | Stack trace |
Error codes
Code | Description |
---|---|
1 | Auvious event client error. |
2 | Browser detection failed. |
3 | Copy-to-clipboard failed. |
4 | Error log failed. |
5 | HTML parsing for media player failed. Probably malformed HTML passed to setQueueEmbeddableVideoCode . |
6 | Error while calling a Genesys API. Description has more details. |
10 | Could not start Genesys chat service. Probably bad configuration at CXBus. |
11 | A required widget property was not provided. The widget cannot load. |
12 | Not a valid/known Genesys pcEnvironment. |
20 | Co-browse invalid PIN provided. Could not authenticate user. Check your auvious-environment if it points to the correct environment or the PIN has expired. |
21 | Co-browse API error. |
22 | Co-browse authentication error. Probably an invalid PIN |
23 | Co-browse leave failed. |
24 | Co-browse join failed. |
25 | Co-browse resume session failed. |
30 | Genesys Premise File transfer API error. |
40 | Not valid custom fields. Check the ICustomField model |
41 | Missing custom fields. registration-type is set to custom but custom fields are missing. |
42 | A required field is missing |
43 | Not valid customer metadata. setCustomerMetadata expects an object but something else was provided. |
50 | Could not start a new conversation. Check your widget parameters for any typos (deployment-id, organization-id) or if a conversation is already active |
51 | Could not end conversation. |
52 | Could not parse auvious URL to open a pop-up. |
53 | iFrame was already destroyed while trying to send a message. |
54 | Could not join a co-browse session. |
55 | iFrame sent invalid metadata. |
56 | Could not parse Gensys web chat message received. |
57 | Genesys client was not able to connect. |
60 | Media devices are not available. Check browser permissions. |
61 | Could not request for camera or microphone. Check if already used by another application. |
70 | Could not start a new Sketch session. |
71 | Sketch API error. |
80 | Could not authenticate with the OTP provided. |
81 | Could not create a Genesys Cloud Callback. |
90 | Could not load list of Country codes. |
91 | Could 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
Method | Value |
---|---|
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
Property | Required | Type | Description |
---|---|---|---|
type | yes | text ,select | Render either a text field or a select field. |
name | yes | string | The form field name. Will be sent in the customFields as is. Prefer camelCase |
required | yes | boolean | Sets the form field as required or not |
label | no | string | Label of the form field. |
options | no (yes if type='select' ) | ISelectOption[] | List of available options for this field |
ISelectOption
Property | Required | Type | Description |
---|---|---|---|
value | yes | string | Value of the field. This will be comminucated back to the server. |
label | yes | string | Label of the select option. |
ISchedule
Property | Required | Type | Description |
---|---|---|---|
timeZone | yes | string | The IANA time zone name (column TZ database name in wikipedia ) |
open | no | IScheduleEntry[] | An array defining open hours |
closed | no | IScheduleEntry[] | 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
Property | Required | Type | Description |
---|---|---|---|
date | no | string OR string[] | One or more, single day or days interval, with format [YYYY-]MM-DD[/[YYYY-]MM-DD] |
time | no | string OR string[] | One or more time intervals with format HH:MM/HH:MM |
weekdays | no | number OR number[] | Days of the week from Sunday (1) to Saturday (7) |
reason | no | string | Formal 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
- 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.
- 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:
Property | Required | Default | Values | Description |
---|---|---|---|---|
pc-environment | Yes | mypurecloud.de, mypurecloud.com | The purecloud instance it will send API calls to. Possible values`mypurecloud. | |
pc-queue | Yes | The queue name it will connect to. | ||
pc-organization-id | Yes | The purecloud organization id. | ||
organization | No | Auvious | Name of your organization. Used in OTP SMS text as the sender’s name. | |
pc-deployment-id | Yes | The deployment id located in purecloud | ||
chat-mode | No | genesys-cloud | genesys-api , genesys-cloud , genesys-premise , genesys-web-messaging | Required. Sets what chat service to use. |
auvious-environment | Yes* | genesys.auvious.com | Auvious region instance it will send API calls to. Required if callback is enabled | |
application-id | Yes* | Can be found in Genesys purecloud / auvious virtual counselor integration / settings Required if callback is enabled. | ||
registration-type | No | name | name nameEmailSubject custom | Indicate 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-url | No | Auvious logo | The avatar that will be shown for the customer in the PureCloud Conversation. Defaults to auvious logo. | |
customer-display-name | No | Prefill customer name and jump right into a conversation without the need to register a name. Makesregistration-type redundant. | ||
customer-subject | No | Optional. Requirescustomer-display-name | ||
customer-email | No | Optional. Requirescustomer-display-name | ||
dark-mode | No | false | Enable dark mode . White panels become dark. | |
color-primary | No | black | Css color such as red, green etc, or hex ex: #333333 | Optional. Changes black color to value provided. Must be a valid css color value. |
color-accent | No | auvious blue | Css color such as red, green etc, or hex ex: #333333 | Optional. Changes blue color to value provided.Must be a valid css color value. |
color-warn | No | Auvious red | Optional. Changes red color to value provided.Must be a valid css color value. | |
locale | No | en-GR | Available 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. |
language | Deprecated. Please uselocale | |||
queue-extra-seconds | No | 30 | Extra 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-seconds | No | 3 | Set 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-widgets | No | video | chat , video , callback , audio , cobrowse . Example "video,callback" | String in csv format. |
pc-callback-queue | Yes* | The genesys callback queue name the interaction will be routed to *Required if callback widget is enabled. | ||
kiosk-mode | No | false | true ,false | Sets 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-minutes | No | 5 | After 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-horizontal | No | right | left , center , right | Where to position the widget horizontally. |
position-vertical | No | bottom | top ,bottom | Where to position the widget vertically |
data-url | No | Http 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-url | No | Http url pointing to Genesys Engage CometD service | Sets the cometD.cometURL parameter in Genesys Widgets webchat configuration. Only in combination with chat-mode: “genesys-premise” | |
comet-channel | No | String denoting the channel to use for cometD | Sets 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-url | No | Http 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-hidden | No | false | true ,false | Hides X button when on an active interaction. |
pop-out-hidden | No | false | true ,false | Hides pop-out button on video card. |
incoming-chat-messages-blocked | No | false | true ,false | Blocks incoming chat messages (from agent). Chat panel will not be shown if on a video call and an incoming message arrives. |
queue-video-url | No | File url (preferably .mp4 ) to load in a video player while the customer is waiting in queue. | ||
queue-video-delay-seconds | No | 3 | Number of seconds to dealy the appearance of the video, from the time the customer is on queue. | |
launcher-image-url | No | Change the default widget launcher image. This image will be applied either you have only one active widget or multiple. | ||
confirm-call | No | false | true , false | Show 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-action | No | audio , video , callback , chat , cobrowse | Define what widget to launch when the greeting notification was clicked | |
greeting-sound-on | No | true | true , false | Plays a notification sound once the greeting is shown |
notification-sound-url | No | Any 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. |