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.

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.

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>

API keys

To start using the Sync Chat SDK you will need to create an app in the Developer Console and choose between one of the two different API Keys provided to you. To learn more about the two different API Keys so that you can choose the right one based on your needs, please refer to Authentication

Copying a publishable API key from the console.

Client initialization with a publishable API key

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',
  }
);

Client initialization with a secret API key and session auth token

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

// Create a client by passing the session authorization token and the current
// user ID.
const client = createClientWithSessionAuthToken(
  'INSERT_SESSION_AUTHORIZATION_TOKEN_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');

// Register for the event for tokens that are about to expire.
client.on('sessionAuthTokenNearingExpiry', function () {
  // Call your backend and get a new session authorization token.
  // Once you have the token, update it on the client.
  client.updateAuthToken(newToken);
});

// Then render the panel by passing a selector, the client, and the channel ID
// that you want to connect to.
const myPanel = ChatPanel(
  '#myChatPanel', // A string containing one or more selectors to match or an
                  // element.
  {
    client: client,
    channelId: 'INSERT_CHANNEL_ID_HERE',
  }
);

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.
};

User experience

To customize the user experience, you can choose which users can send messages using the canSendMessage flag.

The panel shows all users as they join. By default, all users can send messages.

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('EVENT_NAME', onEventTriggeredCallback);

// Unsubscribe from the same event.
client.off('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();

Full reference documentation

Reference documentation can be found here.