Live chat widget

Add the Beamdesk widget to your website with a 3-line script tag. The widget loads from our CDN, respects privacy settings, and works across all browsers and devices.

<!-- Paste before closing </body> -->
<script src="https://cdn.beamdesk.com/widget/v1.js" async></script>
<script>
  window.Beamdesk = window.Beamdesk || {};
  window.Beamdesk.init = window.Beamdesk.init || [];
  window.Beamdesk.init.push({
    businessId: '550e8400-e29b-41d4-a716-446655440000',
    persona: 'support',
    language: 'en',
  });
</script>

Replace businessId with your workspace ID. The widget automatically uses your configured default persona unless you override it with persona parameter.

Configure widget appearance and behavior using HTML data-* attributes on the script tag. These attributes override init configuration and work without JavaScript.

<script
  src="https://cdn.beamdesk.com/widget/v1.js"
  async
  data-business-id="550e8400-e29b-41d4-a716-446655440000"
  data-persona="support"
  data-language="en"
  data-position="bottom-right"
  data-color="#6366f1"
  data-launcher-text="Chat with us"
  data-greeting="Hi! How can I help you today?"
  data-auto-escalate="true"
  data-auto-escalate-threshold="0.6"
  data-gdpr-mode="strict"
></script>

data-position accepts: bottom-left, bottom-right, bottom-center. data-color sets the primary button color in hex format.

Widget can automatically escalate to human when AI confidence falls below threshold or when customer explicitly requests help. Auto-escalation reduces frustration by connecting visitors to agents before they abandon the chat.

Auto-escalation configuration:
Enable: true
Threshold: 0.6  // When confidence < 0.6, offer human
Triggers:
  - keywords: ['agent', 'human', 'speak to someone']
  - sentiment: angry
  - max_turns: 6
  - no_resolution_after: 30000  // 30s

Behavior:
  - Prompt: "Would you like to chat with an agent?"
  - Auto-transfer: false  // Wait for customer to click
  - Queue message: "Transferring to agent..."
  - Show agent avatar: true

When auto-escalation triggers, the widget shows a prompt and waits for customer confirmation. If the customer declines, AI continues the conversation. Transfers preserve the full chat history for the receiving agent.

GDPR mode controls data residency and consent requirements. In strict mode, widget stores chat data in EU regions and requires explicit consent before processing. This is required for EU-based businesses handling customer data.

GDPR configuration:
Mode: strict  // or 'standard' or 'disabled'
Data region: eu
Consent banner:
  - Show on first visit: true
  - Message: "We use chat to support you. By continuing, you agree to our privacy policy."
  - Link: "https://your-site.com/privacy"
  - Required: true

Data retention:
  - Chat history: 90 days
  - Unidentified visitors: 30 days
  - Delete on request: enabled
  - Export on request: enabled

Customize widget appearance with custom CSS. Target widget elements with prefixed class names and override default styles. Common customizations include button size, chat bubble position, and launcher icon.

/* Custom widget styles */
.beamdesk-widget-launcher {
  width: 60px;
  height: 60px;
  border-radius: 12px;
}

.beamdesk-chat-bubble {
  max-width: 380px;
  max-height: 600px;
  box-shadow: 0 10px 40px rgba(0, 0, 0, 0.2);
}

.beamdesk-message-user {
  background-color: #6366f1;
  color: #ffffff;
}

.beamdesk-header {
  background: linear-gradient(135deg, #6366f1, #8b5cf6);
}

/* Hide widget on specific pages */
body.page-no-widget .beamdesk-widget-launcher {
  display: none;
}

Widget styles are scoped to prevent conflicts with your site CSS. Use browser dev tools to inspect widget classes and test custom styles before deploying.

Control widget behavior programmatically with window.Beamdesk API. Open widget, identify users, track events, and customize greeting based on page context.

// Open widget programmatically
window.Beamdesk.open();

// Close widget
window.Beamdesk.close();

// Identify user (passes email, name, custom data)
window.Beamdesk.identify({
  email: 'user@example.com',
  name: 'Alice Johnson',
  userId: 'user_12345',
  plan: 'Pro',
  signupDate: '2024-01-15',
  custom: {
    company: 'Acme Corp',
    role: 'admin',
  },
});

// Set greeting based on page context
window.Beamdesk.setGreeting('Hi! I see you are on the pricing page. Need help with plan selection?');

// Track custom events
window.Beamdesk.track('$view_pricing_page', {
  plan: 'Pro',
  viewed_comparison: true,
});

// Update language
window.Beamdesk.setLanguage('de');

// Switch persona
window.Beamdesk.setPersona('sales');

Use identify to pass user context before chat starts. This helps AI provide personalized responses: plan-specific answers, account-specific pricing, and order status.

• Test widget on staging site before production deployment
• Verify widget renders correctly on mobile and desktop
• Check that auto-escalation doesn't trigger too frequently
• Use identify API to provide personalized context
• Set custom greetings for high-traffic pages
• Review chat transcripts weekly to improve responses
• Monitor escalation rate and adjust confidence threshold