English한국어
English

Quickstart

Suggest Edits

This document provides instructions on setting up the JavaScript SDK (referred to as "SDK" hereafter). The SDK facilitates the integration of a channel button into your web service.

Choose one of the two methods below to install the SDK:

Install Directly as a Function (Option 1)

Multi-Page Application (MPA)

If your web service spans multiple pages, with each page loading fresh static resources upon request, follow this guide.

📘

Note: Web services operating in this manner are termed as MPAs

Dive deeper into MPA(Multi-Page Application) for more insights.

Step 1: Installation

Insert the following script within the <body> tag of your HTML file:

<script>
  (function(){var w=window;if(w.ChannelIO){return w.console.error("ChannelIO script included twice.");}var ch=function(){ch.c(arguments);};ch.q=[];ch.c=function(args){ch.q.push(args);};w.ChannelIO=ch;function l(){if(w.ChannelIOInitialized){return;}w.ChannelIOInitialized=true;var s=document.createElement("script");s.type="text/javascript";s.async=true;s.src="https://cdn.channel.io/plugin/ch-plugin-web.js";var x=document.getElementsByTagName("script")[0];if(x.parentNode){x.parentNode.insertBefore(s,x);}}if(document.readyState==="complete"){l();}else{w.addEventListener("DOMContentLoaded",l);w.addEventListener("load",l);}})();
</script>

Step 2: Boot

Initialize the SDK with the boot method. The type of user is discerned based on the presence or absence of the memberId field in the given object.

For Anonymous User.

To set up the SDK for anonymous users:

ChannelIO('boot', {
  "pluginKey": "YOUR_PLUGIN_KEY" // fill your plugin key
});

For Member User.

To set up the SDK for member users:

