Tool API
Bambuser product: Video Consultation / Live
An API to provide custom User Interface Tools from your app
Replacement of built-in tools
Any tool that the app would like to provide a replacement for must be registered in App manifest using the {hostId}.tools property, see User Interface Tools for the available types you can replace
Example tool registration in App manifest:
{
"permissions": [
"callsWidget:tool.write",
"callsAgentTool:tool.write"
],
"url": {
"type": "module",
"src": "https://your-app-domain.com/main.js"
},
"callsWidget": {
"tools": [{
"id": "my-custom-vto-session-tool",
"type": "vto-session"
}]
},
"callsAgentTool": {
"tools": [{
"id": "my-custom-vto-session-tool",
"type": "vto-session"
}]
}
}
Methods
createTool()
Permission: callsWidget:tool.write / callsAgentTool:tool.write
Context: Main app
Creates a custom tool with the view provided by your app.
Parameters
id- String for the id associated with the tool, required when creating a built-in tool replacementlabel- Text string for the title and menu action labelviewUrl- Url to the tool'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 Tool view.
Example
const { toolApi } = await bambuserAppFramework.getContext();
const tool = await toolApi.createTool({
label: 'My tool',
url: 'https://example.com/tool.html',
});
Events
provide-instance
Permission: callsWidget:tool.write / callsAgentTool:tool.write
Context: Main app
When there are one or more built-in tools that the app should replace, this event will be fired so you can provide the replacement tool view(s)
Event properties
id- The id corresponding to the tool registration in App manifest that should be provided
Event return value
It is expected that the event handler will return a tool view created by createTool() with the id provided by the event
Example
const { toolApi } = await bambuserAppFramework.getContext();
toolApi.on('provide-instance', async ({ id }) => {
const tool = await toolApi.createTool({
id, // Must match the requested id, corresponds to the id for the tool added in App Manifest
label: 'My tool',
viewUrl: `http://your-app-domain.com/custom-tool/${id}.html`,
});
tool.on('open', () => {
console.log(`Tool ${id} was opened`);
});
tool.on('close', () => {
console.log(`Tool ${id} was closed`);
});
return tool;
});
Tool view
A tool view is a specific tool added via the Tool API and is available from both main app and tool view context.
As a tool runs in a separate context, referred to as the tool view context, communication between the tool view context and main app context can be achieved with a bi-directional message channel, see emit() / postMessage() / message. Keep in mind that the tool life cycle is usually dependent upon user interactions, so it can be a good idea to communicate essential UI state with main app context so a tool can be closed and opened into the same state. It's also a good idea to perform long running tasks in main app context as user can at any time decide to look at something else for a while and the tool view will be removed and any ongoing task will be aborted.
Example tool 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 tool</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 { tool } = await bambuserAppFramework.getContext();
// The tool's UI has loaded and may now be presented
tool.setReady()
</script>
</body>
</html>
The page loaded in the tool view context must load the Bambuser App Framework Runtime and at least 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
The page loaded in the tool view context must follow our Design Guidelines and make the look and feel to be aligned with other parts of the user interface
Tool view methods
setReady()
Permission: Implicit via Tool API
Context: Tool view
Decide when the tool 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 { tool } = 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 tool UI presented
tool.setReady();
open()
Permission: Implicit via Tool API
Context: Main app
Open the tool programmatically from main app context
Return value
None.
Example
// ...
tool.open();
close()
Permission: Implicit via Tool API
Context: Main app, Tool view
Close the tool programmatically
Return value
None.
Example
// ...
tool.close();
emit()
Permission: Implicit via Tool API
Context: Tool view
Send a message from tool view context to main app context
Parameters
payload- The message payload to send to the main app context
Return value
None.
Example
const { tool } = await bambuserAppFramework.getContext();
// ...
tool.emit({
eventName: 'hello-from-tool-view-context',
data: {
foo: 'bar',
},
});
postMessage()
Permission: Implicit via Tool API
Context: Main app
Send a message from main app context to tool view context
Parameters
payload- The message payload to send to the tool view context
Return value
None.
Example
// ...
tool.postMessage({
eventName: 'hello-from-main-context',
data: {
foo: 'bar',
},
});
Tool view events
open
Permission: Implicit via Tool API
Context: Main app
The open event is fired in main app context when tool is opened
Example
// ...
tool.on('open', () => {
console.log('Tool was opened');
});
close
Permission: Implicit via Tool API
Context: Main app
The close event is fired in main app context when tool is closed
Example
// ...
dialog.on('close', () => {
console.log('Tool was closed');
});
Permission: Implicit via Tool API
Context: Main app, Tool view
Receive a message sent from the main app context or tool view context
Event properties
event.*- The message payload sent from other context
Example
// ...
tool.on('message', event => {
console.log('Tool message event', event);
});
message
Permission: Implicit via Tool API
Context: Main app, Screen view
Receive a message sent from the main app context or tool view context
Event properties
event.*- The message payload sent from other context
Example
// ...
tool.on('message', event => {
console.log('Tool message event', event);
});