yandex

Documentation

Chat creation

Use web constructor to easily create and configure chat. Use existing plugin: WordPressOpencartJoomlaDrupal

To make chat appear on your site copy javascript code from constructor to your site html head element. It's enough to put it once. Site chat will be updated automatically on constructor settings change.

Chat's embed code

<script id="chatBroEmbedCode"> /* Chatbro Widget Embed Code Start */ function ChatbroLoader(chats, async) { async = !1 !== async; var params = { embedChatsParameters: chats instanceof Array ? chats : [chats], lang: navigator.language || navigator.userLanguage, needLoadCode: 'undefined' == typeof Chatbro, embedParamsVersion: localStorage.embedParamsVersion, chatbroScriptVersion: localStorage.chatbroScriptVersion }, xhr = new XMLHttpRequest; xhr.withCredentials = !0; xhr.onload = function() { eval(xhr.responseText); }; xhr.onerror = function() { console.error('Chatbro loading error') }; xhr.open('GET', 'https://www.chatbro.com/embed.js?' + btoa(unescape(encodeURIComponent(JSON.stringify(params)))), async); xhr.send(); } /* Chatbro Widget Embed Code End */ ChatbroLoader({ encodedChatId: 'YOUR ENCODED CHAT_ID' }); </script>

On-the-fly creation

For example you want different chats for different pages of your site. In case you have video hosting site you can make different chat for each video. Generate these chats on the fly using the dynamic chats feature. Check out detailed explanation.

Parameters

Parameters passed to ChatbroLoader function overrides web constructor settings from database.

There are three main chooses:

  • Static Inserted into static div on the page.
  • Movable It is resizable and movable. You can create div container anywhere on the page.
  • History The same as static, embedded in static div. History divided on the pages which will be indexed by search robots.

