Skip to content

Authentication in Pleased Widget ​

The PleasedWidget interface provides two main commands: set:callback (token) and set:callback (login). These commands are used to enable authenticated users on the chatbot and register the login callback respectively.

set:callback command options ​

token ​

The set:callback (token) command is used to enable authenticated users on the chatbot. It's used to generate a JWE token for the user on your side. This token is used to identify the user and their previous requests.

The command takes a callback function as an argument. This callback function should return a promise that resolves to a JSON Web Encryption (JWE) token string. For details on how to obtain and integrate token-based authentication, see Integrating Authentication with Pleased Chat Widget.

Here's an example of how to use this command:

javascript
window.pLS('set:callback', {
  token: async () => {
    // Generate and return a JWE token
    const token = await generateTokenFromApiIfLoggedIn();
    return token;
  },
});

Please note that this callback can be called multiple times if the token is expired.

login ​

The set:callback (login) command is used to register the login callback. The callback function you provide should authenticate the user based on the provided username and password.

The command takes a callback function as an argument. This callback function should take a payload object with username and password. If the authentication is successful, the callback should return an object with token and bizCode equal to 10000. If the authentication fails, the callback should throw an error.

Here's an example of how to use this command:

javascript
window.pLS('set:callback', {
  login: async (payload) => {
    // Authenticate the user
    if (payload.username === 'admin' && payload.password === 'password') {
      return {
        bizCode: 10000,
        token: 'your-jwe-token',
      };
    }

    throw new Error('Login failed, invalid password');
  },
});

Authentication options ​

As guest ​

This is the widget's default behavior if you have not implemented any of the authentication options below.

When using the widget as a guest, there are some limitations. Users cannot access their previous conversation history, and because they are not authenticated, they must provide contact details before creating a new ticket or starting certain conversations.

To simplify this process, you can pre-fill the user's contact information using the set:visitor command. An example is shown below:

javascript
window.pLS('set:visitor', {
  name: 'your_name',
  phone: 'your_phone',
  email: 'your_email',
  foreignId: 'client-user-id',
});

Login with JWE token ​

This is one of the simplest and most user-friendly options. Once integration is complete on your side, set a callback via the set:callback command as shown in the example below:

javascript
window.pLS('set:callback', {
  token: async () => {
    try {
      const response = await fetch('your_backend_api/pleased-token');

      if (!response.ok) {
        throw new Error('Failed to generate token');
      }

      const tokenData = await response.json();

      // Return the token string
      return tokenData.token;
    } catch (error) {
      console.error('Token generation failed:', error);
      return null;
    }
  },
});

You may also want to set loginMethod to 'external'. In that case, if the user is not logged in when they start a chat, they will first see a prompt to log in or continue as a guest instead of the guest form. If they choose to log in, the request_login event is emitted. Handle it in your application to navigate the user to your login page. After a successful login, call widget:re_auth so the widget requests the token again. A full code example is shown below:

javascript
window.pLS('set:callback', {
  token: async () => {
    // handling token retrieval

    return YOUR_TOKEN_GOES_HERE;
  },
});

window.pLS('set:config', {
  loginMethod: 'external',
});

window.pLS('event:on', 'request_login', async () => {
  // Navigate the user to your login page and wait for login to complete

  window.pLS('widget:re_auth');
});

Login via Pleased Chat Widget ​

This method can be used on its own or together with token-based authentication. To use it, first set loginMethod to 'hybrid'. In that case, if the user is not logged in when they start a chat, they will first see the login form and an option to continue as a guest instead of the guest form. To handle login inside the chatbot, set a login callback via set:callback. It receives the username and password entered by the user. On your side, verify the credentials and return a response in the required format. A full code example is shown below:

javascript
window.pLS('set:callback', {
  login: async ({ username, password }) => {
    // Here you have to verify user credentials and receive a token

    return {
      bizCode: 10000,
      token,
    };
  },
});

window.pLS('set:config', {
  loginMethod: 'hybrid',
});