Cevro Messenger SDK

A lightweight JavaScript SDK for integrating Cevro AI customer support chat into any website.

Installation

Add the embed snippet to your website's <head> or before </body>:

<script>
  (function(){
    window.cevroSettings = {
      workspaceId: 'YOUR_WORKSPACE_ID',
      brandId: 'YOUR_BRAND_ID'
    };
    var c = function(){c.q.push([].slice.call(arguments))};
    c.q = [];
    window.Cevro = c;
    var s = document.createElement('script');
    s.src = 'https://cdn.cevro.ai/loader.js';
    s.async = true;
    document.head.appendChild(s);
  })();
</script>

The loader automatically fetches the latest SDK version and boots the widget.

Settings

All options are passed inside window.cevroSettings in the snippet above:

| Option | Type | Required | Description | |--------|------|----------|-------------| | workspaceId | string | Yes | Your Cevro workspace ID | | brandId | string | Yes | Brand ID for the workspace | | player | object | No | Authenticated user information (see below) | | alignment | 'left' \| 'right' | No | Horizontal position of the widget | | verticalPadding | number | No | Padding from bottom (px) | | horizontalPadding | number | No | Padding from edge (px) | | primaryColor | string | No | Primary brand color (hex) | | theme | object | No | Custom theme colors (see below) | | locale | object | No | UI text overrides (see below) | | hideDefaultLauncher | boolean | No | Hide the default launcher button | | customLauncherSelector | string | No | CSS selector for your own launcher element | | zIndex | number | No | Z-index for the widget |

Player

Identify authenticated users by adding player to cevroSettings:

<script>
  window.cevroSettings = {
    workspaceId: 'YOUR_WORKSPACE_ID',
    brandId: 'YOUR_BRAND_ID',
    player: {
      playerId: 'user-123',
      email: '[email protected]',
      firstName: 'John',
      lastName: 'Doe',
      phone: '+1234567890',
      avatar: 'https://example.com/avatar.jpg',
      createdAt: 1700000000,
      customAttributes: {
        plan: 'premium',
        accountAge: 365,
        verified: true,
      },
      playerHash: 'hmac-hash-for-verification',
    },
  };
</script>

| Field | Type | Description | |-------|------|-------------| | playerId | string | Unique user ID on your platform (required) | | email | string | User's email address | | firstName | string | User's first name | | lastName | string | User's last name | | phone | string | User's phone number | | avatar | string | Avatar URL | | createdAt | number | Unix timestamp of user creation | | customAttributes | object | Custom key-value attributes (string, number, or boolean) | | playerHash | string | HMAC hash for identity verification |

Theme

Customize widget colors via theme:

window.cevroSettings = {
  // ...
  theme: {
    backgroundColor: '#ffffff',
    textColor: '#1a1a1a',
    textSecondaryColor: '#6b7280',
    borderColor: '#e5e7eb',
    userMessageBackgroundColor: '#6366f1',
    userMessageTextColor: '#ffffff',
    agentMessageBackgroundColor: '#f3f4f6',
    agentMessageTextColor: '#1a1a1a',
    headerBackgroundColor: '#6366f1',
    headerTextColor: '#ffffff',
    inputBackgroundColor: '#f9fafb',
    borderRadius: 12,
    shadowColor: 'rgba(0,0,0,0.15)',
    launcherBackgroundColor: '#6366f1',
    launcherIconColor: '#ffffff',
    sendButtonBackgroundColor: '#6366f1',
    sendButtonIconColor: '#ffffff',
  },
};

All properties are optional. Set just primaryColor to derive all accent colors automatically, or override individual properties via theme for full control. Theme can also be managed from the admin dashboard (Settings → Cevro → Appearance).

| Property | Type | Description | |----------|------|-------------| | backgroundColor | string | Main background color | | backgroundSecondaryColor | string | Secondary/alternate background | | textColor | string | Primary text color | | textSecondaryColor | string | Secondary/muted text color | | borderColor | string | Border color | | userMessageBackgroundColor | string | User message bubble background | | userMessageTextColor | string | User message text color | | agentMessageBackgroundColor | string | Agent/AI message bubble background | | agentMessageTextColor | string | Agent/AI message text color | | headerBackgroundColor | string | Header background color | | headerTextColor | string | Header text color | | inputBackgroundColor | string | Input field background color | | launcherBackgroundColor | string | Launcher button background | | launcherIconColor | string | Launcher button icon color | | launcherHoverShadowColor | string | Launcher hover shadow color | | sendButtonBackgroundColor | string | Send button background | | sendButtonIconColor | string | Send button icon color | | fileButtonBackgroundColor | string | File button background | | fileButtonIconColor | string | File button icon color | | borderRadius | number | Border radius in pixels | | shadowColor | string | Shadow color (e.g. 'rgba(0,0,0,0.2)') |

