Zowie Widget JS SDK

Installation

Use the code below to install Zowie Chat on your website. Replace {INSTANCE_ID} with ID and ${URL} with URL address received during the widget setup process.

<script type="text/javascript">
  (function (d, s, id, cb) { var js = d.createElement(s); var n = d.createElement("div"); n.id = id; if (js.readyState) { js.onreadystatechange = function () { if (js.readyState === "loaded" || js.readyState === "complete") { js.onreadystatechange = null; cb(); } }; } else { js.onload = function () { cb(); }; }
    js.src = "${URL}";

    document.body.appendChild(js);
    document.body.appendChild(n);
  })(document, "script", "chatbotize", function () {
		Zowie.init({
      instanceId: "${INSTANCE_ID}",
      startOnOpen: true,
      headerMode: "white"
    });
  });
</script>

Properties

You can customize the behavior of Zowie Chat with the properties described below.

Property name	Type	Example	Description
name	String	Zowie	Override widget's name.
engagementMessage	String	Type your message...	Override widget's engagement message.
ctaHeader	String	Hello!	Override widget's call to action header.
ctaText	String	How can I help you?	Override widget's call to action text.
accessToken	String	See below	Pass token used for customer authentication.
metadata	Metadata	See below	Pass metadata object with customer properties.
position	Position	See below	Pass position object to customize chat position.
resetSession	Boolean	false	Reset persisted customer's session on start.
sessionTimeout	Number	30000	Timeout persisted customer's session after elapsed timeout (in milliseconds).
showOnLoad	Boolean	true	Show the widget once a page is loaded according to configured placement and availability policies.
startOnOpen	Boolean	true	Show Welcome message once a user opens chat first time
allowPickEmoji	Boolean	false	Allow a customer to use the emoji picker feature.
allowFileUpload	Boolean	false	Allow a customer to use the file upload feature.
allowFileExtensions	String	.jpeg,.jpg,.png,.pdf	Comma separated list of supported extensions to be supported for upload.
allowEndChat	Boolean	false	Allow a customer to end chat session.
allowDownloadTranscript	Boolean	true	Allow a customer to download chat transcript.
surface	String	"desktop-mobile"	Override on which platforms the widget should be visible. Allowed values are: "mobile", "desktop" and "desktop-mobile" (default).

📘
Regardless of what is set in the allowFileExtensions, Zowie Chat widget will only be able to process files the following file types:
JPEG, PNG, GIF, MP4, PDF, MP3, AAC, DOC, DOCX, TXT, ZIP, RAR, ZIP7, HTML, SPX, MOV, AVI, XLS, XLSX, CSV.

Metadata

This object allows you to pass additional information about your customer, which can be used to personalize your automation scenarios. You can use our defaults like firstName, lastName etc. or pass your custom parameters using extraParams field.

{
  "firstName": "Tom",
  "lastName": "Zowie",
  "locale": "en-US",
  "timezone": "GMT+2",
  "phoneNumber": "+1 982 888 291",
  "email": "[email protected]",
  "extraParams": {
     "segment": "enterprise",
     "currentPlan": "professional"
  }
}

Property name	Type	Required	Description
firstName	String	No	First name of a customer.
lastName	String	No	Last name of a customer.
locale	String	No	A locale of a customer used to pickup conversation language.
timezone	String	No	A timezone of a customer.
phoneNumber	String	No	Phone number of a customer.
email	String	No	E-mail address of a customer.
extraParams	Map[String, String]	No	Object with additional params you can use to personalize automation scenarios.

Position

This configuration object allows you to customize the position of Zowie Chat. User mobileOffset property to set mobile breakpoint. This will overwrite custom mobile positioning options which can be set via Zowie UI.

{
  "desktopBottom": 25,
  "desktopRight": 20,
  "mobileBottom": 20,
  "mobileRight": 25,
  "mobileOffset": 425
}

Authentication

You can pass accessToken value which is used by Zowie to authenticate users and provide authenticated experience.

Zowie.init({
  ...
  
  accessToken: "YOUR_TOKEN"

  ...
});

Read more about JWT authentication here.

Methods

Zowie Chat exposes JS methods that can be used to trigger certain actions on a widget.

