Authentication

You'll need to authenticate your requests to access any of the endpoints in the Chatness API. In this guide, we'll look at how authentication works. Chatness offers two ways to authenticate your API requests: Org and Visitor authorization.

Org authorization

With the Org authorization, you use a Bearer token containing the secret generated in your account to authenticate your HTTP requests as an org. This method only works for servers and you should never expose the generated token. Here's how to authenticate using cURL:

Example request with bearer token to search for contacts

curl -X POST 'https://api.chatness.ai/v1/bots/{bot}/contacts?query=john%20doe' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {orgToken}'

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

Contact authorization

In this mode of authentication, you pass a contact id or email to the [auth/contact] endpoint. This method is used to authenticate your visitors based on your contacts database. Here's how to authenticate using cURL:

Example request for auth with contact id

curl -X POST 'https://api.chatness.ai/v1/bots/{botId}/auth/contact' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {orgToken}'
  -d id="{contactId}" \

Alternatively, you can also pass the contact email to the auth/contact endpoint. Here's how to authenticate using cURL:

Example request for auth with contact email

curl -X POST 'https://api.chatness.ai/v1/bots/{botId}/auth/contact' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {orgToken}'
  -d email="{contactEmail}" \

A contact token will be generated with a validity period of 1 year.

Contact session token example

{
  "token": "e:f34018111f0526dd64bf8f097494f6e4"
}

You can then use this token to authenticate your visitors when the Chatness widget is loading:

Chatness widget startup example

<html>
  <head>
    <!-- // ... -->
    <script>
      (function () {
        // const script = document.createElement('script');
        // script.id = 'chatness';
        // script.type = 'module';
        script.src =
          // grab the full script src from your bot settings
          '/widget.mjs?bot={bot}&token={token}';
        // script.async = true;
        // document.head.appendChild(script);
      })();
    </script>
  </head>

Or you can use the token to authenticate your visitors when the Chatness widget is already loaded:

  const token = 'c:f34018111f0526dd64bf8f097494f6e4';
  window.Chatness.auth.contacts.login({ token });     

Using SDK

Currently we provide an SDK for Node.js. You can install the node package using npm:

Install Chatness SDK for Node.js

npm install @chatness/node

Then you can use the SDK to authenticate your requests:

Chatness Node SDK example

const Chatness = require('@chatness/node');

const token = process.env.CHATNESS_ORG_TOKEN;
const bot = process.env.CHATNESS_BOT;

const chat = new Chatness({
  token
})

// Search for contacts
chat.contacts({ bot })
    .search({ query: 'john doe' })
    .then(({ status, data }) => {
      console.log(status, data);
    })
    .catch(({ status, error }) => {
      console.log(status, error);
    });

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