Listen to events - Botpress

You can listen to Webchat events within your website’s source code. This is useful if you want to:

Make your website more responsive to Webchat
Adjust UI elements depending on Webchat’s status
Handle Webchat errors on your website

With embedded Webchat

If you added Webchat to your website using the embed code, you can use the window.botpress.on method to listen to events. Just copy and paste any code snippet below into your source code. Then, you can add whatever code you want—it’ll execute whenever the event fires.

You will need:

A website with an embedded bot
Familiarity with JavaScript

Webchat is initialized

This event fires when Webchat has finished loading and is ready to be opened:

index.js

window.botpress.on('webchat:initialized', () => {
	console.log('Webchat has been initialized.');
    // Insert your code here
});

This occurs when window.botpress.init (the function in the second inject script) finishes its execution.

Webchat is ready

This event fires after Webchat has been opened for the first time and is ready to receive messages:

index.js

window.botpress.on('webchat:ready', () => {
	console.log('Webchat has been opened and is ready to receive messages.');
    // Insert your code here
});

Webchat opens

This event fires when the Webchat window is opened:

index.js

window.botpress.on('webchat:opened', () => {
    console.log('Webchat was opened.');
    // Insert your code here
});

Webchat closes

This event fires when the Webchat window is closed:

index.js

window.botpress.on('webchat:closed', () => {
    console.log('Webchat was closed.');
    // Insert your code here
});

New conversation starts

This event fires when a new conversation starts in Webchat:

index.js

window.botpress.on('conversation', (conversationId) => {
	console.log('Conversation ID: ', conversationId);
    // Insert your code here
});

Message is sent

This event fires when either the user or the bot sends a message:

index.js

window.botpress.on('message', (message) => {
	console.log('New message: ', message);
    // Insert your code here
});

Error occurs

This event fires when the bot raises an error:

index.js

window.botpress.on('error', (error) => {
	console.log('Error: ', error);
    // Insert your code here
});

Custom event

This event fires when the bot triggers a custom event:

index.js

window.botpress.on('customEvent', (event) => {
    console.log('Custom event triggered: ', event);
	// Insert your code here
});

With the Webchat React library

You will need:

A working React app that implements Webchat

If you’re using the Webchat React library, you can use the useWebchat hook’s returned on value to listen to events. Just add the following code at the top level of your Webchat implementation:

useWebchat

const { on } = useWebchat({
  clientId: '$CLIENT_ID$'
  // Insert your Client ID here
})

Then, paste any of the code snippets below to listen to events. You can add whatever code you want—it’ll execute whenever the event fires.

The useWebchat hook is incompatible with the batteries-included <Webchat> component—using them together will cause issues and unexpected behaviour.If you need to use the hook, make sure you’re manually building Webchat.

New conversation starts

This event fires when a new conversation starts in Webchat:

useEffect(() => {
  const unsubscribe = on('conversation', (conversationId) => {
    console.log('New conversation started:', conversationId)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])

Message is sent

This event fires when either the user or the bot sends a message:

useEffect(() => {
  const unsubscribe = on('message', (message) => {
    console.log('New message:', message)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])

Error occurs

This event fires when the bot raises an error:

useEffect(() => {
  const unsubscribe = on('error', (error) => {
    console.log('Error:', error)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])

Webchat visibility changes

This event fires when you change Webchat’s visibility using a Webchat Card:

useEffect(() => {
  const unsubscribe = on('webchatVisibility', (webchatVisibility) => {
    console.log('Webchat visibility changed:', webchatVisibility)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])

Configuration changes

This event fires when you change Webchat’s configuration using the Configure Webchat Card:

useEffect(() => {
  const unsubscribe = on('webchatConfig', (webchatConfig) => {
    console.log('Webchat configuration changed:', webchatConfig)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])

Custom event

This event fires when the bot triggers a custom event:

useEffect(() => {
  const unsubscribe = on('customEvent', (event) => {
    console.log('Custom event triggered:', event)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])

Bot is typing

This event fires when the bot starts/stops typing:

useEffect(() => {
  const unsubscribe = on('isTyping', (status) => {
    console.log('Bot is typing:', status)
    // Insert your code here
  })
  return () => {
    unsubscribe?.()
  }
}, [on])

​With embedded Webchat

​Webchat is initialized

​Webchat is ready

​Webchat opens

​Webchat closes

​New conversation starts

​Message is sent

​Error occurs

​Custom event

​With the Webchat React library

​New conversation starts

​Message is sent

​Error occurs

​Webchat visibility changes

​Configuration changes

​Custom event

​Bot is typing

With embedded Webchat

Webchat is initialized

Webchat is ready

Webchat opens

Webchat closes

New conversation starts

Message is sent

Error occurs

Custom event

With the Webchat React library

New conversation starts

Message is sent

Error occurs

Webchat visibility changes

Configuration changes

Custom event

Bot is typing