Cevro Widget

Cevro integrates with the helpdesks you already use—Intercom, Zendesk, LiveChat, Zoho—and that works great. But there’s a ceiling. Third-party platforms weren’t built for AI-first support, and some features just aren’t possible when you’re working within someone else’s system. The Cevro Widget removes that ceiling. It’s a native chat experience built from the ground up for AI-powered support. Faster responses, richer interactions, and new capabilities that ship here first.

Built for AI

Designed from the ground up for AI-powered support. Features like rich player context, real-time tool calls, and intelligent escalation work seamlessly—no third-party constraints.

Your Workspace, Your Widget

Connects directly to your AI Procedures, knowledge base, and back-office integrations. Everything you’ve configured in Cevro works out of the box.

New Features First

Advanced capabilities—like proactive messaging, smart nudges, and deeper personalization—will launch here first. Some features won’t be possible on third-party widgets at all.

Simple & Reliable

One integration, one source of truth. No complex API choreography between systems. Faster responses, fewer failure points.

How It Works

1. EMBED SDK → Add the Cevro SDK to your website

2. PLAYER CHATS → AI handles the conversation
   Using your knowledge base and AI Procedures

3. ESCALATION (if needed) → Transfer to human agent
   Via LiveChat or Intercom integration

All conversations are processed by Cevro’s AI engine. When escalation is needed, the conversation is transferred to your human agents through your configured helpdesk (LiveChat or Intercom).

Installation

NPM (Recommended)
CDN (Script Tag)

npm install cevro-messenger-sdk

import { CevroMessenger } from 'cevro-messenger-sdk';

const chat = new CevroMessenger({
  apiBase: 'https://chat.cevro.ai',
  workspaceId: 'your-workspace-id',
  brandId: 'your-brand-id'
});

chat.boot();

<script src="https://cdn.jsdelivr.net/npm/cevro-messenger-sdk/dist/umd/cevro-messenger.min.js"></script>
<script>
  const chat = new CevroMessenger({
    apiBase: 'https://chat.cevro.ai',
    workspaceId: 'your-workspace-id',
    brandId: 'your-brand-id'
  });
  chat.boot();
</script>

Alternative CDN: https://unpkg.com/cevro-messenger-sdk/dist/umd/cevro-messenger.min.js

Configuration

Required Settings

Setting	Type	Description
`apiBase`	string	Backend API URL (e.g., `https://chat.cevro.ai`)
`workspaceId`	string	Your workspace identifier
`brandId`	string	The brand to use for this widget instance

Optional Settings

Setting	Type	Default	Description
`alignment`	`'left'` \| `'right'`	`'right'`	Widget horizontal position
`verticalPadding`	number	`20`	Distance from bottom (px)
`horizontalPadding`	number	`20`	Distance from edge (px)
`primaryColor`	string	—	Custom brand color (hex)
`theme`	`'light'` \| `'dark'` \| object	`'light'`	Theme preset or custom theme configuration
`zIndex`	number	`2147483647`	Stacking order

Theming

Customize the widget’s appearance using theme presets or a custom theme configuration.

Theme Presets

Use built-in presets for quick styling:

const chat = new CevroMessenger({
  // ... required config
  theme: 'dark'  // or 'light' (default)
});

Preset	Description
`light`	Light background with dark text (default)
`dark`	Dark background with light text

Custom Theme Configuration

For full control, pass a theme object with specific colors:

const chat = new CevroMessenger({
  // ... required config
  theme: {
    backgroundColor: '#1e293b',
    backgroundSecondaryColor: '#0f172a',
    textColor: '#f1f5f9',
    textSecondaryColor: '#94a3b8',
    borderColor: '#334155',
    userMessageBackgroundColor: '#334155',
    userMessageTextColor: '#f1f5f9',
    headerBackgroundColor: '#1e293b',
    headerTextColor: '#f1f5f9',
    inputBackgroundColor: '#0f172a',
    borderRadius: 16,
    shadowColor: 'rgba(0, 0, 0, 0.4)',
    launcherBackgroundColor: '#334155',
    launcherIconColor: '#f1f5f9',
    launcherHoverShadowColor: 'rgba(51, 65, 85, 0.5)'
  }
});

Theme Properties Reference

Colors

