This page contains a reference for all methods available when injecting Webchat.
open
The window.botpress.open method opens the Webchat window:
window.botpress.open()
It becomes available after Webchat has been initialized.
Parameters
The open method takes no parameters.
Returns
close
The window.botpress.close method closes the Webchat window:
window.botpress.close()
It becomes available after Webchat has been initialized.
Parameters
The close method takes no parameters.
Returns
toggle
The window.botpress.toggle method toggles the Webchat window open/closed depending on its current state:
window.botpress.toggle()
It becomes available after Webchat has been initialized.
Parameters
The toggle method takes no parameters.
Returns
updateUser
The asynchronous window.botpress.updateUser method updates the data associated with the current Webchat user:
await window.botpress.updateUser({
name: '<string>',
pictureUrl: '<string>',
data: {},
userKey: '<string>',
})
It becomes available after Webchat has been initialized.
Parameters
user User
The user attributes to update.
pictureUrl string
URL pointing to a picture for the user.
data object
An object containing any additional data as key-value pairs. The values can be of any type.
userKey string
A custom key to associate with the user.
By default, the user object contains the following properties:
user User
id string
required
Unique identifier for the user.
createdAt string
required
User creation timestamp in ISO 8601 format.
updatedAt string
required
Last user update timestamp in ISO 8601 format.
These are generated by the server and can’t be updated or deleted.
Returns
Promise<void>
A Promise that resolves void when the user data has been successfully updated.
getUser
The asynchronous window.botpress.getUser method gets the data associated with the current Webchat user:
await window.botpress.getUser()
It becomes available after Webchat has been initialized.
Parameters
The getUser method takes no parameters.
Returns
Promise<User>
A Promise that resolves when the user information has been retrieved.
id string
required
Unique identifier for the user.
createdAt string
required
User creation timestamp in ISO 8601 format.
updatedAt string
required
Last user update timestamp in ISO 8601 format.
pictureUrl string
URL pointing to a picture for the user.
data object
An object containing any additional data as key-value pairs. The values can be of any type.
userKey string
A custom key to associate with the user.
config
The window.botpress.config method updates Webchat’s configuration and the current user’s data.
window.botpress.config({
configuration: {},
user: {},
})
It becomes available after Webchat has been initialized.
Parameters
object
required
An object containing the Webchat configuration and user data to update.
configuration object
Webchat configuration settings to update.
botName string
Name of the bot displayed in the Webchat header.
botAvatar string
URL to the bot’s avatar image.
botDescription string
Description of the bot.
composerPlaceholder string
Placeholder text for the message input field.
color string
Primary color theme for the Webchat interface as a HEX code.
themeMode string
Theme mode. Can be light or dark.
variant string
Visual variant. Can be solid or soft.
allowFileUpload boolean
Whether to enable file upload functionality.
showPoweredBy boolean
deprecated
Whether to show “Powered by Botpress” branding.
This setting is deprecated and no longer supported. Use the
footer field instead.
feedbackEnabled boolean
Whether to enable message feedback functionality.
fabImage string
URL to the Floating Action Button (FAB) image.
radius number
Border radius for the Webchat interface. Must be between 0.5 and 4.
fontFamily string
Custom font family for the Webchat interface. Can be one of the default fonts:
"inter" | "rubik" | "ibm plex sans" | "fira code"
or any Google Font.
Google Font titles are case-sensitive.
additionalStylesheet string
Custom CSS styles to apply to the Webchat interface.
additionalStylesheetUrl string
URL to an external stylesheet to load for the Webchat interface.
storageLocation string
Storage location for webchat data. Can be localStorage or sessionStorage.
footer string
Custom footer content for the Webchat interface. Set to an empty string to remove the footer.
You can use Markdown to create links and stylize the footer text.
headerVariant string
Header visual variant. Can be solid or glass.
adminKey string
Admin key for enhanced permissions and functionality.
phone object
Phone contact information object.
title string
Display title for the phone contact.
link string
Phone number or link for the contact.
email object
Email contact information object.
title string
Display title for the email contact.
link string
Email address or mailto link for the contact.
website object
Website contact information object.
title string
Display title for the website contact.
link string
Website URL for the contact.
termsOfService object
Terms of service link object.
title string
Display title for the terms of service link.
link string
URL to the terms of service page.
privacyPolicy object
Privacy policy link object.
title string
Display title for the privacy policy link.
link string
URL to the privacy policy page.
If you omit the configuration object or leave any fields blank, they will default to the Webchat configuration set in your Dashboard.
user User
User data to update.
name string
A name for the user.
pictureUrl string
URL pointing to a picture for the user.
data object
An object containing any additional data as key-value pairs. The values can be of any type.
userKey string
A custom key to associate with the user.
Returns
restartConversation
The asynchronous window.botpress.restartConversation method ends the current conversation and starts a new one:
await window.botpress.restartConversation()
It becomes available after Webchat is ready to receive messages.
Parameters
The restartConversation method takes no parameters.
Returns
Promise<void>
A Promise that resolves to void when a new conversation has been successfully created.
sendMessage
The asynchronous window.botpress.sendMessage method sends a new message to your bot on behalf of the current user:
await window.botpress.sendMessage('<string>')
It becomes available after Webchat is ready to receive messages.
Parameters
message string
required
The message to send to the bot.
Returns
Promise<void>
A Promise that resolves to void when the message has successfully been sent.
sendEvent
The asynchronous window.botpress.sendEvent method sends a new event to your bot:
await window.botpress.sendEvent({})
It becomes available after Webchat is ready to receive messages.
Parameters
event object
required
An object containing custom data to send to the bot. Can contain any key-value pairs.
Returns
Promise<void>
A Promise that resolves to void when the event has successfully been sent.
setUnreadMessageCount
The window.botpress.setUnreadMessageCount method sets the number of unread messages to display on the Floating Action Button (FAB):
window.botpress.setUnreadMessageCount(123)
It becomes available after Webchat has been initialized.
Parameters
count number
required
The number of unread messages to display on the FAB.
Returns
on
The window.botpress.on method sets up an event listener for a given Webchat event:
window.botpress.on('<string>', (event) => {})
Parameters
type string
required
The event type to listen for. Can be any of the following event types:
| Event | Description |
|---|
conversation | Fires when a new conversation starts |
message | Fires when a message is sent |
error | Fires when an error occurs |
customEvent | Fires for custom events |
webchat:initialized | Fires when Webchat has finished loading and is ready to be opened |
webchat:ready | Fires when Webchat has been opened for the first time and is ready to receive messages |
webchat:opened | Fires when Webchat is opened |
webchat:closed | Fires when Webchat is closed |
* | Fires for any event (receives all events) |
handler function
required
Callback function that gets called when the event occurs. The function receives event data specific to each event type
as its parameter.
Returns
function
An unsubscribe function that can be called to remove the event listener.
