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.

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:
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

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 in`locale`. 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 in`locale`. 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. Makes`registration-type` redundant.
`customer-subject`	No			Optional. Requires`customer-display-name`
`customer-email`	No			Optional. Requires`customer-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 options`en`, `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 use`locale`
`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.

Widget Configuration

How to setup the widget​

Genesys Cloud prerequisites​

HTML integration​

Using an HTML tag​

caution

Using JavaScript​

ES5 & Google Tag Manager​

Localization​

Supported languages

1st way. Override specific translation strings inline​

2nd way. Set translations from an external json file​

note

Events​

HandledError​

Error codes​

Example​

Methods​

ICustomField​

ISelectOption​

ISchedule​

IScheduleEntry​

Example​

Theming​

note

note

CSS Variables​

Configuration options​

How to setup the widget

Genesys Cloud prerequisites

HTML integration

Using an HTML tag

Using JavaScript

ES5 & Google Tag Manager

Localization

1st way. Override specific translation strings inline

2nd way. Set translations from an external json file

Events

HandledError

Error codes

Example

Methods

ICustomField

ISelectOption

ISchedule

IScheduleEntry

Example

Theming

CSS Variables

Configuration options