Sync Chat SDK for Web: Quickstart

With the Sync Chat SDK for Web, you can quickly add high-quality, real-time text chat to your app. Sync SDKs offer a ready-to-use, best-in-class user experience that you can customize completely.

This SDK also works seamlessly with the Sync Audio SDK. For more on the integrated UI, see Combine with Sync Audio below.

Try it now

There are multiple ways to try out the SDK before you start integrating.

Live apps

Go to air.live to see this SDK in action in a production app. You can instantly start a text chat and invite anyone using a link.

Code pens

Play with interactive examples in different frameworks in your browser.

These code pens are for Sync Chat only. See Combine with Sync Audio below for a code pen with both SDKs.

Mock app

You can use the mock app below to play with the style and other options. To keep your customization, click Copy as JSON and paste the style or configuration directly into your app.

Before starting

Supported browsers and devices

Desktop: Chrome, Edge, Firefox, and Safari
iOS: Chrome and Safari

Installation

The recommended way of installing is using NPM Package Manager.

Install the Sync Chat SDK using the following command:

npm install @aircore/aircore-panel-core @aircore/aircore-chat-panel

Alternatively, you can install the standalone Sync Chat SDK using the CDN:

<script type="importmap">
  {
    "imports": {
      "@aircore/aircore-panel-core": "https://unpkg.com/@aircore/aircore-panel-core/dist/index.js"
    }
  }
</script>
<script src="https://unpkg.com/@aircore/aircore-panel-core/dist/index.js"></script>
<script src="https://unpkg.com/@aircore/aircore-chat-panel/dist/index.js"></script>

Or:

<script async src="https://ga.jspm.io/npm:es-module-shims@1.7.0/dist/es-module-shims.js"></script>
<script type="importmap">
  {
    "imports": {
      "@aircore/aircore-panel-core": "https://unpkg.com/@aircore/aircore-panel-core/dist/index.js"
    }
  }
</script>
<script type="module">
  import { createClientWithPublishableKey } from 'https://unpkg.com/@aircore/aircore-panel-core/dist/index.js';
  import { ChatPanel } from 'https://unpkg.com/@aircore/aircore-chat-panel/dist/index.js';
</script>

Authenticate

This guide uses a publishable API key for a quick setup. To get your API key:

Create an app in the Developer Console.
Copy your publishable API key and use it in the next section.

Copying a publishable API key from the console.

For an overview of API keys, see Authentication.

Use a publishable API key to create the client:

import { createClientWithPublishableKey } from '@aircore/aircore-panel-core';
import { ChatPanel } from '@aircore/aircore-chat-panel';

// Create a client by passing the publishable key and the current user ID.
const client = createClientWithPublishableKey(
  'INSERT_PUBLISHABLE_KEY_HERE',
  'INSERT_USER_ID_HERE'
);

// Set the current user name and avatar.
client.setUserDisplayName('John Doe');
client.setUserAvatarUrl('https://avatar.com/40');

// Connect to the desired channel.
client.connect('INSERT_CHANNEL_ID_HERE');

// Render the panel.
const MyPanel = ChatPanel(
  '#myChatPanel', // Selector DOM target.
  {
    client: client,
    channelId: 'INSERT_CHANNEL_ID_HERE',
  }
);

For more detailed security controls, you can use a secret API key instead. See Customization.

Configuration

You configure the panel with two distinct objects:

ChatPanelConfiguration includes all chat panel-specific configuration, such as the title, share link, and other text.
Theme includes all visual configuration of the panel, such as fonts and colors.

Here is an example of how you can pass these two objects when rendering the panel:

// Render the selector target on the page first.
// Then render the panel by passing a selector, the client, and the channel ID
// that you want to connect to.

const targetElement = document.querySelector('#myChatPanel');

const myPanel = ChatPanel(
  targetElement,
  {
    client: client,
    channelId: 'INSERT_CHANNEL_ID_HERE',
    theme: {
      // You can specify a base theme to start from.
      base: 'light',
    },
    config: {
      // You can specify a title for the panel.
      panelTitle: 'My Chat Panel',
    }
  }
);

