Skip to content
SmartAgent

Webchat API

The script loaded onto your website includes an API which allows you to interact with the chat widget. You can use JavaScript on your website to control certain behaviours and send data from your website to the chat session.

Webchat API might be useful if you wish to send information to the chat about the current customer (e.g. a customer ID number entered onto the site) to avoid having to ask for this information within the chat flow. You may also wish to automatically open a chat window if a customer is visiting a help page.

Using the API

The API is accessible via the window._sa object. The following methods are currently available:

  • Toggle Chat (toggleChat)
  • Check Chat Status (isOpen)
  • End Chat (endChat)
  • Update Contact (updateContact)

Toggle Chat (toggleChat)

window._sa.toggleChat()

Toggles the state of the current chat window. When the chat is open it will be minimised and when it is minimised / closed it will be opened.

Returns: void

Example

You have created your own button to open /close the chat:

1 button.addEventListener("click" , () => {
2    // toggle webchat
3 window._sa.toggleChat();
4  });

Check Chat Status (isOpen)

window._sa.isOpen()

Returns a Boolean value indicating whether the chat is currently open (true) or Closed (false) to tell us if the chat is open.

Returns: boolean

Example

You can check if the chat is open before performing an action:

1 if (window._sa.isOpen())  {
2  console.log("the chat is currently open.");
3 } else {
4   console.log("The chat is currently closed.");
5 }

End Chat (endChat)

window._sa.endChat()

Ends the current chat session. This action will close the chat window and terminate any ongoing conversation.

Returns: void

Example

You can call this method when you want to end the chat session:

1 button.addEventListener("click" , () => {
2    // end the current chat session
3 window._sa.endChat();
4  });

Update Contact (updateContact)

window._sa.updateContact(contact)

Allows you to send information to the current chat session as a contact attribute. This can be used to set or update attributes relating to the current web session.

Once set, attributes are made available within the chat contact flows and can be used to influence contact routing, initiate data dips or present information in SmartAgent.

For more information on contact attributes, refer to the AWS documentation on contact attribute

Returns:void

Parameters:

contact: An object containing contact attributes to be sent to the chat session.

Example

A customer is already logged into your website and you do not wish them to go through ID&V again with the agent. You can pass in a logged in state and an authToken. You can also pass any additional data such as the number of products in their shopping basket.

1 const  updates = {
2  attributes: {
3    customerLoggedIn: "true",
4   authToken: "a5y7lu4klwcjwp66mx9s5n3ztctlriyj4ypl514wd050g726fd",
5   itemsInBasket: "2"
6 }
7 };
8 ,
9 //update contact attributes in the chat session
10 window._sa.updateContact(updates);

This would create 3 attributes on the contact, accessible in the contact flow: sa-customerLoggedIn and sa-authToken and sa-itemsInBasket. These values can then be used in the contact flow to look up the customers details using the authToken.

Contact attributes can be set at any time during the chat lifecycle - including before, on initialisation and even during.