Authenticating Users

If your website or app has a way to authenticate users then you can pass the authenticated user's details to the chat widget. In order for our server to trust the passed data we recommend you use JSON Web Token (JWT) to sign the data. This will require your website to connect to your own server that would generate the JWT on the server side as API keys used to generate JWT should not be exposed to the web/mobile client.

Architecture

Imagine you have a user externalId that you want to pass to the widget for an authenticated user. In order for DG server to trust that this is indeed the correct externalId you would need to pass the JWT token containing the externalId.

The sequence of steps is the following:

1. Website client/app requests JWT from your server (could be part of the authentication flow).
2. Your server uses DG API Key and Secret to generate a JWT with the externalId of the user.
3. Website client/app passed the JWT to the chat widget as one of the inputs.

Generating JWT

1. Create DG API Key and Secret on the DG dashboard. See more details about API Key/Secret. API Key and Secret should be securely stored on server side and not exposed to the public clients.

2. Use the DG API Key and Secret to sign the JWT. Put the API Key in JWT header and use API Secret as JWT secret. Example code in node.js using jsonwebtoken:

var jwt = require('jsonwebtoken');
var userJwt = function(externalID) {
    return jwt.sign(
        {
            scope: 'user',
            external_id: externalId
        },
        DG_API_SECRET,
        {
            header: {
                alg: 'HS256',
                typ: 'JWT',
                kid: DG_API_KEY
            }
        }
    );
};

🚧

Generate JWT on the Server

It's important you generate JWT on the server as the API Secret should not be exposed to the public clients.

Passing the token to the chat widget

Once you have generated the jwt you can pass it to the chat widget as an input via the chat widget config defined in your page:

window.DG_CHAT_WIDGET_CONFIG = {
   widgetId: '22df40c4-110f-4b6f-aa2b-aeaffd6d1179',
   env: 'eu',
   metadata: {
     auth_token: 'YOUR_AUTH_TOKEN'
   }
}

If your token is short lived it is possible to send updated tokens by sending a system message like so:

window.dgchat.methods.sendSystemMessage({ "name":"auth_token","payload":"YOUR_AUTH_TOKEN" })