JavaScript Integration
Learn how to integrate OrcaHive chatbot widget using vanilla JavaScript.
6 min read
Updated 2025-01-10
Introduction
The OrcaHive JavaScript widget is the easiest way to add a chatbot to any website. This guide covers installation, configuration, and customization.
Basic Installation
Add the following code snippet before the closing </body> tag:
index.html
html
<!-- OrcaHive Widget -->
<script>
(function(w,d,s,o,f,js,fjs){
w['OrcaHiveWidget']=o;w[o] = w[o] || function () { (w[o].q = w[o].q || []).push(arguments) };
js = d.createElement(s), fjs = d.getElementsByTagName(s)[0];
js.id = o; js.src = f; js.async = 1; fjs.parentNode.insertBefore(js, fjs);
}(window, document, 'script', 'orcahive', 'https://orcahive.io/widget.js'));
orcahive('init', {
botId: 'your-bot-id-here'
});
</script>Finding Your Bot ID
Your bot ID can be found in the "Deploy" tab of your bot's dashboard.
Configuration Options
Customize the widget behavior with these options:
javascript
orcahive('init', {
// Required
botId: 'your-bot-id',
// Position
position: 'bottom-right', // 'bottom-right', 'bottom-left', 'top-right', 'top-left'
// Appearance
primaryColor: '#0066FF',
theme: 'light', // 'light' or 'dark'
// Behavior
autoOpen: false,
openDelay: 3000, // milliseconds
// Messages
welcomeMessage: 'Hi! How can I help you?',
placeholder: 'Type your message...',
// Advanced
language: 'en',
showBranding: true,
enableSounds: true
});API Methods
Control the widget programmatically:
Open Widget
javascript
// Open the chat widget
orcahive('open');Close Widget
javascript
// Close the chat widget
orcahive('close');Toggle Widget
javascript
// Toggle widget open/closed
orcahive('toggle');Send Message
javascript
// Send a message programmatically
orcahive('sendMessage', 'Hello, I need help with my order');Update User Info
javascript
// Update user information
orcahive('updateUser', {
name: 'John Doe',
email: 'john@example.com',
customData: {
userId: '12345',
plan: 'premium'
}
});Event Listeners
Listen to widget events:
javascript
// Widget opened
orcahive('on', 'open', function() {
console.log('Widget opened');
});
// Widget closed
orcahive('on', 'close', function() {
console.log('Widget closed');
});
// Message sent
orcahive('on', 'messageSent', function(message) {
console.log('User sent:', message);
});
// Message received
orcahive('on', 'messageReceived', function(message) {
console.log('Bot replied:', message);
});
// Conversation started
orcahive('on', 'conversationStart', function() {
console.log('New conversation started');
});
// Conversation ended
orcahive('on', 'conversationEnd', function() {
console.log('Conversation ended');
});Custom Styling
Override default styles with CSS:
custom-widget.css
css
/* Customize widget button */
.orcahive-widget-button {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}
/* Customize chat window */
.orcahive-chat-window {
border-radius: 16px;
box-shadow: 0 8px 32px rgba(0, 0, 0, 0.12);
}
/* Customize message bubbles */
.orcahive-message-bot {
background: #f3f4f6;
color: #1f2937;
}
.orcahive-message-user {
background: #0066FF;
color: white;
}CSS Specificity
Use
!important if your styles aren't applying due to specificity issues.Advanced Examples
Conditional Display
javascript
// Show widget only on specific pages
if (window.location.pathname === '/support') {
orcahive('init', {
botId: 'your-bot-id',
autoOpen: true
});
}
// Hide widget for logged-in users
if (!isUserLoggedIn()) {
orcahive('init', {
botId: 'your-bot-id'
});
}Custom Triggers
javascript
// Open widget when user clicks a button
document.getElementById('help-button').addEventListener('click', function() {
orcahive('open');
});
// Open widget after user scrolls
let scrolled = false;
window.addEventListener('scroll', function() {
if (!scrolled && window.scrollY > 500) {
orcahive('open');
scrolled = true;
}
});
// Open widget on exit intent
document.addEventListener('mouseout', function(e) {
if (e.clientY < 0) {
orcahive('open');
}
});Troubleshooting
Widget Not Showing
- Check that your bot ID is correct
- Verify the script is loaded (check browser console)
- Ensure no JavaScript errors are blocking execution
- Check if bot is active in your dashboard
Styling Issues
- Check CSS specificity
- Use browser dev tools to inspect elements
- Verify custom CSS is loaded after widget script
Still having issues? Contact our support team at support@orcahive.io