Getting started

Setup and usage

The JavaScript API supplies a collection of functions and events that underpin the majority of Support Board functionality. To start using the JavaScript API follow the tutorial below.

Usage

Make sure to load the chat by including the following script into the page where you want to use the APIs. Make sure the links are correct. If you're using the WordPress version this step is not required.

                                <script src="supportboard/js/min/jquery.min.js"></script>
                                <script src="supportboard/js/init.js"></script>
                            

Insert the code snippets, functions, and methods of this documentation into the function below.

                                (function ($) {
                                    $(document).on("SBInit", function () {
                                        // Insert your code here
                                    });
                                }(jQuery));
                            

Function parameters

Insert the function parameters in the same order of this documentation. Example: SBChat.sendMessage(user_id, message, attachments).

Debug

Check the browser console for errors and debug information.


Getting started

Objects

The JavaScript objects used by Support Board are listed below. In some cases, you will need to use these objects to use a function.


SBUser

Represents a user.


Usage

new SBUser(settings, extra)
  • settings is an array with the user details. Example: { first_name: "", last_name: "", profile_image: "", email: "", user_type: "" }
  • extra is an array with the additional user details. Example: { phone: "", city: "", language: "", country: "", birthday: "" }

Methods

id
Return the user ID.
type
Return the user type. Possible values: visitor, lead, user, agent, admin.
name
Return the full name of the user: first name and last name.
image
Return the profile image of the user.
get(key)
Return the user detail of the given key, if available, otherwise return an empty string. Example: get("email").
getExtra(key)
Return the additional user detail of the given key, if available, otherwise return an empty string. Example: get("phone").
set(key, value)
Update a user detail or add a new one. Example: set("phone", "(02) 123 456789").
setExtra(key, value)
Update an additional user detail or add a new one.
update(function(){})
Connect to the database and update the user details and the additional user details with fresh data from the database. Optionally run a function on complete. This method is asynchronous and requires the user ID to works.
getConversations( function(conversations){}, exclude_id)
Connect to the database and get the user conversations, each conversation includes an excerpt of the last message. Optionally run a function on complete. The parameter exclude_id can be any conversation ID and it will exclude the conversation with that ID from the returned value. This method is asynchronous and requires the user ID to works.
getConversationsCode( conversations)
Return the HTML code of the conversations list. Optionally accepts an array of SBConversation objects.
getFullConversation( conversation_id, function(conversation){})
Connect to the database and return a full conversation, including all messages. Optionally run a function on complete. This method is asynchronous and requires a conversation ID to works.
addConversation(conversation)
Add a new conversation to the user object, the parameter conversation must be a SBConversation object. This method doesn't update the database.
isConversationsEmpty()
Return true if the user has at least 1 conversation, otherwise, return false.
isExtraEmpty()
Return true if the additional user details have been already set, otherwise return false. This method returns true also if the additiona user details list is empty, but it's setted.
delete(function(){})
Delete the user from the database and all the linked conversations and messages, permanently. Optionally run a function on complete. This method is asynchronous and requires the user ID to works.

Variables

details
Array with the user details.
extra
Array with the additional user details.
conversations
Array with the user conversations. Each conversation contains only the last message.

SBMessage

Represents a message of a conversation.


Usage

new SBMessage(details)
  • details is an array with the message details. Example: { "id": "2319", "user_id": "377", "message": "Welcome to our support chat!", "creation_time": "2020-05-12 18:04:50", "attachments": "", "status_code": "0", "payload": "", "conversation_id": "1004", "first_name": "Virtual", "last_name": "Agent", "profile_image": "https://board.support/bot.svg", "user_type": "bot" }

Methods

id
Return the message ID.
attachments
Return the attachments array.
get(key)
Return the content of the given key, if available, otherwise return an empty string. Example: get("message").
set(key, value)
Update a message detail or add a new one. Example: set("message", "Hello!").
payload(key, value)
Set or get the payload. The payload is an associative array containing extra data. Example: {"rich-messages":{"123":{"type":"buttons","result":"Premium Plan"}}}, it contains the full Dialogflow response if the message is from the Dialogflow bot. If the value is set, the method adds or updates the key with the given value.
getCode()
Return the HTML code of the message, ready to be inserted in the chat DOM element. This method process attachments, Rich Messages, and text formatting.
render(message)
Render the message and format it by adding stylings like bold and italic, and by converting URLs to clickable links. Optionally accept a string and render it instead.

Variables

details
Array with the message details.

SBConversation

Represents a conversation.


Usage

new SBConversation(messages, details)
  • messages is an array of SBMessage objects.
  • details is optional and it's an array with the conversation details. Example: { conversation_status_code: "2", conversation_time: "2020-05-18 11:48:09", department: null, first_name: "Don", last_name: "John", id: "102", profile_image: "https://board.support/user.jpg", title: "", user_id: "897", user_type: "lead" }

Methods

id
Return the conversation ID.
get(key)
Return the content of the given key, if available, otherwise return an empty string. Example: get("conversation_status_code").
set(key, value)
Update a conversation detail or add a new one. Example: set("conversation_status_code", 2).
getMessage(ID)
Return the message with the given ID. Return false if the message is not found.
getLastMessage()
Return the last message of the conversation. Return false if there are no messages.
getLastUserMessage(index)
Return the last message of the conversation sent by the user, this method excludes the messages sent by the bot, the agents, or the admins. Optionally accepts an index from which start the research of the message, the research is in inverted order, from the last message to the first one. Return false if there are no messages.
updateMessage(ID, message)
Update the message with the give ID with a new message. The parameter message must be a SBMessage object.
addMessages(messages)
Add new messages to the conversation. The parameter messages must be a single SBMessage object or an array of SBMessage objects.
getCode()
Return the HTML code of the message.
deleteMessage(ID)
Remove the message with the given ID from the conversation object. This method doesn't update the database.
searchMessages(search, exact_match)
Search for the search string in all the messages of the conversation and return an array with the messages that match the search. Set the argument exact_match to true to return only the messages with exactly the same content of the search.
getAttachments()
Return an array containing all the attachments of the conversation. Each item is an array containing the following details: filename, link, file extension, message ID. Example: [["image.jpg", "https://board.support/image.jpg", "jpg", "5132"], ["file.txt", "https://board.support/file.txt", "txt", "5135"], ...].

