Introduction

User flow

“Sign in with LiveChat” flow is the easiest way to get access to basic information about LiveChat users. It allows you to quickly build an app that can access different parts of LiveChat account.

User starts the flow by clicking the following button:

If user is not signed in to LiveChat, he is asked to sign in:

Then, user must allow the app to access some parts of his account:

Finally, the app receives access_token that lets it perform REST API calls, limited to what the user agreed on. For example, you can display LiveChat tracking code which already includes user’s account number:

Use cases

With “Sign in with LiveChat” flow, you can easily build an app which:

  • has access to LiveChat user’s email or license number,
  • will receive access_token that can be used to make different REST API calls.

Setup

1. Create new app

Create new “LiveChat OAuth 2.0 Client” app in Developers Console. You will receive a new client_id that we will use in the next steps.

Please note that Redirect URI field must match the URL of the website with “Sign in with LiveChat” button installed. The button will not work on any other URL addresses.

2. Include SDK library

<script src="//cdn.livechatinc.com/accounts/accounts-sdk.min.js"></script>

Create a simple HTML page and include the following JavaScript library.

3. Prepare button container

Native “Sign in with LiveChat” button

<div class="livechat-login-button"></div>

Custom “Sign in with LiveChat” button

// javascript
var instance = AccountsSDK.init({ ... });
<!-- html -->
<a href="" onclick="instance.openPopup()">Sign in with LiveChat</a>

Insert HTML code to prepare the container for “Sign in with LiveChat” button. Its class attribute must have value of livechat-login-button. The button will be automatically inserted into the container.

If you prefer to design your own button, you can do that, too. Just bind the openPopup() method of AccountsSDK instance to the onclick attribute for your link or button.

4. Initialize the SDK

<script>
var instance = AccountsSDK.init({
  client_id: '<your_client_id>',
  onIdentityFetched: (error, data) => {
    if (data) {
      console.log('User authorized!');
      console.log('License number: ' + data.license);
    }
  }
});
</script>

Insert the following JavaScript code before the closing </body> tag.

That’s it!

Your users will see “Sign in with LiveChat” button if they are not yet logged in or they didn’t grant access for your app.

If they are already logged in, you will immediately receive valuable information about your user, such as their access_token or license number.

SDK documentation

Methods

AccountsSDK.init({ … })

Example init() method usage

var instance = AccountsSDK.init({
  client_id: "<your_client_id>",
  onIdentityFetched: (error, data) => {
    // ...
  }
});

This method initiates the SDK and returns the AccountsSDK object instance. It accepts an object with the following properties:

  • client_id – obtained from the Developers Console when you create your app.

  • response_type – (optional, defaults to token) Defines the type of the response that you will receive in onIdentityFetched callback. Two options are supported:

    token (default) – the response will include access_token that can be immediately used for calling REST API methods. Best suitable for client-side apps.

    code – the response will include code that can be exchanged for access_token and refresh_token. Best suitable for backend apps that authorize a user only once and refresh the access_token themselves from that moment.

    Read more about client-side and backend apps in Google OAuth tutorial.

  • onIdentityFetched(error, data) – the callback executed when user’s identity is fetched. The callback will include either error or data object depending on the current user authorization status.
    You will find the detailed documentation in Response format section.

instance.openPopup()

Example openPopup() method usage:

// javascript
var instance = AccountsSDK.init({ ... });
<!-- html -->
<a href="" onclick="instance.openPopup()">Sign in with LiveChat</a>

Binds onclick param for custom HTML <a> element that replaces the “Sign in with LiveChat” button. See the example of custom button in Prepare button container section.

instance.signOut(callback)

Sample signOut() method usage:

// javascript
var instance = AccountsSDK.init({ ... });

function signMeOut(e) {
  e.preventDefault();

  instance.signOut(function() {
    console.log('User signed out');
  });
}
<a href="" onclick="signMeOut(event)">Sign out</a>

It signs the user out and executes the callback function (with no arguments) when it’s done.

instance.displayButtons()

Sample displayButtons() method usage:

