JS API & events
Control the DGbot widget programmatically and react to conversation events from your own JavaScript.
Commands
All commands are called via window.DGbot(command, args):
| Command | Arguments | Description |
|---|---|---|
open | — | Open the chat widget |
close | — | Close the chat widget |
toggle | — | Toggle open/close |
identify | { userId, name, email, userHash } | Pass verified visitor identity |
send | { message: string } | Send a message as the visitor |
reset | — | Clear conversation and start fresh |
hide | — | Hide the widget entirely (no launcher) |
show | — | Show the widget after hide() |
Examples:
js
// Open the widget
window.DGbot('open')
// Close when navigating to checkout
window.DGbot('close')
// Send a pre-filled message
window.DGbot('send', { message: 'I need help with my order' })
// Identify the logged-in user
window.DGbot('identify', {
userId: 'user_12345',
name: 'Jane Smith',
email: 'jane@example.com',
userHash: 'hmac_signature_from_server'
})Events
Subscribe to widget events with window.DGbot('on', event, handler):
| Event | Payload | Fires when |
|---|---|---|
widget:open | — | Widget is opened |
widget:close | — | Widget is closed |
conversation:start | { conversationId } | First message is sent |
message:sent | { message, conversationId } | Visitor sends a message |
message:received | { message, conversationId } | Bot sends a response |
lead:captured | { name, email, conversationId } | Lead form is submitted |
handoff:requested | { conversationId } | Visitor requests a human |
Example — track widget opens in Google Analytics:
js
window.DGbot('on', 'widget:open', function() {
gtag('event', 'chat_opened', {
event_category: 'engagement',
event_label: 'dgbot_widget'
})
})Example — fire a conversion when a lead is captured:
js
window.DGbot('on', 'lead:captured', function(data) {
gtag('event', 'generate_lead', {
event_category: 'lead',
value: data.email
})
// Also send to your own backend
fetch('/api/leads', {
method: 'POST',
body: JSON.stringify(data)
})
})Usage examples
Open widget on button click:
js
document.getElementById('chat-btn').addEventListener('click', function() {
window.DGbot('open')
})Pre-fill a message based on page context:
js
// On a specific product page, open with a relevant message
if (window.location.pathname.includes('/products/')) {
window.DGbot('on', 'widget:open', function() {
window.DGbot('send', {
message: 'I have a question about ' + document.title
})
})
}Show widget only on specific pages:
js
if (window.location.pathname !== '/checkout') {
window.DGbot('show')
} else {
window.DGbot('hide')
}