Variables

details
Array with the conversation details.

Getting started

Variables

The variables in the list below are publicly accessible via JavaScript and are useful in many scenarios.


Variable Description
SBChat.initialized
true if the chat is initialized, otherwise false.
SBChat.conversation
The active conversation. The value is false if there isn't any active conversation.
SBChat.is_busy
true if the chat is in busy mode, otherwise false. When the chat is in busy mode no messages or attachments can be sent.
SBChat.chat_open
true if the chat is open, otherwise false.
SBChat.agent_id
The ID of the active agent in the active conversation. The value is -1 if there isn't any active agent.
SBChat.agent_online
true if the active agent is online, otherwise false.
SBChat.user_online
true if the user is online, otherwise false.
SBChat.email_sent
true if a notification email has been already sent, other false.
SBChat.timetable
true if the current time is within the office hours, otherwise false.
SBChat.dashboard
true if the dashboard is active and visible, otherwise false.

JAVASCRIPT API

Chat functions

Functions to manage chat, users, conversations, and messages.


SBChat.submit()

Fire the submit button click event of the chat editor, send a message with the contents inserted by the user (message and/or attachments), and clear the editor.


Information

  • Requirement. The chat must be initialized.

SBChat.sendMessage()

Add a new message to the active conversation.


Parameters

user_id
The user ID linked to the message. Use the function SBF.setting("bot-id") to get the ID of the bot. Default: -1 (active user ID).
message
The message text.
attachments
Array of attachments. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment.
onSuccess
Function to execute once the function is complete. Syntax: function(response) { ... }. The response is the same of the SBMessageSent event. Default: false.
payload
Associative array containing extra data. Example: { "event": "delete-mesage" }.

Information

  • Requirement. The chat must be initialized.
  • Requirement. The active user must be initialized.

SBChat.sendBotMessage()

Send a message to Dialogflow and add the Dialogflow response to the active conversation as a new message.


Parameters

message
The message text.
attachments
Array of attachments. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment. Dialogflow can read this array.

Information

  • Requirement. The Dialogflow App is required and Dialogflow must be active in the Settings area.
  • Requirement. The chat must be initialized.
  • Requirement. The active user must be initialized.

SBChat.sendEmail()

