Skip to main content

Dialog API

Bambuser product: Video Consultation

An API to provide custom User Interface Dialogs from your app

Replacement of built-in dialog types​

Any dialog type that the app would like to provide a replacement for must be registered in App manifest using the {hostId}.dialogs property, see User Interface Dialogs for the available types you can replace

Example dialog registration in App manifest:

{
  "permissions": [
    "callsWidget:dialog.write"
  ],
  "url": {
    "type": "module",
    "src": "http://your-app-domain.com/main.js"
  },
  "callsWidget": {
    "dialogs": [{
      "id": "my-custom-dialog",
      "type": "vto-consent"
    }]
  }
}

Methods​

openMessageDialog()​

Permission: callsWidget:dialog.write / callsAgentTool:dialog.write
Context: Any

Opens a built-in message dialog with title, content and a button where user can dismiss the dialog

Parameters​

  • title - Text string for the dialog title
  • content - Text string for the dialog content between the title and button
  • dismissButtonLabel - Optional text string for the dismiss button label

Return value​

A promise whose fulfillment handler will receive an object with the dialog close action.

Example​

const { dialogApi } = await bambuserAppFramework.getContext();

const result = await dialogApi.openMessageDialog({
  title: 'Lorem ipsum',
  content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum blandit pretium eros, sed faucibus ligula lacinia vel.'
});

console.log(result); // { action: 'dismiss' }

openConfirmDialog()​

Permission: callsWidget:dialog.write / callsAgentTool:dialog.write
Context: Any

Opens a built-in confirm dialog with title, content and two buttons where user can either dismiss or confirm the dialog

Parameters​

  • title - Text string for the dialog title
  • content - Text string for the dialog content between the title and button
  • confirmButtonLabel - Optional text string for the confirm button label
  • dismissButtonLabel - Optional text string for the dismiss button label

Return value​

A promise whose fulfillment handler will receive an object with the dialog close action.

Example​

const { dialogApi } = await bambuserAppFramework.getContext();

const result = await dialogApi.openConfirmDialog({
  title: 'Bacon ipsum',
  content: 'Bacon ipsum dolor amet burgdoggen bacon ham hock, jerky shankle kevin ham tenderloin?'
});

console.log(result); // { action: 'confirm' | 'dismiss' }

createCustomDialog()​

Permission: callsWidget:dialog.write / callsAgentTool:dialog.write
Context: Any

Create a custom dialog with the view provided by your app. This can be used to show an arbitrary dialog with custom content or when creating a replacement of a built-in dialog type, see provide-instance event

Parameters​

  • id - String for the id associated with the dialog, required when creating a built-in dialog replacement
  • viewUrl - Url to the dialog's view, must have the same origin as the URL to your app's main entrypoint

Return value​

A promise whose fulfillment handler will receive an instance of a Dialog view.

Example​

const { dialogApi } = await bambuserAppFramework.getContext();

const dialog = await dialogApi.createCustomDialog({
  id: 'my-dialog', // Only required when overriding a built-in dialog type, see 'provide-instance'
  viewUrl: 'http://your-app-domain.com/custom-dialog.html',
});

dialog.open();

Events​

provide-instance​

Permission: callsWidget:dialog.write / callsAgentTool:dialog.write
Context: Main app

When a built-in dialog type that is replaced by your app is about to be opened the actual dialog view needs to be determined so the correct dialog view may be shown.

Event properties​

  • id - The id corresponding to the dialog registration in App manifest that should be provided

Event return value​

It is expected that the event handler will return a dialog view created by createCustomDialog() with the id provided by the event

Example​

const { dialogApi } = await bambuserAppFramework.getContext();

dialogApi.on('provide-instance', async ({ id }) => {
  const dialog = await dialogApi.createCustomDialog({
    id, // Must match the requested id, corresponds to the id for the dialog added in App Manifest
    viewUrl: 'http://your-app-domain.com/custom-dialog.html',
  });

  dialog.on('close', event => {
    console.log(`Custom dialog ${id} was closed with action`, event.action);
  });

  return dialog;
});

Dialog view​

