API Website Chat Button

Display a chat window in custom page element

Localization

Change the chat appearance

Edit chat user

JavaScript Methods

Callbacks

JS Parameters in online chatbot

Dispatching a Key Action with a Hook

Note: Everything described in the article works only with the code for placing the button on the site, copied in the Kommo interface.

You need to place the window to configure a button on the site.crmPluginConfig settings object anywhere on the page before including the code for the button itself.

window.crmPluginConfig = { 
  hidden: false, // hide button on page load
  color: '#000', // change button color, will ignore the color configured in Kommo

  onlinechat: { 
    mode: 'widget', // it can also be 'frame', more on that below
    user_id: '', // online chat user id (optional parameter)

    locale: { 
      extends: "com", 
      compose_placeholder: "write your question...", 
    }, 

    theme: { 
      header: false, 
    },
  }, 
};

Let’s take a closer look at the online chat settings.

Display a chat window in a custom page element

window.crmPluginConfig = {
 onlinechat: { 
   mode: 'frame', 
   container: '#custom_chat_holder', 
 }, 
};

In this case, when clicking on the online chat icon in the button, the chat will open not in a pop-up block next to the button but in an arbitrary page element specified in the container property.

Note:  In this mode, incoming pop-up messages next to the button stop working; with a new message on the button, the counter of unread messages only increases, but there will be no pop-up message.

Localization

Full list of strings available for localization:

window.crmPluginConfig = {
 onlinechat: {
  locale: { 
    extends: 'en',
    date_format: 'dd.MM.YYYY', 
    time_format: 'HH:mm', 
    compose_placeholder: 'Write a message...',
    delivery_status_sending: 'Sending', 
    delivery_status_sent: 'Sent', 
    delivery_status_read: 'Read', 
    delivery_status_error: 'Error', 
    powered_by: 'Powered by', 
    new_messages: 'New messages' 
  }, 
 }, 
};

You can send only the necessary strings for translation while specifying the source locale via extends; now the online chat “out of the box” supports three localizations en, es, pt.

For date_format and time_format you can specify any valid values from the documentation of the date-fns library.

Change the chat appearance

window.crmPluginConfig = {
 onlinechat: {
  theme: {
   background: 'yellow', // background
   system_color: 'pink', // color of system texts (delivery status, date)
   header: { // you can specify header: false, then it will not be rendered at all
     background: 'skyblue', // the top of the chat background color 
     color: 'black', // top text color
   }, 
   message: {
     outgoing_background: 'red', // user message background 
     outgoing_color: 'white', // user message color
     incoming_background: 'blue', // operator response background 
     incoming_color: 'white', // operator response color
   }, 
   compose: { 
     height: 100, // minimum height in pixels (maximum 170px, cannot be changed)     
     button_background: 'black', // submit button background
   } 
  }, 
 }, 
};

All colors must be specified in a format that can be processed using CSS in the browser (string value as in the example, hex code, rgb, rgba).

Edit chat user

Use the user_id property to create your online chat user ID. It can be useful in cases where you want to continue the conversation in an already existing chat if the user is logged in from another device.

Usage example:

  1. The client of the online store is authorized in his account and makes the dialogue in the online chat (where the user_id was previously transferred)
  2. The same client decides to log in from another device (for example, from a mobile phone)
  3. After the client is authorized in his account, we pass the same user_id
  4. When a client opens the online chat window, an existing dialog with the entire correspondence history will appear.

It is strongly recommended to hash user_id using any encryption algorithm convenient for you (SHA-256, MD-5, etc.) to protect against gaining access to the conversation by iterating over the id.

window.crmPluginConfig = {
 onlinechat: {
  user_id: 'abc123'
 }, 
};

JavaScript Methods

For working with chats, a special JavaScript function crmPlugin is also provided; it can be used anywhere after connecting the button code.

Supported methods:

  • crmPlugin(‘runChatShow’) – show chat
  • crmPlugin(‘runChatHide’) – hide chat

Sometimes, we need to destroy the current button instance and initialize a new one, for example, to start a chat with a different user_id.

For destroying an instance, a method is provided:

  • crmPlugin(‘runDestroy’) – will remove the current button instance

Callbacks

Callbacks are also provided to respond to events occurring in the button and online chat.

crmPlugin('onChatShow|onChatHide', function () {
  // when opening to open/close the chat
});

crmPlugin('onChatReady', function () {
  // the chat is initialized,
  // you can work with it via the JavaScript API
  crmPlugin('runChatShow');
});

crmPlugin('onButtonClick', function (service, link) {
  // when clicking on the button
  // incoming parameters:
  // service code
  // url of the clicked link
});

crmPlugin('onConversationsChange', function (conversations) {
   // when changing conversations
   //
   // when multi-conversations are disabled, the event will work 1 time,
   // where conversations will be false
   //
   // incoming parameters:
   // conversations - array of visible conversations

  // the format of the conversation
  //
  // {
  //   name: 'A123',
  //   is_closed: true | false,
  //   last_message: {
  //     media: {
  //       url: 'https://path_to_resource.mp4',
  //       thumbnail: 'https://path_to_preview.jpg',
  //     } | undefined,
  //     created_at: 1655283158457,
  //     is_out: true | false,
  //     text: 'Hello',
  //     type: 'text' | 'video' | 'photo',
  //     author: {
  //       name: author.name,
  //     } | undefined,
  //   },
  // },
});

JS Parameters in online chatbot

You can pass arbitrary parameters to the online chatbot using the crm_plugin.setMeta method and, based on these parameters, build different bot behavior chains.

For example, a user is authorized on your site, and you would like to greet him by name. In this case, you need to call the following code on your site:

var USER_NAME = ""; 
crm_plugin.setMeta({ 
  bot_params: { 
    username: USER_NAME 
  } 
});

In the welcome message of the online chatbot, write: hello, {{bot_params.username}}.

Also, the online chatbot supports the condition with the bot_params check in the first step, so you can easily implement, for example, multilingualism in the welcome message.

On your site, you need to forward the parameter with the current locale of the user:

var LOCALE = "com"; // Get the locale via geoip, or the browser API
crm_plugin.setMeta({
 bot_params: {
  locale: LOCALE 
 } 
});

In the bot, we put the condition in the first place; in the text area of the condition, we add the following code:

// as you can see, here is an array
// therefore conditions "and" 
// there can be several
[
  {
    "term1": "{{bot_params.locale}}",
    "term2": "com",
    "operation": "="
  }
]

Now, if the user has entered the site and we have determined his language is English, we will lead him along the bot branch with the English language.

You can also add scripts in other languages through the block interface, and there is always a common “otherwise” block, which will contain an alternative script branch if the user does not fall under any of our conditions.

Dispatching a Key Action with a Hook

To send your own hook to fire a key action, you need to execute the following code anywhere after connecting the button code or on some browser event (for example, on a button click) execute the following code:

crmPlugin('sendKeyActionHook', 'Hook name'); // which you set in the trigger condition of the key action in the paragraph "custom hook"