Accounts SDK - Text Documentation

The Accounts SDK (@livechat/accounts-sdk) is a JavaScript library that lets you implement the Sign in with Text flow — the easiest way to get access to basic information in Text accounts. The Sign in with Text flow lets you:

Get access to the Text account user’s email, account ID, or organization ID.
Receive an access_token that can be used to perform API calls.
Receive a code using the PKCE extension, which could be then used to obtain the account’s refresh_token and access_token.

User flow

Users start the flow by clicking the Sign in with Text button. If a user is not signed in, they’ll be asked to do that. Then, the user must give the app access to the specified parts of their Text account. Finally, the app receives an access_token that allows it to perform different API calls, limited to what the user agreed to in the prompt.

How to start

Step 1: Create a new app

Go to Settings → API access → OAuth clients and create a new OAuth client. You will receive a new client_id to use in the next steps. The Redirect URI field must match the URL of the website that has the Sign in with Text button installed. The button will not work with any other URL addresses.

Step 2: Include the SDK library

Install the SDK from NPM:

npm install --save @livechat/accounts-sdk@^2.0.0

import AccountsSDK from "@livechat/accounts-sdk";

Step 3: Prepare button container

Prepare the login button, which will invoke the authorization flow when a user clicks it.

<div id="login-button" style="background: url(.../livechat_sign_in.png)"></div>

// javascript
const instance = new AccountsSDK({
  client_id: "<your_app_client_id>",
  redirect_uri: "<your_app_redirect_uri>",
});

document.getElementById("login-button").onclick = (e) => {
  if (e && e.preventDefault) {
    e.preventDefault();
  }

  instance
    .popup()
    .authorize()
    .then((authorizeData) => {
      const transaction = instance.verify(authorizeData);
      if (transaction != null) {
        // authorization success
        // authorizeData contains `accessToken` or `code`
        // transaction contains state and optional code_verifier (code + PKCE)
        console.log("User access token: " + transaction.accessToken);
        document.getElementById("login-button").style.display = "none";
      } else {
        console.log("Redirect state doesn't match the previous one");
      }
    })
    .catch((e) => {
      console.error("Failed to authorize user", e);
    });
};

Use prompt: "consent" to force the app to ask you for access to certain resources.

Accounts SDK reference

Following classes and methods are available in the Accounts SDK:

Class	Methods
`AccountsSDK`	`popup()` `redirect()` `authorizeURL()` `verify()`
`Popup`	`authorize()`
`Redirect`	`authorize()` `authorizeData()`

AccountsSDK

The main instance of the SDK used to authorize users in Text Accounts.

const instance = new AccountsSDK({
  client_id: "<your_app_client_id>",
});

The constructor accepts an options object with the following properties:

Property	Required	Data type	Description
`client_id`	yes	`string`	Application Client Id (available in Text under Settings → API access → OAuth clients)
`prompt`	no	`string`	Use `consent` to force the consent prompt in a popup and the redirect flows. Default: `''`
`response_type`	no	`string`	OAuth response type. Possible values: `token` or `code`. Default: `token`
`popup_flow`	no	`string`	`auto` – close the popup automatically if the user is already logged in; `manual` - always show the popup that requires the user to provide their credentials; default: `auto`
`state`	no	`string`	OAuth state parameter. Use it for better security.
`verify_state`	no	`bool`	Check if `state` matches after the redirect; default: `true`
`scope`	no	`string`	The scopes your application will request from the user; if not provided, then all application scopes will be requested. Comma-separated string, default: `null`
`redirect_uri`	yes	`string`	OAuth redirect URI; default: the current location
`email_hint`	no	`bool`	Fill in email in forms
`server_url`	no	`string`	Authorization server URL
`tracking`	no	`object`	Object with tracking query string params
`transaction`	no	`object`	An object with options for the transaction manager
`pkce`	no	`object`	An object with the PKCE configuration

The transaction object consists of the following parameters:

Property	Required	Data type	Description
`namespace`	no	`string`	Transaction key prefix; default: `'com.livechat.accounts'`
`key_length`	no	`string`	Transaction random state length; default: `32`
`force_local_storage`	no	`bool`	Try to use localStorage instead of cookies; default: `false`

In the pkce object, define the following configuration properties:

Property	Required	Data type	Description
`enabled`	yes	`bool`	Enable OAuth 2.1 PKCE extension; default: `true`
`code_verifier`	no	`string`	Override the auto-generated code verifier.
`code_verifier_length`	no	`integer`	Define the length of the code verifier. It should be between 43 and 128 characters; default: `128`.
`code_challange_method`	no	`string`	Define the code challenge method. Possible values: `S256` or `plain`; default: `S256`

Returns a Popup object instance built on top of sdk.

Parameter	Data type	Description
`options`	`object`	An object with the same parameters as provided in `AccountsSDK`

const popup = instance.popup({
  client_id: "<your_app_client_id>",
});

redirect

Returns a Redirect object instance built on top of sdk.

Parameter	Data type	Description
`options`	`object`	An object with the same parameters as provided in `AccountsSDK`

const redirect = instance.redirect({
  client_id: "<your_app_client_id>",
});

authorizeURL

Creates an authorization URL for the given flow and parameters.

Parameter	Data type	Description
`options`	`object`	An object with the same parameters as provided in `AccountsSDK`
`flow`	`string`	`code` or `token`. `code` can only be used with the `PKCE` flow

const authURL = instance.authorizeURL(
  {
    client_id: "<your_app_client_id>",
  },
  "token",
);

verify

