Web messenger Introduction 

Hotline now lets you embed a widget in any site - the Web Messenger. The Web Messenger lets you engage with and manage queries from your website visitors - both anonymous and logged in users. It will appear as a widget on the bottom right corner of your web page. Every message that comes in from the Web Messenger will be treated as a separate conversation in the Hotline inbox. 


For detailed instructions on installation and set up of the Hotline Web Messenger, see here


WEB MESSENGER SETUP: 

  • Go to Settings from your Hotline account and choose SDK Integrations 
  • Click the Generate button 
  • An app token will be generated. 
  • Copy the App Token to call the init method as given below.

Call the init method:

  • Go to Settings 
  • Choose Web Messenger

 

 

 

  • You will be directed to the Web Messenger settings page under the Getting Started tab that looks like the image below
  • To chat with your website visitors, you will have to embed the widget on your website  


  • Copy the JavaScript code snippet before the </body> tag on every page to initialize the Web Messenger widget on your website


Installing the Hotline Web Messenger is a quick process that involves copying and pasting the code snippet to your web app or website. Embedding the Web Messenger lets you speak to and manage queries posed by both logged-out and logged-in users who visit your website.  


HOTLINE WEB MESSENGER FOR LOGGED OUT / ANONYMOUS USERS:

 

To embed the widget on your website, copy the code snippet from the Hotline Settings page as seen in the above image and paste the JavaScript code snippet before the </body> tag on every page to initialize the Web Messenger on your website



Hotline Web Messenger for logged in users: 


To embed the widget on your website, copy the code snippet from Hotline Settings page and paste the JavaScript code snippet before the </body> tag on every page to initialize the Web Messenger on your website


Additionally you can store an "externaIId" with Hotline. This externalId is unique to your system. It can be a user's handle or the user's phone number or email. This will be used to restore user conversations securely if they login from a different computer or browser.


Note: The example user data has to be replaced with real data that helps in getting actual user information on all of your web pages. 


You will now be able to see the Hotline Web Messenger widget on all pages of your website 


RESTORING A USER


If you give an externalId which is a unique identifier in your database, all conversations can be retrieved from all browsers and devices. For example, a user may have visited your site from a work device and held a couple of conversations. When he / she logs in from a different device, the user will be identified and previous conversations will be restored using the restoreId. 


To get the restoreId: 

  • Subscribe to user create by adding a listener to the event and store the restoreId in your database for restoring conversation.


<script src="WEB_CHAT_URL/js/widget.js"></script>
<script>
window.HotlineWidget.on("user:created", function(resp) {
  var status = resp 
  resp.status, data = resp 
  resp.data;
  if (status === 200) {
    if (data.restoreId) {
      // Update restoreId in your database
    }
  }
});

window.HotlineWidget.init({
    token: "WEB_CHAT_TOKEN",
    host: "WEB_CHAT_URL",
    externalId: "john.doe1987",      // user's id unique to your system
    name: "John Doe",                   // user's name
    email: "john.doe@gmail.com", // user's email address
    phone: "8668323090",             // phone number without country code
    phoneCountryCode: "+1"        // phone's country code
});
</script>



To restore the user:

  • The init function should be provided with the externalId and restoreId


<script src="WEB_CHAT_URL/js/widget.js"></script>
<script>
window.HotlineWidget.init({
    token: "WEB_CHAT_TOKEN",
    host: "WEB_CHAT_URL",
    externalId: "john.doe1987",      // user's id unique to your system
    restoreId: "RESTORE_ID",        //  restore id obtained
});
</script>


Note: Restoring a user on mobile is not possible because it is device specific. 


CUSTOMIZING WEB WIDGET CHANNELS


Tags for channels help customize widget channels according to levels and types of customers. There will arise various scenarios in which you will need to show different channels to different users or a subset of channels to a subset of users.


For example: For your paid customers you might want to add an additional "VIP Support" Channel. Or different channels to your users in Europe versus your users in the USA. You can add tags to channels and you can then use these tags to decide which channels to show to whom. 


Set Tags in widget init


If the tags are set when the init is set, relevant channels will appear when the widget loads. 


