The following are the events that can be executed through the SDK library that allow different types of actions to be performed with the Chat Window. For example, opening and minimizing the chat window, initializing properties of the user that is interacting with the chat window, sending a message/query to the bot (so that it responds), among other actions.
Additionally, it is also possible to subscribe to a series of events to be triggered after the user interacts with the Chat Window. For example, clients can measure in their own data tool each time a user clicks on the start button.
Important: we recommend that this documentation be read and used by developers.
To use SDK events it is recommended to invoke the ready method of the $aivo object:
$aivo.ready(function() { ... }).
This will work as a callback and will fire, immediately after finishing the initial configurations of the window, the events that are inside the function passed by parameter.
Below is an example of what the callback would look like. And below, all the events and the actions performed by each one are detailed.
Example:
// include script without async attribute
<script type="text/javascript" src="https://cdn.agentbot.net/core/7c91324f0e1dcf0dcf4fd2dc7582bfaf.js" charset="UTF-8"></script>
<script type="text/javascript">
$aivo.ready(function() {
$aivo.user.set("name", "Steven Paul Jobs");
$aivo.user.set("device", "iPhone");
$aivo.chat.open();
$aivo.chat.addMessage("Welcome, how can I help you?")
});
</script>
Actions on the Chat window
+ Maximize window
Generates the maximization of the chat window.
Execution:
$aivo.chat.maximize();
+ Open chat window:
Opens the chat window and hides the start button.
Execution:
$aivo.chat.open();
+ Close the session and the chat window.
Minimizes the chat window and closes the session. Re-displays the start button.
Execution:
$aivo.chat.close();
+ Show or hide the close chat icon ( X )
Shows and hides the Close icon that is located in the upper right margin of the Header.
Execution:
$aivo.chat.showCloseIcon(true); (show icon)
$aivo.chat.showCloseIcon(false); (show icon)
Example from embed:
showCloseIcon(true) Shows the icon
http://embed.agenbot.net/[name]/[token]?show_close_icon=true
showCloseIcon(false) Hides the icon
http://embed.agenbot.net/[name]/[token]?show_close_icon=false
Note: When executing this event in embed, the close function will only be enabled once there is interaction with the bot and the configuration of that channel has the satisfaction survey active. Once sent to the survey, the "X" disappears and the functionality that each embed has adapted to close the conversation continues.
+ Event to send to the Satisfaction survey
The $aivo.chat.closeToSurvey() event allows sending the Satisfaction survey in cases where the survey is active and, in addition, there is an interaction with the bot.
Execution:
$aivo.chat.closeToSurvey()
+ Set title in Zendesk Header
The setHeaderZendesk event allows you to add a text in the header of the referral window to Zendesk. The content must be specified as a string when executing the event. The text will refer to the action of closing the derivation.
Execution:
$aivo.chat.setHeaderZendesk(“title”)
+ Set chat window aesthetics and functionality for Apps.
When executing this command, the chat window undergoes the following modifications:
The actions of maximizing, minimizing and closing the window are not displayed.
It is not possible to drag the window.
The window occupies 100% of the available width and height in case it is running on a mobile device.
Execution:
$aivo.chat.embed();
+ Send a message to the user (as if it was sent by the bot).
Add a message to the chat window, it is displayed as a message from the Bot.
Example:
$aivo.chat.addMessage("Hello customer, this is AgentBot");
+ Send a message to the bot (as if sent by the user).
Add a message to the chat window, it is displayed as a message sent by the user.
Example:
$aivo.chat.sendMessage("Hi, I need help");
+ Hide the Start Button
Hides the start button in case it is visible.
It is important to clarify that if the chat window is visible, this event does not perform any action. First the window should be minimized or closed (through the "close" or "minimize" events).
Execution:
$aivo.launcher.hide();
+ Hide the minimized bar in mobile
Allows you to hide the minimized bar in mobile
Execution:
show: $aivo.launcher.hideSticky(false)
hide: $aivo.launcher.hideSticky(true)
+ Show the Start Button
If the start button was previously hidden, through this event it is displayed again.
Execution:
$aivo.launcher.show().
+ Remove the Start Button
Removes the start button permanently. So to display again you have to load the Aivo script again.
Execution:
$aivo.launcher.remove();
User Properties
+ Define user properties
Through the event it is possible to define the properties of the user who is interacting with the chat window (name, email, etc.).
There are 2 ways to send the user parameters:
Old
$aivo.user.set('name','Pedro')
$aivo.user.set('last name', 'Perez')
New
$aivo.user.set({
'name', 'Pedro',
'surname': 'Perez'
})
+ Get user properties
We have 2 ways to get user parameters
Implementation:
$aivo.user.get(); // Return data from localstorage
$aivo.user.get((data) => console.log(data)) // Return data from localstorage + APIUser
+ Delete the user and create a new one
Through the event deletes the user (ending the session) and generates a new user. Deleting also all the user properties that have been configured.
Implementation:
$aivo.user.new();
+ Show or hide file attachment icon when referencing
Through the event, the icon of attaching files is shown and hidden when making a derivation. This event can be executed when starting the window.
Implementation:
Activate: $aivo.chat.entryMessage.showAttachButton()
Hide: $aivo.chat.entryMessage.hideAttachButton()
Shadow Root property of the DOM
Through this event we can enable or disable access to the HTML elements within the window. For the event implementation it must be done outside the $aivo.ready()
Example from Web channel:
$aivo.shadowRoot(true): Keeps window elements locked inside the DOM
$aivo.shadowRoot(false): Releases access to window elements within the DOM
1 <script>
2 let scriptAivo = document.createElement("script");
3 const token = '2fbb16f72fb124ecbf35452d54d9cc59'
4 scriptAivo.classList="script-aivo"
5 scriptAivo.type = "text/javascript";
6 scriptAivo.src = `https://cdn.agentbot.net/core/latest/core.js?Myjagsd4wLjY===`;
7 scriptAivo.onload = function() {
8 $aivo.run(token)
9 $aivo.shadowRoot(false)
10 }
11 setTimeout(() => {document.getElementsByTagName("head")[0].appendChild(scriptAivo)},500)
12 </script>
Example from embed:
ShadowRoot (closed) Keeps window elements locked inside the DOM: https://embed.agenbot.net/[name]/[token]?shadow-aivo=true
ShadowRoot (open) Releases access to the window elements within the DOM: https://embed.agenbot.net/[name]/[token]?shadow-aivo=false
After this implementation we can obtain elements from the DOM with the following instruction:
document.querySelector('#AgentAppContainer').shadowRoot.querySelectorAll([Selector])
Subscribe type events
What is a Subscribe event and what can it be used for?
Subscribe events are built-in JavaScript methods that take the selected event and allow it to be listened to each time its execution is generated. They receive a second argument to call each time the described event is triggered, this second argument consists of a callback type function which allows executing client actions and can receive parameters depending on each event.
These events can be used, for example, for clients to measure in their own data tool the interactions of their users with the Chat Window.
These events are detailed in the following article: Subscribe (SDK) type events