Introduction

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

User flow

Here’s the basic flow of signing in with chat.io:

Step 1

A user starts the flow by clicking the following button:

Step 2

If the user is not signed in to chat.io, they are asked to do so:

Step 3

Finally, the app receives access_token which allows it to fetch user’s email and license number.

Use cases

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

  • has access to chat.io user’s email or license number,
  • will receive access_token that can be used to make various API calls.

Setup

This tutorial explains how to create a “Sign in with chat.io” button and place it on a website.

1. Create a new app

Create a new app in the Developers Console. The app type must be Web app (frontend). You will receive a new client_id that you will need in the next steps.

Please note that Redirect URI field in the Console must match the URL of the website where you want to place the "Sign in with chat.io" button. The button will not work with any other URL addresses.

2. Include the SDK library

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

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

3. Prepare the button container

Create the space for your “Sign in with chat.io” button. You can use the native button or create a custom one, as described below.

Native “Sign in with chat.io” button

Use the following HTML code to prepare the container for your “Sign in with chat.io” button. The button will be automatically inserted into the container.

<div class="chatio-login-button"></div>
Don't remove the chatio-login-button class from the container, or the button won't work properly.

Custom “Sign in with chat.io” button

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.

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

4. Initialize the SDK

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

<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>

That’s it!

Your users will see the “Sign in with chat.io” button if they are not logged in to chat.io.

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

SDK documentation

Methods

AccountsSDK.init({ … })

Sample 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:

  • onIdentityFetched(error, data) – a 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()

Sample openPopup() method usage:

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

This method binds the onclick param to a custom HTML <a> element which replaces the default “Sign in with chat.io” button. See the example of a custom button in Prepare the 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>

This method signs out a user and executes a callback function (with no arguments) when it’s done.

instance.displayButtons()

Sample displayButtons() method usage:

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

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

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

This method re-renders the “Sign in with chat.io” button 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 a user completes the “Sign in with chat.io” flow, the error param will be null and the data param will include the authorization data:

  • access_token – used for authorization in API calls,
  • scopes – an array of scopes that access_token has access to,
  • expires_in – the time (in seconds) when access_token is valid,
  • entity_id – chat.io’s user email,
  • license – chat.io license number,
  • client_idclient_id that you passed in the init method.

Error

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

Authentication errors

Error type Values Description Examples
identity_exception invalid_request the request has a wrong format the request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once or is otherwise malformed
unauthorized the request is valid, but the identity data is wrong or the identity does not exists. If the identity ID is known, it’s added to a querystring as entity_id.
server_error the server has encountered an unexpected condition that prevented it from determining the identity
access_denied the identity is known, but access is denied because of business reasons. the identity is banned or its account version is wrong or unsupported

Authorization errors

Error type Values Description Examples
oauth_exception invalid_request the request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once or is otherwise malformed wrong HTTP method, invalid HTTP body encoding
unauthorized_client client is not authorized to request a token using this method 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 requested scope includes a scope not originally granted by the resource owner
unsupported_response_type the authorization server does not support obtaining a token using this method response_type is not token
invalid_scope the requested scope is invalid, insufficient, unknown or malformed scope not found, scope name not found
server_error the authorization server encountered an unexpected condition that prevented it from fulfilling the request server is not responding
temporarily_unavailable the 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 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 refresh token expired, access token expires
invalid_client client authentication failed (unknown client, no client authentication included, unsupported authentication method) user is using refresh token with wrong client_id
missing_grant the client is missing granted rights the grants were rejected or have never been given, or the client changed required grants
exception_details client_id_not_found wrong client_id, client_id does not exist.
redirect_uri_not_set client misconfiguration, tyhe client has not set redirect uri
invalid_redirect_uri redirect uri is not one of client’s allowed redirects
too_many_redirects the server has detected redirect loop, the client should not redirect too many times

Sample app

This sample app will display chat.io user’s license number when the user clicks the “Sign in with chat.io” button.

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

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

<script src="//cdn.chatio-static.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>