A dialog view is a specific dialog added via the Dialog API and is available from both main app and tool view context. It's built as a normal HTML page and shown inside an iframe put on top of the current view inside a dialog box with a backdrop preventing user to interact with anything else than the dialog.

As a dialog view runs in a separate context, referred to as the dialog view context, communication between the dialog view context and main app context can be achieved with a bi-directional message channel, see emit() / postMessage() / message

Example custom dialog view:

<!DOCTYPE html>
<html lang="en" className="bam-ui">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Custom dialog</title>
    <link rel="stylesheet" href="https://app-framework.bambuser.com/bam-ui.css" />
  </head>
  <body>
    <h1>Hello world</h1>
    <script src="https://app-framework.bambuser.com/runtime.js"></script>
    <script src="https://app-framework.bambuser.com/bam-ui.js"></script>
    <script type="module">
      const { dialog } = await bambuserAppFramework.getContext();
      dialog.setReady();
    </script>
  </body>
</html>
info

The page loaded in the dialog view must load the Bambuser App Framework Runtime and communicate back when the UI is ready to be presented to the user by using setReady(). Until you do this, a loader will be shown to the user

info

The page loaded in the dialog view must follow our Design Guidelines and make the look and feel to be aligned with other parts of the user interface

Dialog view methods​

setReady()​

Permission: Implicit via Dialog API
Context: Dialog view

Decide when the dialog is ready to be displayed, ex. your page has loaded completely and initial UI can be presented to the user. Before this, a loader will be displayed to the user.

Return value​

None.

Example​

const { dialog } = await bambuserAppFramework.getContext();

// All necessary resources has been loaded and the UI is presentable to the user
// The loader currently showing should be removed and the dialog UI presented
dialog.setReady();

open()​

Permission: Implicit via Dialog API
Context: Main app

Explicitly open the dialog

Return value​

A promise whose fulfillment handler will receive an object with the dialog close result.

Example​

// ...

const result = await dialog.open();
console.log(result); // { action: 'confirm' | 'dismiss' | '<your-choice>', data: object? }

close()​

Permission: Implicit via Dialog API
Context: Dialog view

Close the dialog with a specific action, the action is passed to close event and the promise created when opening the dialog

Parameters​

  • action - The dialog close action, available actions are:
    • 'confirm' - Meaning user confirmed the dialog
    • 'dismiss' - Meaning user dismissed the dialog
    • '<your-choice>' - Your choice of close action phrase, note that this should only be used when the app is fully managed by your app and doesn't replace any built-in dialog type.
  • data - Optional, any additional data to pass along in the dialog close result

Return value​

None.

Example​

const { dialog } = await bambuserAppFramework.getContext();

dialog.close({ action: 'confirm' });

emit()​

Permission: Implicit via Dialog API
Context: Dialog view

Send a message from dialog view context to main app context

Parameters​

  • payload - The message payload to send to the main app context

Return value​

None.

Example​

const { dialog } = await bambuserAppFramework.getContext();

dialog.emit({
  eventName: 'hello-from-dialog-view-context',
  data: {
    foo: 'bar',
  },
});

postMessage()​

Permission: Implicit via Dialog API
Context: Main app

Send a message from main app context to dialog view context

Parameters​

  • payload - The message payload to send to the dialog view context

Return value​

None.

Example​

// ...

dialog.postMessage({
  eventName: 'hello-from-main-context',
  data: {
    foo: 'bar',
  },
});

Dialog view events​

open​

Permission: Implicit via Dialog API
Context: Main app

The open event is fired in main app context when dialog is opened

Example​

// ...

dialog.on('open', () => {
  console.log('Dialog was opened');
});

close​

Permission: Implicit via Dialog API
Context: Main app

The close event is fired in main app context when dialog is closed. It includes the dialog close result.

Event properties​

  • event.action - The action user took in the dialog
  • event.data - Any additional data that was passed by you when the dialog was closed

Example​

// ...

dialog.on('close', event => {
  console.log('Dialog was closed', event.action, event.data);
});

message​

Permission: Implicit via Dialog API
Context: Main app, Dialog view

Receive a message sent from the main app context or dialog view context

Event properties​

  • event.* - The message payload sent from other context

Example​

// ...

dialog.on('message', event => {
  console.log('Dialog message event', event);
});