ChannelIO

boot

Initialize for the SDK.
Channel button shows up, and features like marketing pop-up are ready to operate.

See boot for more details.

ChannelIO('boot', bootOption: object, callback?: Function)
parametertypedescription
bootOptionobjectA boot option to initialize SDK.
callback(optional) FunctionCallback called after boot.
When boot fails, the callback passes an error object at the first argument.
When boot succeeds, the callback passes a user object at the second argument.
ChannelIO('boot', {
  pluginKey: 'YOUR_PLUGIN_KEY'
}, function onBoot(error, user) {
  if (error) {
    console.error(error);
  } else {
    console.log('boot success', user);
  }
});

shutdown

Stop all operations of the SDK and initialize internal data.

ChannelIO('shutdown');

showMessenger

Show the messenger.

ChannelIO('showMessenger');

hideMessenger

Hide the messenger.

ChannelIO('hideMessenger');

openChat

Open a chat.

A new chat is opened if you pass an empty value to chatId. In this case, if you pass a message, the message is entered in the input. If the support bot is active, the support bot runs.

The chat is opened if the chat with the given chatId exists. In this case, a message is ignored. The lounge is opened if the chat doesn't exist.

behaviorchatIdmessagenote
Open a new chat.undefinedundefinedIf the support bot is active, the support bot runs.
Open a new chat with the given message.undefinedstringIf the support bot is active, the support bot runs.
message is ignored.
Open the certain chat.string | numberundefinedIf the chatId is invalid, the lounge is opened.

📘

The behavior of opening the chat depends on mobileMessengerMode of boot option.

If mobileMessengerMode is 'newTab'(which is the default value), a chat is opened in a new tab on the mobile device. If mobileMessengerMode is 'iframe', a chat is opened in the form of an iframe in the same tab on the mobile device.

🚧

If you use openChat outside of the click event handler, it may not work properly in the Safari browser on the mobile device.

ChannelIO('openChat', chatId?: string | number, message?: string)
parametertypedescription
chatId(optional) string | numberThe id of the chat.
message(optional) stringThe string to enter in message input when a new chat is opened.
// A new chat is opened.
ChannelIO('openChat');

// A new chat is opened, and 'Text here' is entered in message input.
// The support bot runs if the support bot is active.
ChannelIO('openChat', undefined, 'Text here');

// The certain chat is opened if the chat with the id exists.
// The lounge is opened if the chat with the id does not exist.
ChannelIO('openChat', '123');

// The certain chat is opened if the chat with the id exists.
// The lounge is opened if the chat with the id does not exist.
ChannelIO('openChat', 123);

track

Track an event.

If you track a new event that has never been created, the event is newly created.
It takes a few minutes to a few hours to see the event at the desk.

ChannelIO('track', eventName: string, eventProperty?: object);
parametertypedescription
eventNamestringThe name of the event. Max 30 characters are allowed.
eventProperty(optional) objectThe property of the event.
// example 1
ChannelIO('track', 'OrderRequest');

// example 2
ChannelIO('track', 'Order', {
  "price": 100,
  "currency": 'USD'
});

onShowMessenger

Register a callback invoked when the messenger is shown.

ChannelIO('onShowMessenger', callback: Function);
parametertypedescription
callbackFunctionThe callback invoked when the messenger is shown.
ChannelIO('onShowMessenger', function onShowMessenger() {
    console.log('Messenger is shown.');
});

onHideMessenger

Register a callback invoked when the messenger is hidden.

ChannelIO('onHideMessenger', callback: Function);
parametertypedescription
callbackFunctionThe callback invoked when the messenger is hidden.
ChannelIO('onHideMessenger', function onHideMessenger() {
    console.log('Messenger is hidden.');
});

onBadgeChanged

Register a callback invoked when the count of messages that the user has not yet read.

ChannelIO('onBadgeChanged', callback: Function);
parametertypedescription
callbackFunctionThe callback invoked when the count of messages that the user has not yet read.
ChannelIO('onBadgeChanged', function onBadgeChanged(unreadCount) {
    console.log(`Unread count is changed to ${unreadCount}.`);
});

onChatCreated

Register a callback invoked when a chat is created.

ChannelIO('onChatCreated', callback: Function);
parametertypedescription
callbackFunctionThe callback invoked when a chat is created.
ChannelIO('onChatCreated', function onChatCreated() {
    console.log('New Chat is created.');
});

onFollowUpChanged

Register a callback invoked when the user changes the user’s profile.

ChannelIO('onFollowUpChanged', callback: Function);
parametertypedescription
callbackFunctionThe callback invoked when the user changes the user’s profile.
It receives the profile object as the argument.

The profile object passed to the callback's argument includes the following fields.

속성타입설명
name(optional) string | nullThe name of a user.
email(optional) string | nullThe email of a user.
mobileNumber(optional) string | nullThe mobile number of a user. It follows E.164 format.
ChannelIO('onFollowUpChanged', function onFollowUpChanged(profile) {
    console.log('User changed profile', profile);
});