The chat panel has two distinct states: collapsed and expanded. Here is an example configuration for the panel:

const myPanelConfiguration = {
  panelTitle: 'My Chat Panel Title', // Custom title for your panel.
  panelSubtitle: 'Talking about adding a Sync panel', // Custom subtitle.
  shareLinkUrl: 'http://yourDomain.com/chat/1234', // Custom link to this chat
                                                   // in your app.

  string: {
    joinButton: "Join us", // You can override the strings displayed.
    // Add other strings that you want to customize.
  },

  collapsedStateOptions: {
    maxAvatars: 5, // Maximum number of avatars to show. The rest are shown as
                   // "+99 others".
    // Add other collapsed state options that you want to customize.
  },

  expandedStateOptions: {
    placement: 'rightTop', // The expanded view is placed relative to your
                           // collapsed view.
    // Add other expanded state options that you want to customize.
  }
};

You can launch the panel in collapsed mode only by disabling the expanded state:

const myPanelConfiguration = {
  expandedStateOptions: null,
  // Add other properties that you want to customize.
};

Similarly, you can also disable the collapsed state and only display the expanded state:

const myPanelConfiguration = {
  collapsedStateOptions: null,
  // Add other properties that you want to customize.
};

Combine with Sync Audio

If you use both the Sync Audio and Sync Chat SDKs, you can show a combined panel.

Use MediaPanel() and ChatPanel() to create the panels, using the same channel ID for both.
Call the mediaPanel object's combine() method on the chatPanel object.

    const mediaPanel = MediaPanel(
      '#my-media-panel',
      {
        client,
        channelId,
      }
    );

    const chatPanel = ChatPanel(
      null,
      {
        client,
        channelId,
      }
    );

    mediaPanel.combine(chatPanel);

To play with the combined panel, see the code pen.

You can download the source code for sample apps for this SDK from GitHub.

User experience

You can customize how users interact with the chat. When a user joins a chat, they can see the full message history for the channel.

Disable sending messages

By default, all users can send messages. To change this, set canSendMessage to false.

Automatically join the chat

By default, users can preview the chat. To join, they must press a button. When users join, they appear on the panel.

To have users join automatically, set previewBeforeJoin to false.

Theming

The Theme object has a base theme with overriding variables that you can use to customize the look and feel of your panel.

The default base theme is light. You can also choose dark or another base theme:

const myCustomTheme = {
  base: 'dark',
  overrides: {
    // You can override any of the values using your own colors.
    primaryColor: '#228B22', // Your brand color.
    textColor: '#FFFFFF',
    backgroundColor: '#000000',
    borderRadius: '20px',
    font: 'Arial', // Name of your custom font.
    // Add other values that you want to override.
    icons: {
      join: '/assets/join.svg', // Local path to your icon.
      // Add other icons that you want to customize.
    }
  }
};

You can reuse the theme across multiple panels as needed. Just define it somewhere in your app and reuse it every time you render a new panel.

Events

The client object provides events you can hook to in order to react to something that is happening on the panel.

Here is how an example of how you can subscribe and unsubscribe to events:

function onEventTriggeredCallback() {
  // Your business logic here.
};

// Subscribe to an event.
client.on(client.EVENTS.EVENT_NAME, onEventTriggeredCallback);

// Unsubscribe from the same event.
client.off(client.EVENTS.EVENT_NAME, onEventTriggeredCallback);

Full events reference can be found here.

Tear down and clean up

When you are done with the panel, you can tear down the client and the panel as follows:

// Disconnect from a specific channel ID.
client.disconnect('YOUR_CHANNEL_ID');

// Teardown of the panel.
myPanel.destroy();

// Teardown of the client.
// It disconnects automatically from all connected channels.
client.destroy();

More info

To continue customizing the panel, see Customization.
See the full API reference.
Download our sample apps.