ParameterTypeValue
Chat identificators
encodedChatIdStringCreated automatically when you create a chat using constructor.
encodedChatGuidStringInteger number encoded by md5 algorithm and used to identify chats.
chatAliasStringShort chat name that you can set in chat constructor.
Common
chatTitleStringTitle of chat.
chatLanguageStringChat interface language: [auto, en, enrtl, ru, pt, fr, fa, es, nl, de, ro, tt, bg, ar, tr]
Default auto
parentEncodedChatIdStringUsed on creating dynamic chat. More info.
Default null
chatGreetingStringShow concise message when loading chat.
Default null
Colors
chatHeaderBackgroundColorStringChat background color. CSS format.
Default #2D3341
chatHeaderTextColorStringHeader text color.
Default #FFFFFF
chatBodyBackgroundColorStringMessage block background color.
Default #F7F8FC
chatBodyTextColorStringMessage block text color.
Default #121212
chatInputBackgroundColorStringInput block background color.
Default #FFFFFF
chatInputTextColorStringInput block text color.
Default #353535
chatLinksTextColorStringLinks color
Default #2B6DAD
coloredUserNamesBooleanEnable or disabled colored usernames.
Default false
Layout
isStaticBooleanFreely movable chat window.
Default false
chatStateStringInitial state: 'maximized' or 'minimized'.
Default maximized
containerDivIdStringChat container div id. Mandatory parameter for static chat. Can be missed for movable chat. If container will not be found on page, it will be created automatically after embed code or page bottom.
Maximized chat
chatHeightStringChat height. The minimum available chat height is 238 pixels. You can use various units for sizes.
Default 250px
chatWidthStringChat width. The minimum available chat width is 290 pixels with avatars turned on and 250 pixels if they are disabled. You can use various units for sizes.
Default 100% for static chat and 350px for movable chat
chatTopStringTop-left Y-coordinate of opened chat. Indentation of top will be given priority over indentation of bottom. Ignored for static chat.
Default null
chatLeftStringTop-left X-coordinate of opened chat. Indentation of left will be given priority over indentation of right. Ignored for static chat.
Default null
chatBottomStringBottom-right Y-coordinate of opened chat. Ignored if chat is static.
Default 2vh
chatRightStringBottom-right X-coordinate of opened chat. Ignored if chat is static.
Default 2vw
showChatBorderBooleanShow chat with side borders.
Default false
showChatShadowBooleanShadow of chat.
Default false
Minimized chat
minimizedChatTitleStringTitle for movable minimized chat.
Default null
minimizedChatIconStringIcon for movable minimized chat. Available next values: [icon_1, icon_2, icon_3, icon_4, icon_5, icon_6, icon_7].
minimizedChatBorderRadiusStringRadius for movable minimized chat.
Default 5px
minimizedChatPositionStringPosition for movable minimized chat. Available next values: [left, right, bottom].
Default bottom
minimizedChatRightStringX-coordinate from the right down corner of minimized chat. Indentation of right will be given priority over indentations left. Ignored if chat is static or if minimizedChatPosition is equals left or right.
Default 20px
minimizedChatLeftStringX-coordinate from the left down corner of minimized chat. Ignored if chat is static or if minimizedChatPosition is equals left or right.
Default null
minimizedChatBottomStringY-coordinate of closed chat. Ignored if chat is static.
Default 20px
Messages
messageFontSiseStringFont size of message's text. Only in px.
Default 12px
showUsersAvatarsBooleanShow users avatars.
Default true
avatarBorderRadiusStringRadius of user avatars.
Default 3px
showDateOfMessageBooleanShow date of message.
Default true
highlightRepliesBooleanReplies highlighting.
Default true
allowLinkToProfileBooleanShow users profile links.
Default true
showBorderBetweenMessagesBooleanShow border between messages.
Default true
Chat menu
menuItemsArraySet chat menu items. Pass array of objects: [ {url(string), title(string), iconUrl(string), isBlank(boolean)}, ... ].
Default null
Permissions
allowUploadMessagesBooleanAbility to update content. Receive new messages and scroll messages.
Default true
allowSendMessagesBooleanAbility to send messages. allowUploadMessages should be true.
Default true
allowResizeChatBooleanAbility to resize chat.
Default true
allowMinimizeChatBooleanAbility to minimize chat.
Default true
allowUploadFileBooleanAbility to upload files.
Default true
showParticipantCountBooleanShow participant counter.
Default true
showMinimizedParticipantCountBooleanShow participant counter for movable minimized chat.
Default true
allowFullScreenImageBooleanAllow to open pictures in full screen. Otherwise open it in a new tab.
Default true
showTitleNotificationBooleanShow new messages notifications in browser tab title.
Default false
disableImagesBooleanDo not convert links to images
Default false
Users
siteDomainStringChat domain. Should be passed with siteUserExternalId when site authentication used.
Default null
siteUserExternalIdStringYour site user id.
Default null
siteUserFullNameStringUser name. siteDomain and siteUserExternalId should be passed.
Default null
siteUserFullNameColorStringColor of user name. siteDomain and siteUserExternalId should be passed.
Default null
siteUserAvatarUrlStringUser avatar url. siteDomain and siteUserExternalId should be passed.
Default null
siteUserProfileUrlStringUser profile url. siteDomain and siteUserExternalId should be passed.
Default null
allowedLoginMethodsArrayArray of allowed authentication methods.
Default ['guest', 'vk', 'tg', 'google', 'fb']
customLoginLinkStringAdds an additional authorization method to the login menu.
Default null
signatureStringSpoofing protection. Calculated at server on the basis of the transmitted parameters as md5(siteDomain + siteUserExternalId + siteUserFullName + siteUserAvatarUrl + siteUserProfileUrl + siteUserFullNameColor + permissions + secretKey). You can find your secretKey in chat constructor just enable Spoofing protection.
Parameters siteDomain and secretKey are always necessary. Other can be ignored if you do not use them in the ChabroLoader. Example: https://codepen.io/ChatBro/pen/booKRx?editors=0010
More info
Default null
permissionsArrayAn array of allowed moderation methods. Used only in conjunction with the signature parameter. Possible values are: ban (the ability to ban users), delete (the ability to delete messages). Example: https://codepen.io/ChatBro/pen/booKRx?editors=0010
Default []
History
useStandardHistoryWidgetSettingsBooleanDefault history preset.
Default false
chatPaginatorUrlPrefixStringHistory url prefix. Example: https://www.chatbro.com/history/. Mandatory parameter for history widget.
hideMessagesOverflowBooleanAdjust chat height for content.
Default true
showChatOuterFrameBooleanDisplay outer widget border. Used only when hideMessagesOverflow = false.
Default true
batchIdStringCurrent history page number. Used for display of history and paginator.
Default null
Updated 2021-04-24

History indexing

There is specially customized chat widget with paginator for history.

Choose url for history widget. For example:  http://www.chatbro.com/43eM/history

Insert chat here with the history preset option (useStandardHistoryWidgetSettings = true).

You should pass this url as chat parameter chatPaginatorUrlPrefix It will be used in the paginator. Paginator will be available only, if live update disabled (allowUploadMessages = false).

When walking throw history pages, page number will be added to url. It should be passed as batchId parameter.

ChatbroLoader({ encodedChatId: '43eM', containerDivId: "someDivId", useStandardHistoryWidgetSettings: true, chatPaginatorUrlPrefix: 'http://www.chatbro.com/43eM/history' });

See the Pen History_en by ChatBro (@ChatBro) on CodePen.


Single Sign-On

The user, having gone the authentication procedure on your site, logs in to the chat. The chat will use the same nickname and avatar as on the site. A link to user profile will also be available. Example implementation.

Message filtering

To avoid unwanted messages, you can enable message filtering on the server side. You can do this in the chat constructor, in the "Administration" section. The filter function use JavaScript. Return statement use a Java object with static methods that return various actions (for example accept, change or decline message and other).

