Web Chat Developer Tools

With the help of a developer, you can setup advanced controls over the appearance and presentation of Grata’s web chat. In this article we explain how to use your own custom buttons, hide or reveal Grata according to your own business logic, or adjust the position of Grata on a specific page or for a specific action.

Using a button on your site to launch Grata

You can designate any button ID or any class of buttons on your site to open Grata when a user clicks or taps on the button.

If you’re using a button on your site, you can continue to reveal the Grata button, or set the Grata button to be hidden by default on the Web Chat Behaviors tab on the Grata admin backend.

Even if you choose to hide presentation of the Grata button, once a user clicks on your button to open the chat window, your Grata button will show if the user minimizes the chat window while a chat session is active.

When to hide your button

Note that by default, Grata hides chat when a mobile device is rotated to landscape mode. This is by design as with a keyboard revealed and a browser header, there is very little space available to maintain a good user experience. If you are using your own buttons, we recommend you apply similar logic to your button(s) to hide on rotation. Alternatively, you can override the default setting from the Admin Backend to hide Grata chat, and instead choose to reveal Grata chat on rotation. You should also hide your chat button for Internet Explorer v10 or earlier.
We also recommend incorporating some of the following logic in your button implementation to make it as smooth as possible for your users:


If your own chat button displays on your site before Grata chat files have finished loading, or if for some reason your site is unable to connect to Grata, your customer may not get a response when they click on your chat button. To prevent this from happening, you can set an event listener for ‘grataReady’, which we will fire once the chat files have finished loaded. For example:

document.addEventListener('grataReady', CALLBACK);

CALLBACK Find your callback in your web chat script, which can be copied from your Grata admin backend.


'showGrata', 'hideGrata'

If you want to control when chat is presented based on your own business logic, you can set Grata to never reveal on the admin backend and instead fire showGrata and hideGrata events to manually control chat presentation. For example, if you only want to reveal live chat for logged in users, you could write a function to fire showGrata only upon successful user login. Once showGrata is fired, the Grata chat button will be revealed until your team goes offline or becomes busy. Otherwise you can fire hideGrata to hide the Grata chat button at any time.


If you want to enable advanced logic based on the status of your service team, you can also listen for the grataStatus event that tells you if your service team is online, busy, or offline.
Status values
0 = offline
1 = online and available
2 = online but busy (at capacity)
Grata will fire a new grataStatus update every two minutes.


The grataStart event is fired at the start of every web chat session, whenever an agent claims a waiting customer. It sends several values to your backend to help you identify which agent is talking to which customer. Use grataStart to tie Grata chat data to your website visitor sessions. E-Commerce clients use this for tracking sales commissions to customer service agents.
Add an event listener for grataStart and you will receive data in this format:

event.grataValues = {'agentName':
                     'customerName':      };

agentName The agent's name. These are not unique.
utm This is the UTM value, if set, on the agent's Grata user profile.
agentId The 8-9 digit ID number of the agent. These are unique.
userId The 8-9 digit ID number of the customer. These are unique.
customerName For most web chat users, this is the automatically generated user name "$ipLocaleName XXX"


Adjust Chat Position

Use the dataToGrata event listener to change the position of the chat button for a specific page or a specific event on a page. You can fire it as soon as the grataReady event (see above) is received, after reloading the page the values set in the Grata admin backend will take over, so reset it as needed. To adjust chat position, send a custom event with the value dataToGrata containing an object with the values for bufferX, bufferY, and/or zIndex. For example:

event.dataToGrata = {bufferX: '10%', bufferY: '5px', zIndex: 30};

Remember to specify the units you use for bufferX/Y: % em pc px vh etc.