var instance = AccountsSDK.init({ ... });

// some DOM changes which cause buttons to disappear from DOM
// (...)

// inject buttons once again
instance.displayButtons();

It re-renders the “Sign in with LiveChat” buttons in the DOM. It’s helpful when you reload the app’s state and the DOM is cleared. This method is automatically executed by the init method.

Response format

onIdentityFetched callback is the heart of this SDK. It will be fired when user’s authorization status is fetched. This is where you pass authorization access_token to your app to build what you need.

Success

If the user passes through “Sign in with LiveChat” flow, error param will be null and data param will include authorization data, depending on response_code param value.

If response_code was set to access_token:

  • access_token – used for authorization in REST API calls,
  • scopes – array of scopes that access_token has access to,
  • expires_in – number of seconds from now that access_token will be valid,
  • entity_id – LiveChat user email,
  • license – LiveChat license number,
  • client_idclient_id that you passed in the init method.


If response_code was set to code:

  • code – must be exchanged to access_token and refresh_token,
  • scopes – array of scopes that access_token generated by this code will have access to,
  • expires_in – number of seconds from now that code will be valid,
  • entity_id – LiveChat user email,
  • license – LiveChat license number,
  • client_idclient_id that you passed in the init method.

Error

If the user is not logged in to LiveChat, data param will be null and error param will include the following properties:

Authentication errors

  • identity_exception – error type. Possible values:

    • invalid_request – request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once or is otherwise malformed.

    • unauthorized – request is valid, but identity data is wrong or identity does not exists. If identity id is known, it’s added to querystring as entity_id.

    • server_error – server encountered an unexpected condition that prevented it from determining identity.

    • access_denied – identity is known, but access is denied because of business reasons. For example identity can be banned or has wrong unsupported account version.

Authorization errors

  • oauth_exception – error type. Possible values:

    • invalid_request – request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once or is otherwise malformed. Examples: wrong HTTP method, invalid HTTP body encoding.

    • unauthorized_client – client is not authorized to request a token using this method. Examples: missing client_id param, incorrect client_id value, refresh_token not found, invalid client_secret, invalid redirect_uri.

    • access_denied – resource owner or authorization server denied the request. For example, requested scope includes a scope not originally granted by the resource owner.

    • unsupported_response_type – authorization server does not support obtaining a token using this method. For example, response_type is not token or code.

    • invalid_scope – requested scope is invalid, insufficient, unknown or malformed. Examples: scope not found, scope name not found.

    • server_error – authorization server encountered an unexpected condition that prevented it from fulfilling the request. For example, server is not responding.

    • temporarily_unavailable – authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

    • unsupported_grant_type – authorization grant type is not supported by the authorization server. For example, user is using disabled authorization grant type, such as client credentials grant.

    • invalid_grant – provided authorization grant (authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request or was issued to another client. Examples: refresh token expired, access token expires.

    • invalid_client client authentication failed (unknown client, no client authentication included, unsupported authentication method). For example, user is using refresh token with wrong client_id.

    • missing_grant – client is missing granted rights. Examples: grants were rejected, grants were never given, client changed required grants.

  • exception_details – error description. It is returned only in some cases. Possible values:

    • client_id_not_found – wrong client_id, client_id does not exist.

    • redirect_uri_not_set – client misconfiguration, client has not set redirect uri.

    • invalid_redirect_uri – redirect uri is not one of client’s allowed redirects.

    • too_many_redirects – server has detected redirect loop, client should not redirect too many times.

Example app

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
</head>
<body>

<h1>Hello, world!</h1>
<div class="livechat-login-button"></div>
<div id="license"></div>

<script src="//cdn.livechatinc.com/accounts/accounts-sdk.min.js"></script>
<script>
AccountsSDK.init({
  client_id: '<your_client_id>',
  onIdentityFetched: function(error, data) {
    if (data) {
      document.getElementById('license').innerText = data.license;
    }
  }
});
</script>
</body>
</html>

This example app displays LiveChat user’s license number when user clicks the “Sign in with LiveChat” button.