Verifies if the state parameter from the redirect matched the one provided upon initialization. If it does, the method returns Transaction. Otherwise, it returns null.

Parameter	Data type	Description
`authorizeData`	`object`	Data returned from the redirect

const transactionData = instance.verify(authorizeData);
if (transactionData) {
  console.log("Verified correctly");
} else {
  console.log("Url/state mismatch");
}

A class responsible for acquiring the user authorization data through a popup window.

Parameter	Data type	Description
`options`	`object`	An object with the same parameters as provided in `AccountsSDK`
`sdk`	`object`	An `sdk` instance

const instance = new AccountsSDK({
  client_id: "<your_app_client_id>",
});

const popup = new Popup(instance, instance.options);

A popup object instance can also be created via sdk:

const popup = instance.popup();

authorize

Returns a promise that resolves with the user authorization data or an error.

popup
  .authorize()
  .then((authorizeData) => {
    console.log("authorize data acquired: " + authorizeData);
  })
  .catch((e) => {
    console.error("Failed to acquire authorization data: " + e);
  });

The Sample app with the popup flow has a fully implemented authorization flow.

Redirect

A class responsible for acquiring the user authorization data through the redirect method.

Parameter	Data type	Description
`options`	`object`	An object with the same parameters as provided in `AccountsSDK`
`sdk`	`object`	An `sdk` instance

const instance = new AccountsSDK({
  client_id: "<your_app_client_id>",
});

const redirect = new Redirect(instance, instance.options);

A redirect object instance can also be created via sdk:

const redirect = instance.redirect();

authorize

Starts the redirect authorization flow.

redirect.authorize();

authorizeData

Checks if a user was redirected to the current origin with the authorization data. Returns a promise that resolves with the user authorization data or an error.

redirect
  .authorizeData()
  .then((authorizeData) => {
    console.log("Authorization data acquired: " + authorizeData);
  })
  .catch((e) => {
    console.error("Failed to acquire authorization data: " + e);
    redirect.authorize(); // Try to redirect user to authorization once more
  });

The Sample app with the redirect flow has a fully implemented authorization flow.

PKCE support

To acquire both access_token and refresh_token in a frontend application, use the PKCE Extension, which prevents the usage of a hijacked redirect by malicious apps.

Start by enabling PKCE. Provide AccountsSDK instance with PKCE options:

const instance = new AccountsSDK({
  client_id: "<your_app_client_id>",
  redirect_uri: "<your_app_redirect_uri>",
  response_type: "code",
  pkce: {
    enabled: true,
  },
});

Then, using the redirect flow, you’re able to receive the code authorization data:

instance
  .redirect()
  .authorizeData()
  .then((authorizeData) => {
    const transactionData = instance.verify(authorizeData);
    if (transactionData === null) {
      console.log("Failed to verify authorization data");
      return;
    }
    fetch(instance.options.server_url + "/v2/token", {
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json",
      },
      method: "POST",
      body: JSON.stringify({
        grant_type: "authorization_code",
        code: authorizeData.code,
        client_id: transactionData.client_id,
        redirect_uri: transactionData.redirect_uri,
        code_verifier: transactionData.code_verifier,
      }),
    })
      .then((res) => {
        res.json();
      })
      .then((data) => {
        console.log("User tokens: " + data);
      })
      .catch((e) => {
        console.log("Failed to exchange code: " + e);
      });
  })
  .catch((e) => {
    const wasRedirected = sessionStorage.getItem("lc_accounts");
    if (wasRedirected === "yes") {
      console.error("Couldn't authorize user: " + e);
      return;
    }
    sessionStorage.setItem("lc_accounts", "yes");
    instance.redirect().authorize(); // Initiate authorization redirect flow
  });

Response format

All authorize methods return the user authorization data on success, or an error on failure.

Success

Field	Returned	Description
`access_token`	only for `response_type: token`	Used for authorizing Text API calls.
`code`	only for `response_type: code`	Must be exchanged for `access_token` and `refresh_token`
`scope`	for both response types	An array of scopes that `access_token` has.
`expires_in`	for both response types	Defines for how long `access_token` will be valid.
`account_id`	only for `response_type: code`	Text Accounts user ID
`organization_id`	only for `response_type: code`	Text Accounts organization ID to which the account is logged in.
`client_id`	only for `response_type: code`	`client_id` that you passed in the `init` method.

Error

If the authorization process fails, the promise will be rejected with an error:

{
  "oauth_exception": "<exception_name>",
  "identity_exception": "<exception_name>",
  "description": "<exception_description>"
}

identity_exception

Possible values:

unauthorized – The resource owner identity is unknown or the consent is missing.

oauth_exception

Possible values:

invalid_request – The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_client – The client is not authorized to request a token using this method.
access_denied – The resource owner or authorization server denied the request.
unsupported_response_type – The authorization server doesn’t support acquiring a token using this method.

​User flow

​How to start

​Step 1: Create a new app

​Step 2: Include the SDK library

​Step 3: Prepare button container

​Accounts SDK reference

​AccountsSDK

​popup

​redirect

​authorizeURL

​verify

​Popup

​authorize

​Redirect

​authorize

​authorizeData

​PKCE support

​Response format

​Success

​Error

​identity_exception

​oauth_exception

User flow

How to start

Step 1: Create a new app

Step 2: Include the SDK library

Step 3: Prepare button container

Accounts SDK reference

AccountsSDK

popup

redirect

authorizeURL

verify

Popup

authorize

Redirect

authorize

authorizeData

PKCE support

Response format

Success

Error

identity_exception

oauth_exception