The simplest filter function looks like this:

function filter(lastMessages, newMessage, result) { return result.accept(); }

It just accept user's message without any checks.

Parameters
  • newMessage - object of Message
  • lastMessages - array of lastest 10 Message's objects
  • result - result class with static methods to return different actions
Return statements
  • Accept message

    result.acceptMessage();
    result.acceptMessage("{comment: 'some text'}");

    • comment (String) - info message for user.

  • Decline message

    result.declineMessage("{comment: 'some text'}");

    • comment (String) - warning message for user.

  • Change message

    result.changeMessage(messageObject);
    result.changeMessage(messageObject, "{comment: 'some text'}");

    • comment (String) - info message for user.
    • messageObject (Object) - message object

  • Ban user

    result.banUser("{banDurationMin: 15, reason: 'some reason', banType: 'IP', isShadow: false, comment: 'some text for user'}");

    • banDurationMin (Long) - diration of ban in minutes.
    • reason (String) - reason of ban.
    • isShadow (Boolean) - it's shadow ban or not. Default false.
    • comment (String) - warning message when user will be banned.
    • banType (String) - 2 options: IP - ban by ip; ID - ban by user id. Default IP.

  • Show info message

    result.showInfo("{message: 'some text'}");


  • Show warning message

    result.showWarning("{message: 'some text'}");

Object of Message
  • originalText - message text
  • attachments - attachments in the form of an array
    • fileAttachments
      • type = FILE
      • fileUrl
      • fileName
      • fileSize
    • photoAttachments
      • type = PHOTO
      • title
      • thumbnailPhotoUrl
      • originalPhotoUrl
    • videoAttachments
      • type = VIDEO
      • title
      • description
      • thumbnailPhotoUrl
      • playerUrl
      • thumbnailPhotoUrls
  • domain - реферер отправителя
  • url - полный адрес, откуда отправили сообщение
  • creatorId - id отправившего
  • creatorExternalId - внешний id отправившего
  • creatorFullName - имя отправившего
  • creatorAvatarUrl - аватар отправившего в виде урла
  • creatorProfileUrl - урл до профиля отправившего
  • creationDate - время отправки сообщения

Events

Please set events listeners after chat initialization on chatLoaded event. Event should be set on document.

Example:

document.addEventListener('chatLoaded', function() {
    document.addEventListener(...);
    document.addEventListener(...);
    document.addEventListener(...);
    ...
});
chatLoaded

When chat is initialized.

newMessage

Fires on new message. Grants access to the message and it's container.

Play message notification sound for not active tab:

document.addEventListener('chatLoaded', function(event) {
    event.chat.audioControl.loadSoundFile('http://www.soundjay.com/misc/sounds/handbag-lock-4.mp3');
    document.addEventListener('newMessage', function(event) {
        var chat = event.chat;
        if (!chat.isActiveTab()) {
            event.chat.audioControl.play();
        }
    });
});

See the Pen New message event by ChatBro (@ChatBro) on CodePen.

maximizeChat, minimizeChat

When chat window open/closed.


See the Pen maximize & minimize by ChatBro (@ChatBro) on CodePen.

chatInputClick

Fires on input click. Use this event to make chat read only for guests. Ask them to sign in on input click.


See the Pen chatInputClick by ChatBro (@ChatBro) on CodePen.

beforeSendMessage

Use this event to filter URLs or work with attachments. Fires before sending message with access to the Message object.

The Message object structire:

{
    text: '', - Text of the message
    attachments: [
        {
            type: 'photo/video', - attachment type
            thumbnailPhotoUrl: '', - image preview url
            originalPhotoUrl: '', - image url
            playerUrl: '' - Attachment url. Only when type = video
        }
        ...
    ],
    links: [
        {
            host: '', - url host
            protocol: '', - url protocol
            url: '' - original url
        }
        ...
    ]
}

Have two callbacks:

onSuccess(Message) - Will send the Message object.
onFail(text) - Will alert with the text message.


See the Pen beforeSendMessage_en by ChatBro (@ChatBro) on CodePen.

chatbroPtCountChanging

Event fired when changing the number of participants.

See the Pen Get current online by ChatBro (@ChatBro) on CodePen.

CMS

Plugins implement transparent authenctication for CMS users. Spoofing protection. History pages for search engines. Easy installation and configuration.

Incorrect signature

Signature is a unique string generated on the user's server based on the parameters passed to the ChatbroLoader function. The signature is compared on the server ChatBro, providing protection of the chat from substitution of users and not allowing copying to the other websites. If spam protection is enabled, the chat will only work if the signature is calculated correctly and the site's domain corresponds to the one transmitted.
More about spoofing 

How to fix?

We have made a separate page that will help you understand how to do everything correctly.