Property	Type	Description
`backgroundColor`	string	Main background color of the chat window
`backgroundSecondaryColor`	string	Secondary/alternate background (e.g., input area)
`textColor`	string	Primary text color
`textSecondaryColor`	string	Secondary/muted text color
`borderColor`	string	Border color for dividers and outlines

Messages

Property	Type	Description
`userMessageBackgroundColor`	string	Background color of user message bubbles
`userMessageTextColor`	string	Text color in user message bubbles

Property	Type	Description
`headerBackgroundColor`	string	Chat header background (defaults to `backgroundColor`)
`headerTextColor`	string	Chat header text color (defaults to `textColor`)

Input

Property	Type	Description
`inputBackgroundColor`	string	Background color of the message input field

Launcher Button

Property	Type	Description
`launcherBackgroundColor`	string	Launcher button background (defaults to `primaryColor`)
`launcherIconColor`	string	Launcher button icon color
`launcherHoverShadowColor`	string	Shadow color on hover (e.g., `rgba(0, 0, 0, 0.3)`)

Style

Property	Type	Description
`borderRadius`	number	Border radius in pixels for rounded corners
`shadowColor`	string	Box shadow color with opacity (e.g., `rgba(0, 0, 0, 0.2)`)

Theme Precedence

Theme settings are merged with the following priority (highest first):

Local SDK config — Values passed in theme option during initialization
Dashboard settings — Appearance configured in Settings → Cevro
Defaults — Built-in light theme values

This allows you to configure a base theme in the dashboard while overriding specific properties in your SDK initialization.

Use the dark preset as a starting point for dark-themed websites, then override individual properties as needed.

Full Example

const chat = new CevroMessenger({
  apiBase: 'https://chat.cevro.ai',
  workspaceId: 'ws_abc123',
  brandId: 'br_xyz789',

  alignment: 'right',
  verticalPadding: 20,
  horizontalPadding: 20,
  primaryColor: '#E91E63',

  player: {
    playerId: 'player-123',
    firstName: 'John',
    email: '[email protected]',
    playerHash: 'hmac-signature'
  }
});

Player Authentication

For authenticated players, pass their information during initialization:

const chat = new CevroMessenger({
  // ... required config
  player: {
    playerId: 'player-123',
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]',
    phone: '+1234567890',
    customAttributes: {
      vipLevel: 'gold',
      totalDeposits: 5000
    },
    playerHash: 'hmac-signature'
  }
});

Supported Player Fields

Field	Type	Description
`playerId`	string	Required. Unique player identifier
`playerHash`	string	HMAC signature for identity verification
`firstName`	string	Player’s first name
`lastName`	string	Player’s last name
`email`	string	Player’s email address
`phone`	string	Player’s phone number
`customAttributes`	object	Custom key-value pairs (string, number, or boolean values)

Security: Always use playerHash (HMAC signature) in production to prevent player impersonation. Generate the hash server-side using your HMAC secret.

Public API

Method	Description
`boot()`	Initialize widget, render UI
`shutdown(options?)`	Remove widget. Pass `{ clearVisitorData: true }` to clear local storage.
`show()`	Open chat window
`hide()`	Close chat window
`toggle()`	Toggle visibility

Localization

Override default UI strings:

const chat = new CevroMessenger({
  // ... config
  locale: {
    headerTitle: 'Support Chat',
    headerSubtitle: 'We usually reply within minutes',
    inputPlaceholder: 'Type your message...',
    closedChatMessage: 'This conversation has ended',
    csatPrompt: 'How was your experience?'
  }
});

Localization strings configured in the dashboard take priority over SDK settings.

File Uploads

Players can upload files directly in the chat:

Max file size: 25MB
Allowed: Images, documents, audio, video, archives
Blocked: Executables (.exe, .dll, .js, .php, etc.)

Escalation to Human Agents

When the AI cannot resolve an issue or the player requests human help, the conversation is escalated to your configured helpdesk system.

Supported Escalation Targets

LiveChat

Conversations transfer to your LiveChat operators. Players continue chatting in the widget while agents respond from LiveChat dashboard.

Intercom

Conversations transfer to your Intercom team. Players continue chatting in the widget while agents respond from Intercom inbox.

How Escalation Works