<script src="WEB_CHAT_URL/js/widget.js"></script>
<script>
window.HotlineWidget.init({
    token: "WEB_CHAT_TOKEN",
    host: "WEB_CHAT_URL",
    tags: ["public", "paid"],
    externalId: <externalId>
});
</script>


Set Tags during page transition: 


The tags can also be set later for specific web pages using Set Tags (only the latest selection will be updated for the channel list).  


For example, if a user is on the 'Payments' page, these tags will show only payment related channels on the Web Messenger. If he's switching to the 'Deliveries' page, Set Tags help show channels relating to deliveries during transition. Once Set Tags are called, the channel list will immediately be updated.


<script>
window.HotlineWidget.setTags(tags);      // For ex: ["public", "paid"]
</script>


Hotline Widget Events


1. widget:opened - Triggers when the widget opens
2. widget:closed - Triggers when the widget close
3. widget:loaded - Triggers when the widget loads
4. user:created - Triggers when the widget loads
 


Response


PROPERTIES TYPE DESCRIPTION
success Boolean TRUE - Success (200), FALSE - Error (Not 200)
status Var 1. 200 - Success
2. 400 - Backend Error
3. 401 - Init not called
4. 403 - ExternalId already used. Use clear() user method
5. 404 - Init not called / Restore ID is invalid
data Object 1. undefined - With 200 in status, user not created yet
- Without 200 in status, error
2. { restoreId: <value> } Use to synchronise later



5. user:updated - Triggers when the widget loads
6. user:cleared - Triggers when the widget loads


window.HotlineWidget.user.get() - Get User Promise

Response 


PROPERTIES TYPE DESCRIPTION
success Boolean TRUE - Success (200), FALSE - Error (Not 200)
status Var 1. 200 - Success
2. 401 - User not created


window.HotlineWidget.user.create(payload) - Create User Promise. 

Response


PROPERTIES TYPE DESCRIPTION
success Boolean TRUE - Success (200), FALSE - Error (Not 200)
status Var 1. 200 - Success
2. 401 - User not created
3. 403 - User exists. Use clear() user method
4. 404 - Init not called



window.HotlineWidget.user.update(payload) - Update User Promise

Response


PROPERTIES TYPE DESCRIPTION
success Boolean TRUE - Success (200), FALSE - Error (Not 200)
status Var 1. 200 - Success
2. 401 - User not created
3. 400 - Backend error



window.HotlineWidget.user.clear() - Clear User Promise
Response 


PROPERTIES TYPE DESCRIPTION
success Boolean TRUE - Success (200), FALSE - Error (Not 200)
status Var 1. 200 - Success
2. 401 - User not created
3. 400 - Backend error
4. 404 - Init not called


Web Messenger API: 

window.HotlineWidget.init(payload) 


OPTION DEFAULT VALUE DESCRIPTION
token*
Token generated in hotline web app
host*
Host URL
open false Window state of hotline widget is closed
externalId
Unique ID to identify the user
restoreId
Restore ID to synchronise the user


Note: *Options marked with asterisk are mandatory 



window.HotlineWidget.isOpen()
Returns the current window state of the hotline widget. TRUE - Opened / FALSE - Closed


window.HotlineWidget.isInitialized()
Returns TRUE if the init method is already called else FALSE


window.HotlineWidget.isLoaded()
Return TRUE if widget has completed loading


window.HotlineWidget.open(payload)
Opens the hotline widget



OPTION DEFAULT VALUE DESCRIPTION
payload
Use this to default to specific channel when the widget is opened
{ id: "<channelId>" }
or
{ name: "<channelName>" }
or
true - Opens default Channel




window.HotlineWidget.close()
Close the hotline widget


window.HotlineWidget.on(event, callback)
Subscribe to hotline widget events


window.HotlineWidget.off(event, callback)
Unsubscribe to hotline widget events


window.HotlineWidget.setExternalId(id)
Identify the user


window.HotlineWidget.setTags(tags)
Update tags to filter channels on page transition


Asynchronous Load

payload    Use this to default to specific channel when the widget is opened 
{ id: "<channelId>" } 
or
{ name: "<channelName>" } 
or
true - Opens default Channel