Webchat Integration Guide

Overview

The Vambe Webchat is a powerful tool that allows customers to interact with your AI assistant directly from your website, enabling real-time communication and instant support.

Quick Start

Prerequisites

Active Vambe account
Access to your website’s HTML code
Your Vambe API credentials

Installation Steps

Access Your Vambe Account

Navigate to Channels & Accounts

Go to Settings → Channels & AccountsYou can access this directly at: app.vambeai.com/settings?q=channels

Add Webchat Channel

Click “Add Channel” 2. Select “Webchat” from the available options
Give your webchat channel a descriptive name (internal use only, not visible to customers)

Get Your Integration Code

Click on the newly created Webchat channel
Click the three dots menu (⋮)
Select the code icon (<>)
Copy the provided script code

Add Code to Your Website

Paste the copied code into the <body> section of your website’s HTML, preferably just before the closing </body> tag.

<!DOCTYPE html>
<html>
  <head>
    <title>Your Website</title>
  </head>
  <body>
    <!-- Your website content -->

    <!-- Vambe Webchat Script (paste here) -->
    <script>
    window.embeddedWebchatConfig = {
      clientId: "YOUR_CLIENT_ID",
      channelId: "YOUR_CHANNEL_ID"
    };
    </script>
    <script src="https://vambeai.com/webchat.js"></script>
  </body>
</html>

Test the Integration

Refresh your website and you should see the Vambe chat widget appear in the corner of your page.

Success! Your webchat is now live on your website. Customers can start chatting with your AI assistant immediately.

Configuration Options

After the basic installation, you can customize your webchat with various options:

Basic Configuration

window.embeddedWebchatConfig = {
  // Required fields
  clientId: 'YOUR_CLIENT_ID',
  channelId: 'YOUR_CHANNEL_ID',

  // Agent customization
  agentName: 'Sofia',
  agentIconUrl: 'https://your-domain.com/agent-avatar.png',

  // Appearance
  primaryColor: '#2994FF',
  darkTheme: false,

  // Initial data collection
  askForName: true,
  askForEmail: true,
  askForPhoneNumber: false,

  // Positioning
  xPosition: 20,
  yPosition: 20,

  // Language
  language: 'es', // "es" or "en"

  // Custom text
  chatWithUsText: 'Chat with us',

  // Suggested questions
  suggestedQuestions: [
    'What services do you offer?',
    'How can I get started?',
    'What are your pricing plans?',
  ],
};

Configuration Reference

string

required

Your Vambe client ID (found in the integration code)

string

required

Your webchat channel ID (found in the integration code)

string

default:"\"\""

The name of the agent displayed in the chat. Example: "Sofia", "Customer Support"

string

default:"\"\""

URL to the agent’s avatar image. Must be a valid image URL (JPG, PNG, SVG, etc.)Example: "https://your-domain.com/avatar.png"

string

The user ID from your system. Use this if you’re embedding the webchat on a page where users are already logged in.This allows you to:

Track conversations by your user IDs
Link chat history across sessions
Use with POST /api/public/webchat/contact/add-metadata endpoint

string

The user’s name from your system. Use when embedding on authenticated pages.

boolean

default:false

Request user’s phone number before starting the chat.

boolean

default:false

Request user’s email before starting the chat.

boolean

default:false

Request user’s name before starting the chat. If not provided, contact will be named “Webchat Contact” in Vambe.

boolean

default:false

Enable dark theme for the webchat widget.

string

default:"\"#2994FF\""

Primary color for the chat widget. Must be a valid hex color code.Examples: "#2994FF", "#FF5733", "#00AA00"

string

default:"\"es\""

Chat interface language. Options: "es" (Spanish) or "en" (English)

array

default:[]

Up to 4 suggested questions displayed to start the conversation.Example:

suggestedQuestions: [
  'What services do you offer?',
  'How can I get started?',
  'What are your pricing plans?',
  'How do I contact support?',
];

string

default:"\"\""

Text displayed next to the chat button. Example: "Chat with us", "Need help?"

number

default:20

Horizontal position of the chat button in pixels from the right edge.

number

default:20

Vertical position of the chat button in pixels from the bottom edge.

Advanced Examples

Example 1: E-commerce Website