Locale

The widget language is detected automatically from the player's browser. To override specific UI texts, use locale:

window.cevroSettings = {
  // ...
  locale: {
    headerTitle: 'Support',
    headerSubtitle: 'We typically reply within a few minutes',
    inputPlaceholder: 'Type your message...',
    preChatTitle: 'Start a conversation',
    preChatSubtitle: 'Please provide your contact information.',
    preChatFirstNameLabel: 'First name',
    preChatEmailLabel: 'Email',
    preChatSubmit: 'Start Chat',
    closedMessage: 'The agent closed the chat.',
    newConversation: 'Start New Conversation',
    csatTitle: 'How was your conversation?',
    csatSubmit: 'Submit Feedback',
    poweredBy: 'Powered by Cevro AI',
  },
};

API

Use Cevro() to control the widget:

Cevro('show');                          // Open the chat window
Cevro('hide');                          // Close the chat window
Cevro('toggle');                        // Toggle the chat window
Cevro('shutdown');                      // Remove the widget
Cevro('shutdown', { clearVisitorData: true }); // Remove and clear visitor data
Cevro('getUnreadCount');                // Get unread message count
Cevro('getVisitorId');                  // Get current visitor ID

// Identify a player after login (soft re-init, no flicker)
Cevro('identify', {
  playerId: 'user-123',
  email: '[email protected]',
  firstName: 'John',
  playerHash: 'hmac-hash-for-verification',
  customAttributes: { vipLevel: 'gold' },
});

// Update SDK config
Cevro('update', {
  player: {
    playerId: 'user-123',
    email: '[email protected]',
  },
});

Cevro('showLauncher');                  // Show the launcher button
Cevro('hideLauncher');                  // Hide the launcher button

// Pre-fill the input without sending (user can edit before sending)
Cevro('setDraft', 'I have a question about order #123');

Readiness and message recovery

The instance event API is available through Cevro('on', event, handler) (or messenger.on(event, handler) for direct SDK instances):

Cevro('on', 'subscription:ready', () => console.log('Live channel subscribed'));
Cevro('on', 'subscription:lost', () => console.log('Live channel interrupted'));
Cevro('on', 'error', ({ type, error }) => {
  if (type === 'message_recovery') console.warn('History recovery interrupted', error);
});

| Event | Meaning | | --- | --- | | boot | Widget UI is mounted. | | ready | Visitor token setup succeeded and the WebSocket connection was started. This does not guarantee a live subscription or complete history. | | subscription:ready | The visitor's live channel is subscribed. The SDK may still be catching up on history. This event can repeat after reconnecting. | | subscription:lost | The previously active visitor subscription was interrupted. The SDK buffers incoming messages until a fresh subscribed catch-up succeeds. | | error with type: 'message_recovery' | A history request, subscription wait, missing opening dependency, buffer limit, or interrupted catch-up prevented recovery from completing. A transient interruption can recover after the next subscription or recovery attempt; this event does not mean a player send failed. |

For direct SDK instances, await messenger.show() initializes the HTTP session and its initial visible history. HTTP sending can work while WebSocket connection or subscription is unavailable. Token acquisition failure rejects show() and emits websocket_connect; it does not emit ready. Built-in launchers and auto-open consume these already-reported failures. Applications calling show() directly should handle its promise rejection.

Messages retain their provider id. A persisted history or live projection also supplies localMessageId; the SDK joins it to an earlier send acknowledgement by the unchanged provider ID. afterGreetingMessageId references the exact persisted greeting identity and keeps a dependent message behind that greeting during initial load, live delivery, and reconnect recovery.

Custom Launcher

Hide the default launcher and use your own button:

<button id="my-chat-btn">Chat with us</button>

<script>
  window.cevroSettings = {
    workspaceId: 'YOUR_WORKSPACE_ID',
    brandId: 'YOUR_BRAND_ID',
    hideDefaultLauncher: true,
    customLauncherSelector: '#my-chat-btn',
  };
</script>

Clicks on #my-chat-btn will toggle the chat window. You can also control the launcher programmatically with Cevro('showLauncher') and Cevro('hideLauncher').

License

MIT

Support

For support, contact us at cevro.ai