Send an email to the agents (or the active user if you're in the admin area). The email is sent only to the last agent of the conversation, if any, otherwise to all agents. The email template used by this function can be customized in the Settings > Notifications area.


Parameters

message
The message text.
attachments
Array of attachments. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment. Dialogflow can read this array.

Information

  • By default you can send only one email, to send another email you need first to set to false the variable SBChat.email_sent.

SBChat.pushNotification()

Send a Push notification to the last agent of the conversation, or all agents if no agents have replied yet.


Parameters

message
The message text.

Information

  • This function works only if the Push notifications are active in the settings area.
  • Currently, Push notifications are supported only on Mac, Windows and Android devices, iPhones, and iOS devices are not supported yet.
  • For more details click here.

SBChat.desktopNotification()

Send a Desktop notification(Web notification) to the user, or the logged-in agent if the notification is sent from the admin area.


Parameters

title
The title of the notification.
message
The message text.
icon
The icon of the notification.
conversation_id
The ID of the conversation to open when the user clicks the notification.

Information

  • Currently, Desktop notifications are supported only on Mac, Windows and Android devices, iPhones, and iOS devices are not supported yet.

SBChat.initChat()

Initialize the chat and display the chat button.


Information

  • Use this function in combination with the setting Manual initialization of the Settings > Chat area.
  • This method must not be inserted into the event $(document).on("SBInit", function () { ... });. Use instead $(document).on("SBReady", function () { ... });.

SBChat.open()

Open or close the chat window.


Information

  • Requirement. The chat must be initialized.

SBChat.openConversation()

Open a conversation and display it in the chat window.


Parameters

conversation_id
The ID of the conversation to open. Only the conversations of the active user can be opened. Use the function SBF.activeUser().conversations to get the conversations list.

Information

  • Requirement. The chat must be initialized.

SBChat.update()

Update the active conversation and check if there are new messages. This function is fired automatically every 1000ms.


Information

  • Requirement. A conversation must be active.
  • Requirement. The chat must be initialized.
  • Requirement. The active user must be initialized.

SBChat.populateConversations()

Populate the user conversations list of the dashboard with all the conversations of the user.


Parameters

onSuccess
Function to execute once the function is complete. Syntax: function(conversations) { ... }.

Information

  • Requirement. The chat must be initialized.
  • Requirement. The active user must be initialized.

SBChat.updateConversations()

Update the user conversations list of the dashboard and check if there are new conversations. This function is fired automatically every 10000ms.


Information

  • Requirement. The chat must be initialized.
  • Requirement. The active user must be initialized.

SBChat.newConversation()

Create a new conversation and optionally add the first message to it.


Parameters

status_code
The status code of the conversation. Default: 0. Status codes: live = 0, waiting answer from user = 1, waiting answer from agent = 2, archive = 3, trash = 4.
user_id
The ID of the user linked to the new conversation. Default: -1 (active user ID).
message
The message text.
attachments
Array of attachments. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment.
department
The ID of a department. You can get the IDs from Settings > Miscellaneous > Departments. Default: NULL.
agent_id
The ID of the agent assigned to the conversation. Default: NULL.
onSuccess
Function to execute once the function is complete. Syntax: function(conversation) { ... }. Default: false.

Information

  • Requirement. The chat must be initialized.
  • Requirement. The active user must be initialized.

SBChat.setConversation()

Set an existing conversation as active conversation.


Parameters

conversation
The conversation. It must be a SBConversation object. Use the function SBF.activeUser().conversations to get the conversations list.

Information

  • Requirement. The chat must be initialized.
  • Requirement. The active user must be initialized.

SBChat.startRealTime()

Start the real-time check of new messages for the active conversation every 1000ms.


SBChat.stopRealTime()

Stop the real-time check of new messages.


SBChat.busy()

Show or hide the loading icon and enable or disable the chat busy mode. When the chat is in busy mode no messages or attachments can be sent.


Parameters

value
Boolean. true or false.

Information

  • The loading icon appears only in the conversation area, not in the dashboard or in other panels.
  • Requirement. The chat must be initialized.
  • Requirement. The active user must be initialized.

SBChat.lastAgent()

Return the last agent of the active conversation.


Parameters

bot
Boolean. Set it to false to exclude the bot. Default: true.

Response

                                {
                                    "user_id": "123456",
                                    "full_name": "Don John",
                                    "profile_image": "https://board.support/agent.svg"
                                }
                            

Information

  • Requirement. The chat must be initialized.

SBChat.scrollBottom()

Scroll the chat to the bottom.


Parameters

top
Boolean. Set it to true to scroll on top. Default: false.

Information

  • Requirement. The chat must be initialized.

SBChat.showDashboard()

Display the dashboard.


Information

  • Requirement. The chat must be initialized.

SBChat.hideDashboard()

Hide the dashboard.


Information

  • Requirement. The chat must be initialized.

SBChat.updateNotifications()

Update the red notification counter of the chat button that alerts the user of new messages and new conversations.


Parameters

action
Insert add to increase the counter of 1, insert remove to decrease the counter of 1. Default: add.
conversation_id
The ID of the conversation linked to the update of the counter. Use the function SBF.activeUser().conversations to get the conversations list of the active user.

Information

  • Requirement. The chat must be initialized.

SBChat.setConversationStatus()

Update the status code of a conversation.


Parameters

status_code
The status code to assign to the conversation. Status codes: live = 0, waiting answer from user = 1, waiting answer from agent = 2, archive = 3, trash = 4.

Information

  • Requirement. The chat must be initialized.
  • Requirement. The active user must be initialized.

SBChat.typing()

Manage the typing ... label of the chat header.


Parameters

user_id
The ID of the active user (or the ID of the active agent if you're in the admin area). Use the function SBF.activeUser().id to get the ID of the active user (use the variable SB_ACTIVE_AGENT["id"] to get the ID of the active agent if you're in the admin area). Use the variable SBChat.agent_id to get the ID of the last agent of the conversation. Default: -1.
action

Possible values:

  • check - Check if the user with the given ID is typing and update the chat header.
  • set - Assign the typing status to the user with the given ID and update the chat header.
  • start - Display the typing status in the chat header.
  • stop - Hide the typing status from the chat header.

Information

  • The typing label is visible only when a conversation is open.
  • Requirement. The chat must be initialized.

SBChat.showArticles()

Display the articles area or one single article.


Parameters

id
The ID of an article to show. Use the function SBChat.getArticles() to get the articles list. Default: -1.

Information

  • Requirement. The chat must be initialized.

SBChat.getArticles()

Return the articles list or the content of one single article.


Parameters

id
The ID of an article to show. Use the function SBChat.getArticles() to get the articles list. Default: -1.
onSuccess
Function to execute once the function is complete. Syntax: function(response) { ... }. Default: false.

Response

                                [
                                    {
                                        "id": "6P2Oq",
                                        "title": "What's new with Dialogflow API V2?p",
                                        "content": "Dialogflow API V2 is the new iteration of our developer API ...",
                                        "link": "https://dialogflow.com/v2-faq"
                                    },
                                    {
                                        "title": "Which API version am I currently using?",
                                        "content": "The Dialogflow API version is configured separately for each ...",
                                        "link": "",
                                        "id": "IDkft"
                                    },
                                    ...
                                ]
                            
                                {
                                    "id": "6P2Oq",
                                    "title": "What's new with Dialogflow API V2?p",
                                    "content": "Dialogflow API V2 is the new iteration of our developer API. The new API integrates Google Cloud SpeDialogflow API V2 is the new iteration of our developer API. ",
                                    "link": "https://dialogflow.com/v2-faq"
                                }
                            

Information

  • Requirement. The chat must be initialized.
  • Each article of the list contains only an excerpt of the content.

SBChat.searchArticles()

Display the articles matching the search in the dashboard' articles box.


Parameters

search
String with the search terms. The search function supports the title and the content.

Information

  • Requirement. The chat must be initialized.
  • Requirement. The dashboard must be active.
  • Requirement. The articles be active.

SBChat.insertText()

Insert a string in the chat editor.


Parameters

text
The string to insert in the editor.

Information

  • Requirement. A conversation must be active and open.
  • Requirement. The chat must be initialized.

SBChat.privacy()

Display the privacy message and force the user to accept the terms before starting the chat.


Information

  • Requirement. The chat must be initialized.

Display a pop-up message or close it.


Parameters

close
Boolean. Set it to true to close the pop-up. Default: false.
content
Array with the pop-up content. Array syntax: { image: "", title: "", message: "" }. Default: the content inserted in the Settings > Chat > Popup message area.

Information

  • Requirement. The chat must be initialized.
  • Requirement. The chat must close.

SBChat.slackMessage()

Send a message to Slack.


Parameters

user_id
The ID of the active user (or the ID of the active agent if you're in the admin area). Use the function SBF.activeUser().id to get the ID of the active user (use the variable SB_ACTIVE_AGENT["id"] to get the ID of the active agent if you're in the admin area). Use the variable SBChat.agent_id to get the ID of the last agent of the conversation. Default: -1.
full_name
The name of the sender, it will appear in Slack on the left of the message. It should be an agent's name if the message is from an agent, otherwise the user's name.
profile_image
The profile image of the sender, it will appear in Slack on the left of the message. It should be an agent's profile image if the message is from an agent, otherwise the user's profile image. Supported formats: PNG and JPG.
message
The message text.
attachments
Array of attachments in JSON format. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment.

Information

  • Requirement. A conversation must be active.
  • Requirement. The chat must be initialized.

SBChat.deleteMessage()

Delete a message from the database and the active conversation if available.


Parameters

message_id
The ID of the message to delete. Use the function SBChat.conversation.messages to get the messages list of the active conversation.

Information

  • Only the messages of the conversations of the active user can be deleted.
  • Requirement. A conversation must be active.
  • Requirement. The chat must be initialized.

SBChat.registration()

Display the registration or the login area or check if the registration is required.


Parameters

check
Set it to true to check if the registration is required. Default: false.
type
Insert registration to display the registration form, insert login to display the login form.

Information

  • Requirement. The chat must be initialized.

SBChat.addUserAndLogin()

Register a new user as a visitor and login it automatically after the registration. Optionally execute a function on complete.

Parameters

onSuccess
Function to execute once the function is complete. Syntax: function(response) { ... }. Default: false.

Response

                                [
                                    {
                                        "id": "913",
                                        "profile_image": "https://board.support/user.svg",
                                        "first_name": "User",
                                        "last_name": "#29902",
                                        "email": null,
                                        "user_type": "visitor",
                                        "token": "9b25351047ee758aa97ee4868d130cc1ceb8decf"
                                    },
                                    "YXNkWGNSeTdtRTdDYVkxVG8wckN4YWF6V2s0Tk1mczBSVHdQbHBpOWdmejVUTTdOUUxEUENhdUVoYmROWn..."
                                ]
                            

The last value is the encrypted login data ready to be stored in the Web Storage of the user' browser. Use the function SBF.storage("login", response[1]); to store it.


Information

  • If a user is already logged-in a page reload is required to activate the new user.
  • Requirement. The chat must be initialized.

SBChat.getDepartmentCode()

Return an HTML code with the details of the given department or of all the departments. Department details: id, color, image, name.

Parameters

department_id
The ID of the department. If this parameter is not setted or null, the function return the code of all departments.
onSuccess
Function to execute once the function is complete. Syntax: function(response) { ... }.

Response

                                <div data-color="red"><img src="sales.jpg" /><div>Sales<div></div>
                            

Information

  • Requirement. The chat must be initialized.

JAVASCRIPT API

Utility functions

List of various functions that perform different tasks.


SBF.translate()

Translate a string to the active user language.


Parameters

string
The string to translate.

Information

  • Return the translated string if available, otherwise the original string.
  • This function works only for the front-end translations.
  • For more details about the active language check the translations docs.

SBF.activeUser()

Return the active user as a SBUser object, return false if the active user is not found.


Active user JSON representation

                                {
                                    "details": {
                                        "id": "914",
                                        "profile_image": "https://board.support/user.svg",
                                        "first_name": "User",
                                        "last_name": "#23262",
                                        "email": null,
                                        "user_type": "visitor",
                                        "token": "bc308e274473fb685a729abe8a4bf82d3c49cd2f"
                                    },
                                    "extra": {},
                                    "conversations": []
                                }
                            

Information

  • For the user' methods and more details see the SBUser documentation.

SBF.cors()

Execute an HTTP POST or GET request to a URL and return the response.


Parameters

method
Insert POST or GET. Default: GET.
url
Insert the full URL of the request.
onSuccess
Function to execute once the function is complete. Syntax: function(response) { ... }.

SBF.null()

Check if an existing variable is null or empty.


Parameters

variable
The variable to check.

Information

  • Return true if the variable is an empty string, null, 'null', undefined.

SBF.deactivateAll()

Hide all the pop-ups and the windows. This function is used mostly in the admin area.


SBF.getURL()

Search for a parameter in the URL and return its value.


Parameters

name
The parameter to search. Return false if the parameter is not found.

SBF.restoreJson()

Convert a JSON encoded string into a normal text.


Parameters

value
The string to convert.

SBF.stringToSlug()

Convert a string to a slug by removing all special chars, by replacing all spaces with the char -, and by making the string lowercase.


Parameters

value
The string to convert.

Information

  • Use the function slugToString(slug) to convert back a slug to a string.

SBF.random()

Return a random alphanumeric string.


SBF.isAgent()

Check if a user type is an agent. Return true only if the user type is agent, admin, or bot.


Parameters

user_type
The user type string to check.

SBF.beautifyTime()

Convert a date to the local format and perform other optimizations to make the date more friendly.


Parameters

date
Date and time in the following format: YYYY-MM-DD HH:MM:SS. Ex. 2020-05-13 13:35:59. You can remove the time and leave only the date. The dates stored in the database are in UTC+0.
extended
Set it to true to include minutes and seconds. Default: false.

SBF.dateDB()

Convert a date format to the date format of the database and set the UTC to +0.


Parameters

date
Date and time in the following format: YYYY-MM-DD HH:MM:SS. Ex. 2020-05-13 13:35:59. You can remove the time and leave only the date. Insert now to get the current date and time. The dates stored in the database are in UTC+0.

SBF.error()

Trigger the custom JavaScript error of Support Board.


Parameters

message
String with the error message or a Error object.

SBF.errorValidation()

Check if a response from an AJAX call is a validation error.


Parameters

response
The response from the AJAX call.

SBF.login()

Login a user or an agent. The login can be completed in two ways: via email and password, or via user ID and token.


Parameters

email
The email of the user to login. If this attribute is set you need to set also the password. Default: empty string.
password
The password of the user to login. If this attribute is set you need to set also the email. Default: empty string.
user_id
The ID of the user to login. If this attribute is set you need to set also the token. Default: empty string.
token
The token of the user to login. If this attribute is set you need to set also the user ID. You can get the token from the Users area by opening the profile box of a user, only if you're an admin. Default: empty string.
onSuccess
Function to execute once the function is complete. Syntax: function(response) { ... }. Default: false.

Response

                                [
                                    {
                                        "id": "913",
                                        "profile_image": "https://board.support/user.svg",
                                        "first_name": "Don",
                                        "last_name": "John",
                                        "email": "support@schiocco.com",
                                        "user_type": "user",
                                        "token": "9b25351047ee758aa97ee4868d130cc1ceb8decf"
                                    },
                                    "YXNkWGNSeTdtRTdDYVkxVG8wckN4YWF6V2s0Tk1mczBSVHdQbHBpOWdmejVUTTdOUUxEUENhdUVoYmROWn..."
                                ]
                            

Return false if login is unsuccessful.


SBF.logout()

Logout the logged-in user and reload the page.


SBF.reset()

Logout the logged-in user, remove all Support Board stored data, and reload the page.


SBF.dialog()

Show a confirmation dialog window with Cancel and Confirm buttons and execute the given function only if the user clicks Confirm.


Parameters

text
The message displayed in the dialog window.
type
Insert alert, info, or map.
onSuccess
Function to execute once the user clicks Confirm. Syntax: function() { ... }.

Information

  • Requirement. This function is available only in the admin area.

Display the given content in a lightbox.


Parameters

content
The content to display. It can be any HTML content, to display an image use the code <img src="image.jpg" >.

SBF.storage()

Manage the local storage of Support Board. The local storage is a technology that saves any data in the browser, permanently.


Parameters

key
The ID of the value to set or retrieve.
value
The value to save. If not set the function return the value of the given key.

SBF.storageTime()

Save a key and the current date and time in the local storage to check in the future if it's within the given number of hours or if it's expired.


Parameters

key
The key to save or check.
hours
The number of hours to compare to the saved date and time.

Response

If the hours attribute is set, return true if the sum of saved date and time and the given hours is less than the current date and time, otherwise, return false. Example: if the saved time is 5:00 pm, and you insert 3, the function will return true only if the current time is 8:01 pm or more. true


SBF.setting()

Return the value of a setting.


Parameters

value

Available settings

Some of the available settings and the values are in the list below.

                                {
                                    "registration-required": "",
                                    "registration-timetable": false,
                                    "visitors-registration": true,
                                    "privacy": false,
                                    "popup": false,
                                    "welcome": false,
                                    "welcome-trigger": "open",
                                    "welcome-delay": 0,
                                    "follow": true,
                                    "chat-manual-init": false,
                                    "chat-login-init": false,
                                    "chat-sound": "n",
                                    "header-name": true,
                                    "desktop-notifications": "all",
                                    "flash-notifications": "all",
                                    "bot-id": "377",
                                    "bot-name": "Digital Assistant",
                                    "bot-image": "profile.jpg",
                                    "bot-delay": 0,
                                    "bot-office-hours": false,
                                    "bot-unknow-notify": false,
                                    "dialogflow-active": true,
                                    "slack-active": true,
                                    "rich-messages": [
                                        "email",
                                        "registration",
                                        "login",
                                        "timetable",
                                        "articles",
                                        "immagine",
                                        "video"
                                    ],
                                    "display-users-thumb": true,
                                    "hide-agents-thumb": true,
                                    "notify-user-email": true,
                                    "notify-agent-email": false,
                                    "translations": false,
                                    "auto-open": false,
                                    "office-hours": true,
                                    "disable-office-hours": false,
                                    "timetable": false,
                                    "articles": true,
                                    "articles-title": "",
                                    "init-dashboard": true,
                                    "wp": false,
                                    "wp-users-system": "sb",
                                    "wp-show-ids": [],
                                    "queue": false,
                                    "queue-message": "",
                                    "queue-message-success": "Let's start chat!",
                                    "queue-response-time": "",
                                    ...
                                }
                            

SBF.shortcode()

Convert a shortcode into an array containing the shortcode name and the shortcode settings.


Parameters

shortcode
The shortcode string. Example: [rating title="Rate your conversation" message="Tell us your experience." success="Thank you!"].

Response

                                [
                                    "rating",
                                    {
                                        "title": "Rate your conversation",
                                        "message": "Tell us your experience.",
                                        "success": "Thank you!"
                                    }
                                ]
                            

SBApps.dialogflowActive()

Check if Dialogflow is active or deactivate it.


Parameters

active
Set it to false to disable Dialogflow and stop the bot.

Response

Return true if the Dialogflow bot is active, otherwise, return false.


SBF.getLocationTimeString()

Return a string containing the location and current local time of the given timezone.


Parameters

details
Array with the location details. Example: { "timezone" : "", "country" : "", "city" : "" }. This function accepts the extra method of any SBUser object. Example: SBF.getLocationTimeString(activeUser().extra, function(){}).
onSuccess
Function to execute once the function is complete. Syntax: function(response) { ... }.

Response

05:15 AM in London, United Kingdom


JAVASCRIPT API

Tickets functions

List of functions of the Tickets App.


SBTickets.showPanel()

Display a panel or the conversation area.


Parameters

name
The name of the panel to show. Available names: new-ticket, privacy, articles, edit-profile, login, registration. Leave it empty to display the main conversation area.
title
The title to display as the panel name.

SBTickets.showSidePanels()

Display or hide the side panels.


Parameters

show
Set it to false to hide the panels.

SBTickets.setAgent()

Get the agent details and populate the agent profile area of the right panel.


Parameters

agent_id
The ID of the agent.

SBTickets.activateConversation()

Activate and display a conversation.


Parameters

conversation
The conversation to activate as a SBConversation object.

SBTickets.selectConversation()

Set the style of a conversation of the left panel as the active conversation.


Parameters

conversation_id
The ID of the conversation.

SBTickets.getActiveConversation()

Return the HTML DOM object of the active conversation.


Parameters

type
Set it to ID to get only the ID of the conversation.

JAVASCRIPT API

Events

Events lets you intercept Support Board actions in real-time and execute a custom JavaScript code when an action is triggered.

Usage

Use the code below and replace EVENT-NAME with the event name. The response represents the returned value if there is only one attribute, otherwise, it's an array of values. JQuery is required.

                                $(document).on("EVENT-NAME", function (e, response) {
                                    // Insert your code here
                                });
                            

Example:

                                $(document).on("SBMessageSent", function (e, response) {
                                    console.log(response["user_id"]);
                                    console.log(response["conversation_id"]);
                                    console.log(response["message"]);
                                });
                            

SBReady

Event fired on page load after the chat' script main.js has been loaded. This event fired also in the admin area.


SBInit

Event fired on page load when the chat has completed the initialization.


SBTicketsInit

Event fired on page load when the tickets area has completed the initialization. This event is available only when the Tickets App is active.


SBLogout

Event fired when the active user logout.


SBError

Event fired when a Support Board error occurs.


Response

message
The error message.
function_name
The function name that has generated the error.

SBDoubleLoginError

Event fired on chat initialization if an agent or an admin is already logged-in.


SBUserDeleted

Event fired when a user is deleted.


Response

The ID of the user that has been deleted.

SBMessageSent

Event fired when a new message has been sent.


Response

user_id
The ID of the user that sent the message.
conversation_id
The ID of the conversation linked to the message.
conversation_status
The status code of the conversation linked to the message. Status codes: live = 0, waiting answer from user = 1, waiting answer from agent = 2, archive = 3, trash = 4.
message_id
The ID of the message.
message
The text of the message.
attachments
The attachments of the message.

SBBotMessage

Event fired when the Dialogflow bot reply to a message.


Response

response
The response array in JSON format from Dialogflow.
message
The input message of the user.

SBSlackMessageSent

Event fired when a message is sent to Slack.


Response

message
The text of the message.
conversation_id
The ID of the conversation linked to the message.

SBEmailSent

Event fired when a notification email is sent to a user or an agent.


Response

recipent_id
The ID of the user that will receive the email.
message
The message of the email.
attachments
The attachments of the email.

SBNotificationsUpdate

Event fired when the red notification counter of the chat button that alerts the user of new messages and conversations is updated.


Response

action
The action value can be add if the counter is increased by 1, or remove it the counter is decreased by 1.
conversation_id
The action value can be add if the counter is increased by 1, or remove it the counter is decreased by 1.

SBConversationOpen

Event fired when a conversation is fully loaded and it's opened in the chat.


Response

response
The conversation as a SBConversation object.

SBNewMessagesReceived

Event fired when there are new messages in the active conversation.


Response

The list of the new messages. Each message is a SBMessage object.
response
The single message as a SBMessage or an array of SBMessage objects.

SBMessageDeleted

Event fired when a message is deleted.


Response

The ID of the message that has been deleted.

SBNewConversationReceived

Event fired when a new conversation is received.


Response

The new conversation as a SBConversation object.

SBNewConversationCreated

Event fired when a new conversation is created.


Response

The new conversation as a SBConversation object.

SBActiveConversationChanged

Event fired when the active conversation is changed.


Response

The new active conversation as a SBConversation object.

SBActiveConversationStatusUpdated

Event fired when the active conversation status code is updated.


Response

conversation_id
The ID of the conversation.
status_code
The new status code of the conversation. Status codes: live = 0, waiting answer from user = 1, waiting answer from agent = 2, archive = 3, trash = 4.

SBChatOpen

Event fired when the chat is opened.


SBChatClose

Event fired when the chat is closed.


SBQueueUpdate

Event fired when the queue is started and each time the queue is updated.


Response

The position of the user in the queue. If the position is 0 the queue is ended and the user can start the chat.

SBBusy

Event fired when the busy status of the chat changes. The chat is busy if it's operating, like sending a message. When the chat is busy some functions can not be fired, like sending a new message.


Response

true if the chat is busy, otherwise false.


SBDashboard

Event fired when the dashboard is displayed.


SBDashboardClosed

Event fired when the dashboard is closed and a conversation is displayed instead.


SBTyping

Event fired when a user or an agent is typing in the editor.


Response

true if the user or agent is typing, otherwise false.


SBArticles

Event fired when the articles panel is displayed or when a single article is opened.


Response

id
The ID of the article. This value is -1 if the articles panel is displayed.
articles
It can be the array with the single article details or the array with the list of all the articles.

SBPrivacy

Event fired on chat initialization if the privacy form is displayed.


SBPopup

Event fired when a pop-up message is displayed.


Response

The array with the contents of the pop-up: { image: "", title: "", message: "" }.


SBFollowUp

Event fired when the follow-up message is sent.


SBWelcomeMessage

Event fired when the welcome message is sent.


SBLoginForm

Event fired when the user login successfully from the login form of the chat. This event is fired only if the login is successful.


Response

The user as a SBUser object.

SBRegistrationForm

Event fired when the user registers successfully from the registration form of the chat. This event is fired only if the registration is successful. This event is fired also if the registration is updated via the Rich Message form.


Response

user
Array with the user details.
extra
Array with the additional user details.

SBRichMessageSubmit

Event fired when the response from a Rich Message is received.


Response

result
The response of the Rich Message.
data
The Rich Message details and the data sent by the user.

SBAttachments

Event fired when the user attaches a file.


SBNewEmailAddress

Event fired when a user register his email via the follow-up message or registration form.


Response

name
The full name of the user.
email
The email of the user.

SBPanelActive

Event fired when a panel of the Tickets area is opened. This event is available only when the Tickets App is active.


Response

name
The name of the active panel. Values: new-ticket, privacy, articles, edit-profile, login, registration. If the value is empty the main conversation area is active.
email
The email of the user.

MISCELLANEOUS

AJAX functions

List of AJAX functions. The AJAX functions are similar to the WEB API, they use the same function name, the same parameters, and return the same responses. Use the function below to start an AJAX call:

                                SBF.ajax({
                                    function: 'FUNCTION-NAME',
                                    parameter: value,
                                    parameter: value,
                                    ...
                                }, (response) => {

                                   // Insert your code here

                                });
                            

Replace FUNCTION-NAME with the name of one of the functions below. Replace the list of parameter: value with the parameters of the function.

Parameters and responses are the same as the WEB API. The response is in JSON format.

Warning! Do not include the token in the parameters. The token must be kept always secret.

Functions


Function name Requirements Parameters and response
saved-replies
Saved replies
get-settings
  • The chat must be initialized.
  • Admin function. The active user must be an admin.
Get settings
add-user
  • The chat must be initialized.
  • Admin function. The active user must be an admin.
Add user
add-user-and-login
Add user
get-user
  • The chat must be initialized.
  • If the active user is a user the function works only with the active user ID. If the active user is an agent or an admin the function works for any user.
Get user
get-users
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
Get users
get-new-users
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
Get new users
get-user-extra
  • The chat must be initialized.
Get user extra
get-online-users
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
Get online users
search-users
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
Search users
delete-user
  • The chat must be initialized.
  • Admin function. The active user must be an admin.
Delete user
delete-users
  • The chat must be initialized.
  • Admin function. The active user must be an admin.
Delete users
update-user
  • The chat must be initialized.
  • If the active user is a user the function works only for the active user. If the active user is an agent or an admin the function works for any user.
Update user
update-user-to-lead
  • The chat must be initialized.
Update user to lead
count-users
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
Count users
get-conversations
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
  • Include the argument routing with value true if the queue or routing is active in Settings > Miscellaneous. Include it as the last argument. Default: false.
Get conversations
get-new-conversations
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
  • Include the argument queue with value true if the queue or routing is active in Settings > Miscellaneous. Include it as the last argument. Default: false.
Get new conversations
get-conversation
  • The chat must be initialized.
  • If the active user is a user the function works only for the active user conversations. If the active user is an agent or an admin the function works for the conversations of any user.
Get conversation
get-user-conversations
  • The chat must be initialized.
  • If the active user is a user the function works only for the active user. If the active user is an agent or an admin the function works for any user.
Get user conversations
get-new-user-conversations
  • The chat must be initialized.
  • If the active user is a user the function works only for the active user. If the active user is an agent or an admin the function works for any user.
Get new user conversations
search-conversations
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
  • Include the argument routing with value true if the queue or routing is active in Settings > Miscellaneous. Include it as the last argument. Default: false.
Search conversations
search-user-conversations
  • The chat must be initialized.
  • If the active user is a user the function works only for the active user. If the active user is an agent or an admin the function works for any user.
  • The argument user_id is not required. Default: active user ID.
Search user conversations
new-conversation
  • The chat must be initialized.
  • If the active user is a user the function works only for the active user. If the active user is an agent or an admin the function works for any user.
new-conversation
update-conversation-status
  • The chat must be initialized.
Update conversation status
update-conversation-department
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
Update department
get-new-messages
  • The chat must be initialized.
  • If the active user is a user the function works only for the active user. If the active user is an agent or an admin the function works for any user.
Get new messages
send-message
  • The chat must be initialized.
  • If the active user is a user the function works only for the active user. If the active user is an agent or an admin the function works for any user.
Send message
send-bot-message
  • The chat must be initialized.
  • The function works only for the active user.
Send bot message
send-email
  • The chat must be initialized.
  • If the active user is a user the email can be sent only to agents or admins. If the active user is an agent or an admin the email can be sent to any user.
Send email
send-slack-message
  • The chat must be initialized.
  • If the active user is a user the function works only for the active user. If the active user is an agent or an admin the function works for any user.
Send Slack message
update-message
  • The chat must be initialized.
  • If the active user is a user the function works only for the active user. If the active user is an agent or an admin the function works for any user.
Update message
delete-message
  • The chat must be initialized.
  • If the active user is a user the function works only for the active user. If the active user is an agent or an admin the function works for any user.
Delete message
slack-users
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
Slack users
archive-slack-channels
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
Archive Slack channels
current-url
Current URL
set-rating
  • The chat must be initialized.
  • If the active user is a user the function works only for the conversations of the active user. If the active user is an agent or an admin the function works for the conversations of any user.
Set rating
get-rating
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
Get rating
get-articles
Get articles
save-articles
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
Save articles
search-articles
Search articles
get-versions
Get versions
update
  • The chat must be initialized.
  • Admin function. The active user must be an agent or an admin.
Update
app-get-key
  • The chat must be initialized.
  • Admin function. The active user must be an admin.
App get key
app-activation
  • The chat must be initialized.
  • Admin function. The active user must be an admin.
App activation
csv-users
  • The chat must be initialized.
  • Admin function. The active user must be an admin or an agent.
Csv users
csv-conversations
  • The chat must be initialized.
  • Admin function. The active user must be an admin or an agent.
Csv conversations
dialogflow-intent
  • The chat must be initialized.
  • Admin function. The active user must be an admin or an agent.
Dialogflow intent
is-agent-typing
  • The chat must be initialized.
  • Admin function. The active user must be an admin or an agent.
Is agent typing

More AJAX functions

The functions below are available only via AJAX.


login

Login a user or an agent. A user can logins in two ways: via email and password, or via user ID and token.


Parameters

function
Insert login
email
The email of the user to login. If this attribute is set you need to set also the password. Default: empty string.
password
The password of the user to login. If this attribute is set you need to set also the email. Default: empty string.
user_id
The ID of the user to login. If this attribute is set you need to set also the token. Default: empty string.
token
The token of the user to login. If this attribute is set you need to set also the user ID. You can get the token from the Users area by opening the profile box of a user. Default: empty string.

Response

                                [
                                    {
                                        "id": "913",
                                        "profile_image": "https://board.support/user.svg",
                                        "first_name": "User",
                                        "last_name": "#29902",
                                        "email": null,
                                        "user_type": "visitor",
                                        "token": "9b25351047ee758aa97ee4868d130cc1ceb8decf"
                                    },
                                    "YXNkWGNSeTdtRTdDYVkxVG8wckN4YWF6V2s0Tk1mczBSVHdQbHBpOWdmejVUTTdOUUxEUENhdUVoYmROWn..."
                                ]
                            

The last value is the encrypted login data ready to be stored in the Web Storage of the user' browser. Use the function SBF.storage("login", response[1]); to store it. Return false if login is unsuccessful.


is-typing

Check if a user or an agent is typing a message in a conversation.


Parameters

function
Insert is-typing
user_id
The ID of the user, or the agent, to check.
conversation_id
The ID of conversation to check.

Response

Return true if the user is typing, otherwise, return false.


set-typing

Assign the typing status to a user or an agent relative to a conversation.


Parameters

function
Insert set-typing
user_id
The ID of the user, or the agent.
conversation_id
The ID of the conversation.

Response

true

logout

Logout the logged-in user.


Response

true

Use the function SBF.storage("login", ""); to clear the browser' user data and complete the logout.


update-login

Update the user details of the logged-in user. This function update all the user details, if a detail is not set it will be deleted from the database.


Parameters

function
Insert update-login.
profile_image
The profile image URL of the user. Default: empty string.
first_name
The first name of the user. Default: empty string.
last_name
The last name of the user. Default: empty string.
email
The email of the user. Default: empty string.
department
Update the department of the user. This setting is used in the admin area. Default: empty string.

Response

YXNkWGNSeTdtRTdDYVkxVG8wckN4YWF6V2s0Tk1mczBSVHdQbHBpOWdmejVUTTdOUUxEUENhdUVoYmROWn...

Use the function SBF.storage("login", response); to update the browser' user data and complete the update.


close-message

Send the close message to a conversation. You can set the close message in the Settings > Chat area.


Requirements

  • This is an admin function and it works only if the active user is an agent.

Parameters

function
Insert close-message.
bot_id
The ID of the bot. Use the function SBF.setting("bot-id") to get the ID of the bot. If you're in the admin area use instead SB_ADMIN_SETTINGS['bot-id'].
conversation_id
The ID of the conversation to which send the message.

Response

                                {
                                    "success": true,
                                    "response": {
                                        "status": "success",
                                        "message-id": 123456,
                                        "queue": false
                                    }
                                }
                            

update-user-and-message

Update the user details of a user and the content of a message.


Requirements

  • The chat must be initialized.
  • If the active user is a user only the active user can be updated and only the messages linked to the conversations of the user can be updated. If the active user is an agent or an admin the function works for any user and any message.

Parameters

function
Insert update-user-and-message.
user_id
The ID of the user to update.
settings
Array with the user details. Array syntax and values: { first_name: [""], last_name: [""], profile_image: [""], email: [""], user_type: [""] }
settings_extra
Array with additional user details in JSON format.
Array syntax:
{ "ID": ["value", "Name"], "ID": ["value", "Name"], ...}
message_id
The ID of the message to update.
message
The message text.
payload
Associative array containing extra data. Example: {"rich-messages":{"123":{"type":"buttons","result":"Premium Plan"}}}.

Response

true

clean-data

This function performs the following tasks: Delete visitors older than 24h. Delete messages in trash older than 30 days. Archive messages with an agent reply as last message older than 24h.


Requirements

  • This is an admin function and it works only if the active user is an agent or an admin.

Parameters

function
Insert clean-data.

Response

true

get-translations

Return the translations of the back-end and the frond-end, for all the available languages.


Response

                                {
                                    "ar": {
                                        "name": "Arabic",
                                        "front": {
                                            "Activities": "أنشطة",
                                            "All": "الكل",
                                            "All articles": "جميع المقالات",
                                            "All fields are required.": "جميع الحقول مطلوبة",
                                            ...
                                        },
                                        "admin": {
                                            "A conversation was started by": "",
                                            "Activate": "",
                                            "Activation complete! Page reload in progress...": "",
                                            "Add a saved reply": "",
                                            ...
                                        }
                                    },
                                    "da": {
                                        "name": "Danish",
                                        "front": {
                                            "Activities": "Aktiviteter",
                                            "All": "Alle",
                                            "All articles": "Alle artikler",
                                            "All fields are required.": "Alle felter skal udfyldes.",
                                            ...
                                        },
                                        "admin": {
                                            "A conversation was started by": "",
                                            "Activate": "",
                                            "Activation complete! Page reload in progress...": "",
                                            "Add a saved reply": "",
                                            ...
                                        }
                                    },
                                    ...
                                }
                            

save-translations

Save the translations and overwrite the translations files. Warning! If the given translations array is corrupted you could corrupt the translations files. Make a backup of the translations folder ( \resources\languages\ first. Each time a translation is saved a backup is created automatically in the uploads folder.


Requirements

  • This is an admin function and it works only if the active user is an agent or an admin.

Parameters

translations
The translations array with all the translations. Use the method get-translations to get the array.

Response

true

get-agent

Return the details of an agent, admin, or bot.


Parameters

agent_id
The ID of the agent.

Response

                                {
                                    "id": "2",
                                    "first_name": "Don",
                                    "last_name": "John",
                                    "department": null,
                                    "flag": "gb.png",
                                    "country_code": "GB",
                                    "details": [
                                        {
                                            "slug": "city",
                                            "name": "City",
                                            "value": "London"
                                        },
                                        {
                                            "slug": "country",
                                            "name": "Country",
                                            "value": "United Kingdom"
                                        },
                                        {
                                            "slug": "sport",
                                            "name": "Sport",
                                            "value": "email@example.com"
                                        },
                                        {
                                            "slug": "timezone",
                                            "name": "Timezone",
                                            "value": "Europe/London"
                                        }
                                        ...
                                    ]
                                }
                            

delete-leads

Delete all leads, including all the linked conversations and messages.


Requirements

  • This is an admin function and it works only if the active user is an admin.

Response

                                true