AI determines escalation is needed (or player requests it)
Conversation is created in your helpdesk (LiveChat/Intercom)
Human agent receives the full conversation context
Messages sync bidirectionally:
- Player messages from widget → Helpdesk
- Agent responses from helpdesk → Widget

The player never leaves your website. They continue chatting in the Cevro widget while your agents respond from their familiar helpdesk interface.

Admin Settings

Configure widget appearance and security in Settings → Cevro.

Security

Setting	Purpose
HMAC Verification	Require player identity verification
HMAC Secret	Key for generating playerHash (server-side)
Allowed Domains	Whitelist domains that can embed the widget

HMAC Setup

Generate HMAC Secret

In Settings → Cevro, click Generate to create an HMAC secret key. Copy it immediately — it’s only shown once.

Store Securely

Save the secret on your backend server. Never expose it to frontend code or commit it to version control.

Generate Hash Server-Side

Create the player hash on your server:

// Node.js example
const crypto = require('crypto');

function generatePlayerHash(playerId, hmacSecret) {
  return crypto
    .createHmac('sha256', hmacSecret)
    .update(playerId)
    .digest('hex');
}

Pass to Widget

Include the hash in player.playerHash when initializing the widget.

Regenerating the HMAC key invalidates all existing playerHash values.

Allowed Domains

Restrict which websites can embed your widget:

example.com — Specific domain
*.example.com — All subdomains
* — Any domain (not recommended for production)

Appearance

Setting	Purpose
Primary Color	Brand accent color (hex)
Bubble Icon	Custom launcher button icon
Custom Logo	Brand logo in chat header

Changing Player Data

To update player information, shut down and reinitialize:

chat.shutdown({ clearVisitorData: true });

const newChat = new CevroMessenger({
  // ... config with new player data
});
newChat.boot();

Troubleshooting

Widget doesn't appear

'Domain not allowed' error

Add your domain to allowed origins in Settings → Cevro → Allowed Domains. The domain must match exactly (including subdomains).

'Invalid player hash' error

Verify HMAC secret matches between dashboard and your server.
Ensure you’re generating the hash server-side, not client-side.
Check that the playerId matches exactly between hash generation and widget init.
If you regenerated the HMAC key, all old hashes are invalidated.

Messages not sending

Verify workspaceId and brandId are correct.
Ensure the brand has automation enabled.
Check browser console for network errors.

File upload fails

Check file size (max 25MB).
Verify file type is allowed (no executables like .exe, .js, .php).

Escalation not working

Verify LiveChat or Intercom integration is configured in Settings.
Check that human agents are available in the helpdesk.
Ensure the helpdesk integration is enabled for this brand.

AI Procedures — Configure AI responses
Player Authentication — Identity verification setup
Escalation & Delegation — Human handoff strategies

Get Started

AI Ticket Handling

Analytics & Insights

Working with Human Agents

Responsible Gaming

Settings

Security & Compliance

Channels

Custom Integrations

​Why the Cevro Widget?

Built for AI

Your Workspace, Your Widget

New Features First

Simple & Reliable

​How It Works

​Installation

​Configuration

​Required Settings

​Optional Settings

​Theming

​Theme Presets

​Custom Theme Configuration

​Theme Properties Reference

​Colors

​Messages

​Header

​Input

​Launcher Button

​Style

​Theme Precedence

​Full Example

​Player Authentication

​Supported Player Fields

​Public API

​Localization

​File Uploads

​Escalation to Human Agents

​Supported Escalation Targets

LiveChat

Intercom

​How Escalation Works

​Admin Settings

​Security

​HMAC Setup

​Allowed Domains

​Appearance

​Changing Player Data

​Troubleshooting

​Related Documentation

Why the Cevro Widget?

How It Works

Installation

Configuration

Required Settings

Optional Settings

Theming

Theme Presets

Custom Theme Configuration

Theme Properties Reference

Colors

Messages

Header

Input

Launcher Button

Style

Theme Precedence

Full Example

Player Authentication

Supported Player Fields

Public API

Localization

File Uploads

Escalation to Human Agents

Supported Escalation Targets

How Escalation Works

Admin Settings

Security

HMAC Setup

Allowed Domains

Appearance

Changing Player Data

Troubleshooting

Related Documentation