HomeAPI ReferenceGuides
Guides
Start typing to search…

Widget Setup

Overview

The website widget allows customers to chat with you directly from your website—no external app required. Customers can start conversations without leaving your site, and all messages appear in your OCC Dashboard/Inbox.

Enabling the Widget

  1. Go to Settings → Inbox → Select your inbox
  2. Click the "Widget" tab
  3. Toggle "Activate Chat Widget" to ON
  4. Click Edit Inbox

Customizing the Widget

Appearance

Primary Color:

  • Choose a color that matches your brand
  • This affects the widget header, buttons, and accents

Widget Position:

  • Left: Widget appears in the bottom-left corner
  • Right: Widget appears in the bottom-right corner (default)

Avatar:

  • Upload your company logo or agent photo
  • Recommended size: 80x80 pixels
  • Supported formats: JPG, PNG

Greeting Message:

  • The first message customers see when they open the widget
  • Example: "Hi! How can we help you today?"
  • Keep it friendly and action-oriented

Open Widget by default

  • On/Off toggle

Initial message

Online message

Offline message

Callout Message:

  • A teaser message that appears before the widget is opened
  • Example: "Need help? Chat with us!"
  • This appears as a small bubble next to the widget icon

Multilingual Support

Add multiple languages so the widget automatically displays in the customer's browser language.

To add a language:

  1. Click "Add Language"
  2. Select a language from the dropdown
  3. Enter translated versions of:
    • Greeting message
    • Callout message
    • Button labels (e.g., "Start Chat," "Send Message")
  4. Click Save

How it works:

  • The widget detects the customer's browser language setting
  • If a matching translation exists, it displays that version
  • If no match, it defaults to your primary language

💡

Pro Tip: Add languages for your most common customer regions to provide a localized experience.

Installing the Widget Code

After customizing your widget, you need to add it to your website.

Step 2.a: Copy the Code

  1. In the Widget settings, scroll to "Installation"
  2. Click "Copy Code"
  3. The code is now copied to your clipboard

Step 3.b: Add Code to Your Website

The installation method depends on your website platform:

For WordPress:

  1. Install the "Insert Headers and Footers" plugin
  2. Go to Settings → Insert Headers and Footers
  3. Paste the widget code in the "Scripts in Header" section
  4. Click Save

For Shopify:

  1. Go to Online Store → Themes
  2. Click "Actions" → "Edit Code"
  3. Open the theme.liquid file
  4. Find the </head> tag
  5. Paste the widget code just before </head>
  6. Click Save

For Custom HTML Sites:

  1. Open your website's HTML template file
  2. Find the <head> section
  3. Paste the widget code just before the closing </head> tag
  4. Save and upload the file to your server

For Wix, Squarespace, or Other Builders:

  1. Look for "Custom Code" or "Code Injection" settings
  2. Paste the code in the Header section
  3. Save and publish
⚠️

Important: The code must be placed in the <head> section, NOT in the <body> section. Placing it in the body may cause the widget to malfunction.

Step 3: Test the Widget

  1. Open your website in an incognito/private browser window (to avoid cache issues)
  2. The widget should appear in the bottom corner
  3. Click the widget icon to open it
  4. Send a test message
  5. Check that the conversation appears in your OCC Dashboard/Inbox

Troubleshooting

Widget doesn't appear on the website

Check:

  • ✅ The widget is enabled in Settings → Inbox → Widget
  • ✅ The code is placed in the <head> section (not <body>)
  • ✅ Your website changes are published/live
  • ✅ Clear your browser cache or test in incognito mode

Widget appears but messages aren't received

Check:

  • ✅ The inbox is linked to a channel or has the widget enabled
  • ✅ You're logged into OCC and viewing the correct inbox
  • ✅ Check the Dashboard or Inbox for new unassigned requests

Widget appears in the wrong position

Solution:

  • Go to Settings → Inbox → Widget → Appearance
  • Change the Widget Position to Left or Right
  • Save and refresh your website

Widget shows in the wrong language

Check:

  • ✅ You've added the language in Widget → Multilingual
  • ✅ The translation is complete (greeting, callout, buttons)
  • ✅ The customer's browser language matches an available translation

Best Practices

Design:

  • ✅ Use your brand colors for consistency
  • ✅ Keep greeting messages short and friendly
  • ✅ Upload a recognizable logo/avatar
  • ✅ Test the widget on mobile devices

Multilingual:

  • ✅ Add languages for your top 3-5 customer regions
  • ✅ Use professional translations (avoid machine translation for customer-facing text)
  • ✅ Keep translations concise to fit in the widget UI

Performance:

  • ✅ Place the widget code in the <head> for fastest loading
  • ✅ Test the widget after every website update
  • ✅ Monitor the Dashboard for widget conversations

Updated 21 days ago