Pricing Updates ✨ Grouped chats and quick actions Login Start your trial

Authorization API

To ensure secure access to the Chatness API, you need to authenticate your requests. Chatness provides multiple authentication methods tailored to different use cases, allowing you to choose the most suitable one for your scenario.

Auth attributes

Name
token
Type
string
Description

The token for contact authentication within the widget

Name
createdAt
Type
string
Description

Timestamp of when the token was created

Name
expiresAt
Type
string
Description

Timestamp of when the token will expire

Org authorization

With the Org authorization, you will use a Bearer token containing the secret generated in your account to authenticate your HTTP requests as an organization. This method is intended to work within servers only, so you must never, in any circumstances, expose the generated secret for an organization.

Never expose your organization secret to the public.

Please don't commit your Chatness token to GitHub or anywhere else! If you suspect your secret has been compromised, you can revoke it anytime in your account settings.

Authorized request example
import { Chatness } from '@chatness/server';

// obtain a `orgToken` from the Chatness app
const orgToken = 'your-org-token';

// obtain a `botId` from the Chatness app
const botId = 'your-bot-id';

// init the Chatness SDK
const chat = new Chatness({
  orgToken,
  botId
});

// search for contacts
const { data } = await chat.contacts.search({
  page: 1,
  limit: 10,
  query: 'john'
});

console.log(data)

Contact authorization

In order to authorize a contact within your widget, your server should first request a session token by passing the contact id or email to the auth endpoint. Here's how to generate a session token for your contact:

Examples
import { Chatness } from '@chatness/server'

const orgToken = 'your-org-token';
const botId = 'your-bot-id';

const chat = new Chatness({
  orgToken,
  botId
});

// create token
const { data } = await chat
  .auth
  .contacts
  .tokenize({
    // use either id or email
    // id: 'your-contact-id',
    email: '[email protected]'
  });

const { token } = data;

// pass down the contact token
// to your frontend application
console.log(token);

A contact token will be generated with 1-year validity, after this period the token is automatically invalidated and the user using it become anonymous.

Generated token
  {
    "data": {
      "token": "c:f34018111f0526dd64bf8f097494f6e4",
      "createdAt": "2023-12-08T00:00:00.000Z",
      "expiresAt": "2024-12-08T00:00:00.000Z"
    }
  }

The generated contact token will look like the above json and they can be exposed. We recommend generating a new token for each session only when needed. Meaning, when users log into your system, you generate a new token, pass it down to the widget, and when they log out from your system, you revoke the token.


Widget authorization

Once the contact is authorized and you have a token, you can pass it down to the widget implementation and authenticate your visitors so they can start an identified conversation with your bot.

The widget can then be authenticated by your frontend:

Examples
import { Chatness } from '@chatness/browser';

const botId = 'your-bot-id';

const chat = new Chatness({ botId });
const token = 'c:f34018111f0526dd64bf8f097494f6e4';

// log user in the browser
await chat.auth.contacts.login({ token });

You don't need to call the login method everytime your app is loaded. We recommend calling it only once, when the user logs in your system, and then when they log out, revoke the session by calling the logout method.


Widget logout

To revoke the authorization of a contact in the browser, you can call the public API to log the connected user out right away. This will ensure the session within the widget is cleared and refreshed as anonymous.

Examples
import { Chatness } from '@chatness/browser';

const botId = 'your-bot-id';

const chat = new Chatness({ botId });

// log the current user out
await chat.auth.contacts.logout();

in case you're tracking the contact token in your database, you can optionally revoke a session from the server, this will automatically log the user out from the widget.


Create a contact token

PUT

/v1/bots/{botId}/auth/contacts

Allows to authenticate a contact. If successful, the response will contain a session token created for the contact you can then pass down to your widget implementation.

Required attributes

Name
botId
Type
string in pathname
Description

The ID of the bot.


Optional attributes

Name
id
Type
string in body
Description

The contact id.

Name
email
Type
string in body
Description

The contact email.

Examples
import { Chatness } from '@chatness/server'

const chat = new Chatness({ orgToken, botId })
const email = '[email protected]'

chat.auth
    .contacts
    .tokenize({ email })
    .then(({ status, data }) => {
      const { token } = data;
      console.log(status, token);
    })
    .catch(({ status, error }) => {
      console.log(status, error);
    });

Generated token
{
  "data": {
    "token": "c:f34018111f0526dd64bf8f097494f6e4",
    "createdAt": "2023-12-08T00:00:00.000Z",
    "expiresAt": "2024-12-08T00:00:00.000Z"
  }
}

Revoke a contact token

DELETE

/v1/bots/{botId}/auth/contacts/{contactToken}

Allows to revoke a contact token, useful for the logout action of your system. If successful, the response will contain a status 204.

When a session is revoked by the server, the logged session in a widget should automatically be cleared and refreshed as anonymous.

Required attributes

Name
botId
Type
string in pathname
Description

The ID of the bot.

Name
contactToken
Type
string in pathname
Description

The contact token.


Examples
import { Chatness } from '@chatness/server';

const chat = new Chatness({ orgToken, botId });

// stored token
const contactToken = 'c:f34018111f0526dd64bf8f097494f6e4';

await chat.auth.contacts.revoke({ contactToken });

Get started with Chatness this afternoon

Each subscription goes towards aggressively adding new features built with customers' best interests at heart, including your privacy.

© 2024 Chatness - A product by IntenseloopChatness uptime in the last 180 days