onUrlClicked

Register a callback invoked when the user clicks a link.

The links that the user can click include the following list.

  • Link button/text in marketing pop-up
  • Link button/text sent by manager in chat
ChannelIO('onUrlClicked', callback: Function);
parametertypedescription
callbackFunctionThe callback invoked when the user clicks a link.
It receives the URL of the link as the argument.
ChannelIO('onUrlClicked', function onUrlClicked(url) {
  console.log(`User clicked url: ${url}`);
});

clearCallbacks

Clear all callbacks registered by following APIs.

ChannelIO('clearCallbacks');

updateUser

Update user’s information.

ChannelIO('updateUser', userObject: object, callback?: Function);
parametertypedescription
userObjectobjectObject with user’s information.
callback(optional) FunctionThe callback invoked after updating.
When it fails, the callback passes an error object at the first argument.
When it succeeds, the callback passes an user object at the second argument.

You can set the following fields to update a user’s information.

fieldtypedescription
language(optional) stringSet user’s language.
If language is ‘ko’ or ‘ja’, UI text inside ChannelTalk changes with that language. Otherwise, UI text is set with English.
profile(optional) object | nullSet user’s profile.
If you pass null, the whole profile is initialized. If you pass null to the specific field inside profile object, that specific field is initialized. An empty object is not allowed. The name of the field must follow Camel Case. If you pass mobileNumber, it must follow e.164 format.
profileOnce(optional) objectSet user’s profile.
Among the fields inside profileOnce object, only the fields with no existing value are added.
tags(optional) array | nullSet user’s tags.
Max 10 tags are allowed. If you pass null, tags are initialized. An empty array([]) is not allowed.
unsubscribeEmail(optional) booleanSet whether the user subscribes to the marketing email.
Terminates subscription if the value is true.
unsubscribeTexting(optional) booleanSet whether the user subscribes to the marketing SMS.
Terminates subscription if the value is true.

🚧

The updated user information is not reflected in real-time on the client-side.

The updateUser updates the user information on the server of ChannelTalk.
To receive the updated information for the client-side, you should boot newly.

const userObject = {
  language: 'ko',
  tags: ['a', 'b'],
  profile: {
    email: '[email protected]',
    mobileNumber: '+821012345678',
    name: 'test name',
  },
  profileOnce: {
    customerType: 'vip',
    registeredAt: '2022-11-22'
  },
  unsubscribeEmail: false,
  unsubscribeTexting: true
};

ChannelIO('updateUser', userObject, function onUpdateUser(error, user) {
  if (error) {
    console.error(error);
  } else {
    console.log('updateUser success', user);
  }
});

addTags

Add a user’s tags.

ChannelIO('addTags', tags: array, callback?: Function)
parametertypedescription
tagsstring[]Array of the tags to add.
If the same tag exists, only one tag is added. Max 10 tags allowed. Always lowercase.
callback(optional) FunctionThe callback invoked after addition.
If it fails, the callback passes an error object at the first argument.
If it succeeds, the callback passes a user object at the second argument.
ChannelIO('addTags', ['tag1', 'tag2'], function onAddTags(error, user) {
  if (error) {
    console.error(error);
  } else {
    console.log('addTags success', user);
  }
});

removeTags

Remove a user’s tags.

ChannelIO('removeTags', tags: array, callback?: Function)
parametertypedescription
tagsstring[]Array of the tags to remove.
If the corresponding tag don’t exist, that tag is ignored. null or an empty array([]) not allowed.
callback(optional) FunctionThe callback invoked after removal.
If fails, the callback passes an error object at the first argument.
If succeeds, the callback passes a user object at the second argument.
ChannelIO('removeTags', ['tag1', 'tag2'], function onRemoveTags(error, user) {
  if (error) {
    console.error(error);
  } else {
    console.log('removeTags success', user);
  }
});

setPage

Set page.
Page can be used instead of canonical URL.

🚧

Don’t pass null or undefined to page.

To reset the page, use resetPage.

ChannelIO('setPage', page: string)
parametertypedescription
pagestringThe page value to change.
ChannelIO('setPage', 'https://example.com/product');

resetPage

Reset the page value set by setPage.
If you use resetPage, the canonical URL is used as the page value.

ChannelIO('resetPage');

showChannelButton

Show channel button.

🚧

After boot, channel button shows without showChannelButton.

Only when you set hideChannelButtonOnBoot to true or call hideChannelButton, you should manually execute showChannelButton.

ChannelIO('showChannelButton');

hideChannelButton

Hide channel button.

ChannelIO('hideChannelButton');

setAppearance

Set the appearance of the theme.

  • ‘light’: use light theme.
  • ‘dark’: use dark theme.
  • ‘system’: follow system theme.
  • null: follow desk’s theme setting.
ChannelIO('setAppearance', appearance: ‘light’ | ‘dark’ | ‘system’ | null)
parametertypedescription
appearance‘light’ | ‘dark’ | ‘system’ | nullThe value of appearance to set.
ChannelIO('setAppearance', 'dark');