ChannelIO('boot', {
  "pluginKey": "YOUR_PLUGIN_KEY", // Replace with your plugin key
  "memberId": "USER_MEMBER_ID", // Replace with user's member id
  "profile": { // Populate with user's profile
    "name": "USER_NAME", // Replace with user's name
    "mobileNumber": "USER_MOBILE_NUMBER", // Replace with user's mobile number
    "landlineNumber": "USER_LANDLINE_NUMBER", // Replace with user's landline number
    "customField1": "VALUE_1", // Add custom property
    "customField2": "VALUE_2" // Add custom property
});

To integrate users between your web service and Channel Talk, populate the boot option with relevant user information. Refer to memberId and profile for more details.

❗️

Security Alert: Use member hash for enhanced security

If you employ predictable memberId values like user IDs or emails, unauthorized access to this data poses a security risk. To mitigate this, enable member hash for your channel.

📘

Note: User Data Unification

Transitioning from an anonymous user to a member user state allows Channel Talk to unify these users under certain conditions. Refer to unifying customer information for more information.

Refer to the boot and boot option sections for comprehensive information about boot.
Browse ChannelIO for various methods provided by the SDK.

Single Page Application (SPA)

For web services designed as Single Page Application(SPA) or if you intend to use the SDK via the JavaScript Class, follow the instructions below:

🚧

Heads Up: Use the SDK only on the client side.

Server-side execution is not supported.

Step 1: Add a Service

Service for JavaScript

class ChannelService {
  loadScript() {
    (function(){var w=window;if(w.ChannelIO){return w.console.error("ChannelIO script included twice.");}var ch=function(){ch.c(arguments);};ch.q=[];ch.c=function(args){ch.q.push(args);};w.ChannelIO=ch;function l(){if(w.ChannelIOInitialized){return;}w.ChannelIOInitialized=true;var s=document.createElement("script");s.type="text/javascript";s.async=true;s.src="https://cdn.channel.io/plugin/ch-plugin-web.js";var x=document.getElementsByTagName("script")[0];if(x.parentNode){x.parentNode.insertBefore(s,x);}}if(document.readyState==="complete"){l();}else{w.addEventListener("DOMContentLoaded",l);w.addEventListener("load",l);}})();
  }

  boot(option, callback) {
    window.ChannelIO('boot', option, callback);
  }

  shutdown() {
    window.ChannelIO('shutdown');
  }

  showMessenger() {
    window.ChannelIO('showMessenger');
  }
  
  hideMessenger() {
    window.ChannelIO('hideMessenger');
  }

  openChat(chatId, message) {
    window.ChannelIO('openChat', chatId, message);
  }

  track(eventName, eventProperty) {
    window.ChannelIO('track', eventName, eventProperty);
  }
  
  onShowMessenger(callback) {
    window.ChannelIO('onShowMessenger', callback);
  }
  
  onHideMessenger(callback) {
    window.ChannelIO('onHideMessenger', callback);
  }
  
  onBadgeChanged(callback) {
    window.ChannelIO('onBadgeChanged', callback);
  }

  onChatCreated(callback) {
    window.ChannelIO('onChatCreated', callback);
  }

  onFollowUpChanged(callback) {
    window.ChannelIO('onFollowUpChanged', callback);
  }

  onUrlClicked(callback) {
    window.ChannelIO('onUrlClicked', callback);
  }

  clearCallbacks() {
    window.ChannelIO('clearCallbacks');
  }
  
  updateUser(userInfo, callback) {
    window.ChannelIO('updateUser', userInfo, callback);
  }

  addTags(tags, callback) {
    window.ChannelIO('addTags', tags, callback);
  }

  removeTags(tags, callback) {
    window.ChannelIO('removeTags', tags, callback);
  }

  setPage(page) {
    window.ChannelIO('setPage', page);
  }

  resetPage() {
    window.ChannelIO('resetPage');
  }

  showChannelButton() {
    window.ChannelIO('showChannelButton');
  }

  hideChannelButton() {
    window.ChannelIO('hideChannelButton');
  }

  setAppearance(appearance) {
    window.ChannelIO('setAppearance', appearance);
  }
}

export default new ChannelService();

Service for TypeScript

declare global {
  interface Window {
    ChannelIO?: IChannelIO;
    ChannelIOInitialized?: boolean;
  }
}

interface IChannelIO {
  c?: (...args: any) => void;
  q?: [methodName: string, ...args: any[]][];
  (...args: any): void;
}

interface BootOption {
  appearance?: string;
  customLauncherSelector?: string;
  hideChannelButtonOnBoot?: boolean;
  hidePopup?: boolean;
  language?: string;
  memberHash?: string;
  memberId?: string;
  pluginKey: string;
  profile?: Profile;
  trackDefaultEvent?: boolean;
  trackUtmSource?: boolean;
  unsubscribe?: boolean;
  unsubscribeEmail?: boolean;
  unsubscribeTexting?: boolean;
  zIndex?: number;
}

interface Callback {
  (error: Error | null, user: CallbackUser | null): void;
}

interface CallbackUser {
  alert: number
  avatarUrl: string;
  id: string;
  language: string;
  memberId: string;
  name?: string;
  profile?: Profile | null;
  tags?: string[] | null;
  unsubscribeEmail: boolean;
  unsubscribeTexting: boolean;
}

interface UpdateUserInfo {
  language?: string;
  profile?: Profile | null;
  profileOnce?: Profile;
  tags?: string[] | null;
  unsubscribeEmail?: boolean;
  unsubscribeTexting?: boolean; 
}

interface Profile {
  [key: string]: string | number | boolean | null | undefined;
}

interface FollowUpProfile {
  name?: string | null;
  mobileNumber?: string | null;
  email?: string | null;
}

interface EventProperty {
  [key: string]: string | number | boolean | null | undefined;
}

type Appearance = 'light' | 'dark' | 'system' | null;

class ChannelService {
  loadScript() {
    (function(){var w=window;if(w.ChannelIO){return w.console.error("ChannelIO script included twice.");}var ch:IChannelIO=function(){ch.c?.(arguments);};ch.q=[];ch.c=function(args){ch.q?.push(args);};w.ChannelIO=ch;function l(){if(w.ChannelIOInitialized){return;}w.ChannelIOInitialized=true;var s=document.createElement("script");s.type="text/javascript";s.async=true;s.src="https://cdn.channel.io/plugin/ch-plugin-web.js";var x=document.getElementsByTagName("script")[0];if(x.parentNode){x.parentNode.insertBefore(s,x);}}if(document.readyState==="complete"){l();}else{w.addEventListener("DOMContentLoaded",l);w.addEventListener("load",l);}})();
  }

  boot(option: BootOption, callback?: Callback) {
    window.ChannelIO?.('boot', option, callback);
  }

  shutdown() {
    window.ChannelIO?.('shutdown');
  }

  showMessenger() {
    window.ChannelIO?.('showMessenger');
  }

  hideMessenger() {
    window.ChannelIO?.('hideMessenger');
  }

  openChat(chatId?: string | number, message?: string) {
    window.ChannelIO?.('openChat', chatId, message);
  }

  track(eventName: string, eventProperty?: EventProperty) {
    window.ChannelIO?.('track', eventName, eventProperty);
  }

  onShowMessenger(callback: () => void) {
    window.ChannelIO?.('onShowMessenger', callback);
  }

  onHideMessenger(callback: () => void) {
    window.ChannelIO?.('onHideMessenger', callback);
  }

  onBadgeChanged(callback: (unread: number, alert: number) => void) {
    window.ChannelIO?.('onBadgeChanged', callback);
  }

  onChatCreated(callback: () => void) {
    window.ChannelIO?.('onChatCreated', callback);
  }

  onFollowUpChanged(callback: (profile: FollowUpProfile) => void) {
    window.ChannelIO?.('onFollowUpChanged', callback);
  }

  onUrlClicked(callback: (url: string) => void) {
    window.ChannelIO?.('onUrlClicked', callback);
  }

  clearCallbacks() {
    window.ChannelIO?.('clearCallbacks');
  }

  updateUser(userInfo: UpdateUserInfo, callback?: Callback) {
    window.ChannelIO?.('updateUser', userInfo, callback);
  }

  addTags(tags: string[], callback?: Callback) {
    window.ChannelIO?.('addTags', tags, callback);
  }

  removeTags(tags: string[], callback?: Callback) {
    window.ChannelIO?.('removeTags', tags, callback);
  }

  setPage(page: string) {
    window.ChannelIO?.('setPage', page);
  }

  resetPage() {
    window.ChannelIO?.('resetPage');
  }

  showChannelButton() {
    window.ChannelIO?.('showChannelButton');
  }

  hideChannelButton() {
    window.ChannelIO?.('hideChannelButton');
  }

  setAppearance(appearance: Appearance) {
    window.ChannelIO?.('setAppearance', appearance);
  }
}

export default new ChannelService();

Step2: Installation

Install the SDK using the Service.

ChannelService.loadScript();

Step 3: Boot

Initialize the SDK with the boot method. The type of user is discerned based on the presence or absence of the memberId field in the given object.

For Anonymous User.

To set up the SDK for anonymous users:

ChannelService.boot({
  "pluginKey": "YOUR_PLUGIN_KEY", // fill your plugin key
});

For Member User.

To set up the SDK for member users:

ChannelService.boot({
  "pluginKey": "YOUR_PLUGIN_KEY", // Replace with your plugin key
  "memberId": "USER_MEMBER_ID", // Replace with user's member id
  "profile": { // Populate with user's profile
    "name": "USER_NAME", // Replace with user's name
    "mobileNumber": "USER_MOBILE_NUMBER", // Replace with user's mobile number
    "landlineNumber": "USER_LANDLINE_NUMBER", // Replace with user's landline number
    "customField1": "VALUE_1", // Add custom property
    "customField2": "VALUE_2" // Add custom property
});

To integrate users between your web service and Channel Talk, populate the boot option with relevant user information. Refer to memberId and profile for more details.

❗️

Security Alert: Use member hash for enhanced security

If you employ predictable memberId values like user IDs or emails, unauthorized access to this data poses a security risk. To mitigate this, enable member hash for your channel.

📘

Note: User Data Unification

Transitioning from an anonymous user to a member user state allows Channel Talk to unify these users under certain conditions. Refer to unifying customer information for more information.

🚧

To utilize the workflow and marketing features in an SPA environment, you must use the setPage and track methods.

In an SPA environment, the SDK and Channel Talk server cannot automatically detect URL changes. For more details, please refer to How to Use the Workflow and Marketing Features in an SPA Environment.

Refer to the boot and boot option sections for comprehensive information about boot.
Browse ChannelIO for various methods provided by the SDK.

Install using an NPM module (Option 2)

Step 1: Install the module

Install the Channel Web SDK Loader NPM module.

npm install @channel.io/channel-web-sdk-loader

yarn add @channel.io/channel-web-sdk-loader

pnpm i @channel.io/channel-web-sdk-loader

Step 2: Install the SDK

Import channel-web-sdk-loader and call the loadScript function.

import * as ChannelService from '@channel.io/channel-web-sdk-loader';

ChannelService.loadScript()

Step 3: Boot

Initialize the SDK using the boot method. The user type is determined by the presence or absence of the memberId field in the passed object.

For Anonymous User.

To initialize the SDK for anonymous users, use the following code:

ChannelService.boot({
  "pluginKey": "YOUR_PLUGIN_KEY", // fill your plugin key
});

For Member User.

To initialize the SDK for member users, use the following code:

ChannelService.boot({
  "pluginKey": "YOUR_PLUGIN_KEY", // Replace with your plugin key
  "memberId": "USER_MEMBER_ID", // Replace with user's member id
  "profile": { // Populate with user's profile
    "name": "USER_NAME", // Replace with user's name
    "mobileNumber": "USER_MOBILE_NUMBER", // Replace with user's mobile number
    "landlineNumber": "USER_LANDLINE_NUMBER", // Replace with user's landline number
    "customField1": "VALUE_1", // Add custom property
    "customField2": "VALUE_2" // Add custom property
});

To integrate users between your web service and ChannelTalk, populate the boot option with relevant user information. Refer to memberId and profile for more details.

❗️

Security Alert: Use member hash for enhanced security

If you employ predictable memberId values like user IDs or emails, unauthorized access to this data poses a security risk. To mitigate this, enable member hash for your channel.

📘

Note: User Data Unification

Transitioning from an anonymous user to a member user state allows Channel Talk to unify these users under certain conditions. Refer to unifying customer information for more information.

For a detailed guide on using NPM modules, visit GitHub or npm.
Consult the TypeDoc for API documentation.

Updated about 2 months ago

What’s Next