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.

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:

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.

  {
    "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.

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:

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.

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.

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.

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);
    });

{
  "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.

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 night

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