<script>
  window.embeddedWebchatConfig = {
    clientId: 'YOUR_CLIENT_ID',
    channelId: 'YOUR_CHANNEL_ID',

    // Branding
    agentName: 'Shopping Assistant',
    agentIconUrl: 'https://yourshop.com/images/assistant-avatar.png',
    primaryColor: '#FF6B6B',

    // Collect email for order updates
    askForEmail: true,
    askForName: true,

    // Custom message
    chatWithUsText: 'Need help shopping?',

    // Product-related suggestions
    suggestedQuestions: [
      "What's on sale today?",
      'Do you have free shipping?',
      'How do I track my order?',
      "What's your return policy?",
    ],

    language: 'en',
  };
</script>
<script src="https://vambeai.com/webchat.js"></script>

Example 2: Logged-in User Area

<!-- For authenticated users, pass their info -->
<script>
  window.embeddedWebchatConfig = {
    clientId: 'YOUR_CLIENT_ID',
    channelId: 'YOUR_CHANNEL_ID',

    // User identification (from your system)
    externalUserId: '<%= current_user.id %>', // Your user ID
    externalUserName: '<%= current_user.name %>', // Your user name

    // Skip asking for info since user is logged in
    askForName: false,
    askForEmail: false,

    // Personalized
    agentName: 'Support Team',
    primaryColor: '#4A90E2',
    language: 'en',
  };
</script>
<script src="https://vambeai.com/webchat.js"></script>

Example 3: Multilingual Support

// Detect user's browser language
const userLang = navigator.language.startsWith('es') ? 'es' : 'en';

window.embeddedWebchatConfig = {
  clientId: 'YOUR_CLIENT_ID',
  channelId: 'YOUR_CHANNEL_ID',

  language: userLang,

  // Language-specific suggestions
  suggestedQuestions:
    userLang === 'es'
      ? [
          '¿Qué servicios ofrecen?',
          '¿Cómo puedo empezar?',
          '¿Cuáles son sus precios?',
        ]
      : [
          'What services do you offer?',
          'How can I get started?',
          'What are your prices?',
        ],

  chatWithUsText: userLang === 'es' ? 'Habla con nosotros' : 'Chat with us',
};

Example 4: Dark Theme for Dark Websites

<script>
  window.embeddedWebchatConfig = {
    clientId: 'YOUR_CLIENT_ID',
    channelId: 'YOUR_CHANNEL_ID',

    // Dark theme for dark websites
    darkTheme: true,
    primaryColor: '#BB86FC',

    agentName: 'Night Owl Support',
    chatWithUsText: "We're here 24/7",
  };
</script>
<script src="https://vambeai.com/webchat.js"></script>

Customization Tips

Choosing Colors

Primary Color: Used for buttons, headers, and accents
Brand Alignment: Use your brand’s primary color
Contrast: Ensure good contrast with white/dark backgrounds
Test: Test with both light and dark themes

// Brand color examples
primaryColor: '#2994FF'; // Vambe blue
primaryColor: '#FF6B6B'; // E-commerce red
primaryColor: '#4CAF50'; // Success green
primaryColor: '#9C27B0'; // Tech purple

// Bottom right (default)
xPosition: 20,
yPosition: 20

// Bottom left
xPosition: 20,
yPosition: 20,
// + CSS: right -> left position

// Custom positioning
xPosition: 100,  // Further from edge
yPosition: 80    // Higher up

Creating Effective Suggested Questions

✅ Good Examples:

suggestedQuestions: [
  'What are your business hours?', // Practical
  'How much does it cost?', // Clear
  'Can you help me track my order?', // Specific
  'Do you offer custom solutions?', // Open-ended
];

❌ Avoid:

suggestedQuestions: [
  'Hello', // Too vague
  'I have a question', // Not specific
  'Click here', // Not a question
  'Tell me everything', // Too broad
];

Integration with User Data

Pass User Information

If users are logged in on your website, pass their information:

// Example with template engine (EJS, Handlebars, etc.)
window.embeddedWebchatConfig = {
  clientId: "YOUR_CLIENT_ID",
  channelId: "YOUR_CHANNEL_ID",

  // User info from your session
  externalUserId: "<%= user.id %>",
  externalUserName: "<%= user.full_name %>",

  // Skip collection if already have data
  askForName: false,
  askForEmail: <%= user.email ? 'false' : 'true' %>
};

Add Metadata After Chat Start

Use the webchat metadata endpoint to enrich contact data:

// After user interacts with chat
async function enrichChatContact(externalUserId, userData) {
  await fetch('https://api.vambe.me/api/public/webchat/contact/add-metadata', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'your_api_key_here',
    },
    body: JSON.stringify({
      externalUserId: externalUserId,
      metadata: {
        subscription_tier: userData.tier,
        account_status: userData.status,
        lifetime_value: userData.ltv.toString(),
        last_purchase: userData.lastPurchaseDate,
      },
    }),
  });
}

Common Integrations

WordPress

Add to your theme’s footer.php before </body>:

<script>
window.embeddedWebchatConfig = {
  clientId: "<?php echo get_option('vambe_client_id'); ?>",
  channelId: "<?php echo get_option('vambe_channel_id'); ?>",
  agentName: "<?php bloginfo('name'); ?> Support",
  language: "<?php echo substr(get_locale(), 0, 2); ?>"
};
</script>
<script src="https://vambeai.com/webchat.js"></script>

React/Next.js

// components/VambeChat.tsx
import { useEffect } from 'react';

export function VambeChat() {
  useEffect(() => {
    // Set configuration
    (window as any).embeddedWebchatConfig = {
      clientId: process.env.NEXT_PUBLIC_VAMBE_CLIENT_ID,
      channelId: process.env.NEXT_PUBLIC_VAMBE_CHANNEL_ID,
      agentName: "Support Team",
      primaryColor: "#2994FF",
      language: "en",
      suggestedQuestions: [
        "How can I upgrade my plan?",
        "Do you offer a free trial?",
        "How do I contact sales?"
      ]
    };

    // Load script
    const script = document.createElement('script');
    script.src = 'https://vambeai.com/webchat.js';
    script.async = true;
    document.body.appendChild(script);

    return () => {
      // Cleanup if needed
      document.body.removeChild(script);
    };
  }, []);

  return null;
}

// In your layout/page
import { VambeChat } from '@/components/VambeChat';

export default function Layout({ children }) {
  return (
    <>
      {children}
      <VambeChat />
    </>
  );
}

Vue.js

<!-- components/VambeChat.vue -->
<template>
  <div></div>
</template>

<script>
export default {
  name: 'VambeChat',
  mounted() {
    window.embeddedWebchatConfig = {
      clientId: process.env.VUE_APP_VAMBE_CLIENT_ID,
      channelId: process.env.VUE_APP_VAMBE_CHANNEL_ID,
      agentName: 'Customer Support',
      primaryColor: '#42b983',
      language: this.$i18n.locale,
    };

    const script = document.createElement('script');
    script.src = 'https://vambeai.com/webchat.js';
    document.body.appendChild(script);
  },
};
</script>

Shopify

Add to Online Store → Themes → Edit Code → theme.liquid before </body>:

<script>
window.embeddedWebchatConfig = {
  clientId: "{{ settings.vambe_client_id }}",
  channelId: "{{ settings.vambe_channel_id }}",
  agentName: "{{ shop.name }} Support",
  primaryColor: "{{ settings.color_primary }}",
  askForEmail: true,
  language: "{{ request.locale.iso_code }}",
  suggestedQuestions: [
    "Do you ship internationally?",
    "What's your return policy?",
    "How can I track my order?"
  ]
};
</script>
<script src="https://vambeai.com/webchat.js"></script>

Advanced Features

Conditional Loading

Only load webchat on specific pages:

// Only on product and checkout pages
if (
  window.location.pathname.includes('/products') ||
  window.location.pathname.includes('/checkout')
) {
  window.embeddedWebchatConfig = {
    clientId: 'YOUR_CLIENT_ID',
    channelId: 'YOUR_CHANNEL_ID',
    chatWithUsText: 'Need help with your purchase?',
  };

  const script = document.createElement('script');
  script.src = 'https://vambeai.com/webchat.js';
  document.body.appendChild(script);
}

Dynamic User Identification

// When user logs in, update webchat config
function initializeWebchatForUser(user) {
  window.embeddedWebchatConfig = {
    clientId: 'YOUR_CLIENT_ID',
    channelId: 'YOUR_CHANNEL_ID',
    externalUserId: user.id,
    externalUserName: user.name,
    askForName: false,
    askForEmail: false,
  };

  // Reload webchat with user context
  const script = document.createElement('script');
  script.src = 'https://vambeai.com/webchat.js';
  document.body.appendChild(script);
}

Custom Styling

While the widget is pre-styled, you can adjust positioning and behavior:

/* Hide webchat on mobile */
@media (max-width: 768px) {
  #vambe-webchat {
    display: none;
  }
}

/* Custom z-index if needed */
#vambe-webchat {
  z-index: 9999 !important;
}

Best Practices

Performance

Load Asynchronously: The script loads async by default
After Page Load: Consider loading after main content
Lazy Load: Load only when user interacts

// Load on first user interaction
let chatLoaded = false;

document.addEventListener(
  'mousemove',
  function loadChat() {
    if (!chatLoaded) {
      chatLoaded = true;
      // Load webchat script
      const script = document.createElement('script');
      script.src = 'https://vambeai.com/webchat.js';
      document.body.appendChild(script);

      // Remove listener
      document.removeEventListener('mousemove', loadChat);
    }
  },
  { once: true },
);

User Experience

Collect Minimal Info: Only ask for necessary information
Clear Suggestions: Provide helpful suggested questions
Brand Consistency: Match your website’s colors and style
Mobile Friendly: Test on mobile devices
Response Time: Configure AI for quick responses

Privacy & Compliance

<!-- Add privacy notice if collecting emails/phones -->
<script>
  window.embeddedWebchatConfig = {
    clientId: 'YOUR_CLIENT_ID',
    channelId: 'YOUR_CHANNEL_ID',
    askForEmail: true,
    // Note: Inform users about data collection in your privacy policy
  };
</script>

Troubleshooting

Check script is loaded

Open browser console and verify:

console.log(window.embeddedWebchatConfig);

Should show your configuration object.

Verify IDs are correct

Check that clientId and channelId match your Vambe account settings.

Check for JavaScript errors

Open browser DevTools (F12) → Console tab Look for errors related to the webchat script.

Verify script source

Ensure https://vambeai.com/webchat.js is accessible and loading.

Z-index: If widget appears behind other elements, adjust z-index
Mobile: Test responsiveness on different screen sizes
Colors: Verify hex color codes are valid
Images: Ensure avatar URL is accessible and CORS-friendly

Data Not Syncing

External User ID: Verify externalUserId matches your system
Metadata Endpoint: Use correct endpoint for webchat contacts
API Key: Ensure API key has proper permissions

Testing Your Integration

Local Testing

Open your website in a browser
Click the chat button - should open chat interface
Send a test message - verify it appears in Vambe dashboard
Check contact creation - go to Vambe → Contacts
Verify metadata - if using externalUserId, check it’s saved

Production Checklist

Webchat Metadata Endpoint - Add metadata to webchat contacts
Contact Management - Manage webchat contacts
Analytics - Track webchat performance
Webhooks - Real-time notifications for webchat events

​Overview

​Quick Start

​Prerequisites

​Installation Steps

​Configuration Options

​Basic Configuration

​Configuration Reference

​Advanced Examples

​Example 1: E-commerce Website

​Example 2: Logged-in User Area

​Example 3: Multilingual Support

​Example 4: Dark Theme for Dark Websites

​Customization Tips

​Choosing Colors

​Positioning the Widget

​Creating Effective Suggested Questions

​Integration with User Data

​Pass User Information

​Add Metadata After Chat Start

​Common Integrations

​WordPress

​React/Next.js

​Vue.js

​Shopify

​Advanced Features

​Conditional Loading

​Dynamic User Identification

​Custom Styling

​Best Practices

​Performance

​User Experience

​Privacy & Compliance

​Troubleshooting

​Widget Not Appearing

​Widget Styling Issues

​Data Not Syncing

​Testing Your Integration

​Local Testing

​Production Checklist

​Related Resources

Overview

Quick Start

Prerequisites

Installation Steps

Configuration Options

Basic Configuration

Configuration Reference

Advanced Examples

Example 1: E-commerce Website

Example 2: Logged-in User Area

Example 3: Multilingual Support

Example 4: Dark Theme for Dark Websites

Customization Tips

Choosing Colors

Positioning the Widget

Creating Effective Suggested Questions

Integration with User Data

Pass User Information

Add Metadata After Chat Start

Common Integrations

WordPress

React/Next.js

Vue.js

Shopify

Advanced Features

Conditional Loading

Dynamic User Identification

Custom Styling

Best Practices

Performance

User Experience

Privacy & Compliance

Troubleshooting

Widget Not Appearing

Widget Styling Issues

Data Not Syncing

Testing Your Integration

Local Testing

Production Checklist

Related Resources