Method	Description
`Zowie.start()`	Open widget and initialize conversation.
`Zowie.open()`	Open widget's window, keep icon visible.
`Zowie.close()`	Close widget's window, keep icon visible.
`Zowie.show()`	Show widget's window and icon if hidden.
`Zowie.hide()`	Hide widget's window and icon if visible.
`Zowie.updateMetadata(Metadata)`	Update customer's metadata passing object described above.
`Zowie.updatePosition(Position)`	Update widget's position passing object described above.
`Zowie.sendReferral(string)`	Send referral parameter which can be used to trigger configured scenario (learn more).
`Zowie.setMessage(string)`	Set message in customer's input.
`Zowie.isAvailable()`	Returns true if configured placement and availability policies allow displaying the widget. Returns false otherwise.
`Zowie.setAccessTokenCallback(callback)`	Register callback which will be invoked whenever user click on chat call to action to start a chat. Callback should be a function with following signature `(onSuccess: string => void, onFailure: string => void)`. Call `onSuccess` and provide `accessToken` or call `onFailure` with error message. Zowie will wait with setting up a session until `onSuccess`/`onFailure` is being called.
`Zowie.logout()`	Logout current user and remove current chat session.

Events

To react or measure Zowie chat behavior, you can use callback functions exposed by Zowie. You can pass this function as part of Zowie.init() method.

Zowie.init({
  ...
  
  onShow: function() {
  
  },
  onHide: function() {
  
  },
  onStart: function() {
  
  },
  onOpen: function() {
  
  },
  onClose: function() {
  
  },
  onLoaded: function() {
  
  },
  onEndChat: function() {
  
  },
  onMessageSent: function(message) {
  
  },
  onMessageReceived: function(message) {
  
  },
  onLinkClicked: function(message) {
  
  },
  onMetadataUpdated: function(Metadata){
  
  }

  ...
});

Function	Description
onShow	Invoked whenever a chat widget has been shown.
onHide	Invoked whenever a chat widget has been hidden.
onOpen	Invoked whenever chat window has been opened.
onClose	Invoked whenever chat window has been closed.
onLoaded	Invoked whenever chat window has been loaded.
onStart	Invoked whenever a user starts a new conversation.
onEndChat	Invoked whenever a user ends conversation.
onMessageSent(message: string)	Invoked whenever a user sends a message.
onMessageReceived(message: string)	Invoked whenever a user receives a message.
onLinkClicked(link: string)	Invoked whenever a user clicks a link.
onMetadataUpdated(Metadata)	Invoked whenever metadata object is updated.

Conversation language

By default, Zowie relies on the user's browser language to choose the language used for conversation with the chatbot. If you need to customize this to be based on website language for example, then you can pass a value for the locale property in the metadata field.
If you want to start the widget in English, go ahead with the following example:

Zowie.init({
    instanceId: "{INSTANCE_ID_GOES_HERE}",
    metadata: {
        locale: "en-US"
    }
});

If you want to start the widget in French, then you need to provide a correct value for French locale:

Zowie.init({
    instanceId: "{INSTANCE_ID_GOES_HERE}",
    metadata: {
        locale: "fr-FR"
    }
})

Google Analytics tracking

You can use callback events to track user interactions with a widget and send events to Google Analytics.

Zowie.init({
  ...,
  
  onLoaded: function() {
    ga('send', 'event', 'Zowie', 'loaded');
  },
  onOpen: function() {
    ga('send', 'event', 'Zowie', 'opened');
  },
  onClose: function() {
    ga('send', 'event', 'Zowie', 'closed');
  },
  onHide: function() {
    ga('send', 'event', 'Zowie', 'hidden');
  },    
  onShow: function() {
    ga('send', 'event', 'Zowie', 'showed');
  },        
  onStart: function() {
    ga('send', 'event', 'Zowie', 'chat_started');
  },        
  onEndChat: function() {
    ga('send', 'event', 'Zowie', 'chat_ended');
  },        
  onMessageSent: function(message) {
    ga('send', 'event', 'Zowie', 'message_sent');
  },        
  onMessageReceived: function(message) {
    ga('send', 'event', 'Zowie', 'message_received');
  },
  onLinkClicked: function(link) {
    ga('send', 'event', 'Zowie', 'link_clicked');
  }  

  ...
});