Skip to main content

​
Step 1: Add to Your Website

Add this code to your website before the closing </body> tag: 
<script>
  window.supportUnicornSettings = {
    widgetToken: 'wgt_YOUR_TOKEN_HERE',
    position: 'right',
    locale: 'en',
    primaryColor: '#1f77b4',
    welcomeMessage: 'Hi! How can we help you?'
  };
</script>
<script src="https://your-support-unicorn-instance.com/sdk.js"></script>

​
Configuration Options

OptionTypeDefaultDescription
baseUrlstringrequiredYour Support Unicorn instance URL
widgetTokenstringrequiredWidget authentication token
positionstring'right'Widget position (‘left’ or ‘right’)
localestring'en'Language code
primaryColorstring'#1f77b4'Theme color (hex)
welcomeMessagestring'Hi! How can we help you?'Welcome message
hideMessageBubblebooleanfalseHide chat bubble

​
Example: Full HTML Page

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to My Website</h1>
  
  <!-- Your website content -->
  
  <!-- Support Unicorn Widget -->
  <script>
    window.supportUnicornSettings = {
      widgetToken: 'wgt_abc123def456',
      position: 'right',
      locale: 'en',
      primaryColor: '#590088',
      welcomeMessage: 'Hello! How can we help you today?'
    };
  </script>
  <script src="https://support.example.com/sdk.js"></script>
</body>
</html>

​
Security

​
Widget Token Authentication

  • Widget tokens are generated using nanoid (format: wgt_XXXXXXXXXXXXXXXX)
  • Tokens are validated on both HTTP and WebSocket connections
  • Invalid or disabled tokens are rejected
  • Tokens map to specific Organization + Configuration

​
Iframe Isolation

  • Widget runs in sandboxed iframe
  • Parent-iframe communication via postMessage
  • Origin validation on all messages

​
Troubleshooting

​
Widget not loading

  • Check widgetToken is correct
  • Verify ChatWidget is enabled
  • Check browser console for errors
  • Verify CORS is working

​
WebSocket connection failed

  • Ensure configuration is set
  • Check ActionCable is mounted at /cable
  • Verify widgetToken authentication

​
Messages not sending

  • Check Slack integration is configured (if using Slack)
  • Verify configuration has valid sink_main (Slack channel)
  • Check Rails logs for errors

​
Next Steps

Configuration

Customize widget appearance and behavior

JavaScript API

Programmatically control the widget