Skip to main content
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:
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])
Last modified on November 19, 2025