External visitor identity

Overview

This tutorial describes how third-party system could generate JSON Web Tokens (JWT) for visitor to control the visitor's identity (visitor_id) on Giosg platform.

This might be useful for example when you want to authenticate your visitors on your third-party application and then use that information to create a visitor on Giosg platform. This way you can control that the same authenticated user on your platform will always have the same visitor ID also on Giosg platform.

Prerequisites

• Giosg account: Creating account and user with at least settings permission.
• Giosg account needs to have "Live" feature enabled
• Knowledge about HTTP requests, JSON Web Tokens and some basic programming skills

How external visitor identity works

External visitor identity is a way to authenticate visitors on Giosg platform using JSON Web Tokens (JWT). This allows third-party applications to create and manage visitor identities without needing to rely on Giosg's built-in way.

Normally Giosg platform generates visitor identities automatically for new visitors and stores them in cookies. However, in some cases you might want to control the visitor identity yourself, for example if you have your own authentication system and want to ensure each identified user is identified as same user on Giosg platform also.

This can be done by generating a JWT token that contains the visitor's identity information and signing it with a API Signing key. The token can then be passed to Giosg platform by placing it into window.giosgExternalIdentity variable before loading Giosg client script. This will allow Giosg platform to read the token and generate a visitor_id based on the information in the token.

When Giosg platform receives the token, it will verify the signature using the API Signing key and extract the visitor's identity information from the token. If the token is valid, Giosg platform will create a new visitor with the provided identity information or update an existing visitor if one already exists. Note that the actual visitor ID is generated by Giosg platform and is not directly controlled by the third-party application, so you can think of it as a way to link the external user ID with the Giosg visitor ID.

If the token is misssing required data, otherwise invalid or expired, Giosg platform will not create a new visitor and will instead return an error. This prevents the Giosg chat client from loading.

Create a API signing key

To generate JWT token, customer needs to first create a API Signing key in Giosg platform. This key is used to sign the JWT token so that Giosg platform can verify that the token is valid and was generated by the customer.

To generate a API Signing key, go to Settings > Company > API Signing Keys and click "Generate new signing key" button after giving a descriptive name for the key.

Copy the generated key and place it on some safe place. Note that you cannot see the key again after you close the dialog, so make sure to copy it somewhere safe.

Generate a token

Below is an example code snippet that shows how to generate a JWT token for external visitor identity using Python. This code should be implemented in the third-party system that wants to authenticate visitors on Giosg platform and the resulting token should be rendered to page into a window.giosgExternalIdentity.

Requirements:

• PyJWT

Example code:

import time
import jwt


def encode_giosg_external_user_identity_token(giosg_org_uuid, user_id, session_id, signing_key, token_ttl=10):
    """
    Customer would implement this function to generate the JWT token.
    """
    payload = {
        # This is mandatory. Used internally at Giosg to cleanup
        # old mappings after a certain period of time.
        "is_authenticated": True if user_id else False,
        # This is mandatory and MUST be unique for each identified user
        # If user is not logged in, this could be session id
        "identifier": user_id or session_id,

        # Claims:
        # Exp would is required so Giosg can accept the token
        # only for short time. Recommended to be 10 seconds.
        "exp": time.time() + token_ttl,
        # Issuer should match the Giosg org UUID so it cannot be used for other orgs
        # even if the key would be same for multiple orgs.
        "iss": giosg_org_uuid,
    }

    # This is the JWT token that would be sent to Giosg
    # signed with the pre-shared key Giosg and customer know
    jwt_auth = jwt.encode(
        payload,
        signing_key,
        algorithm="HS256",
    )
    return jwt_auth


# Call the function to generate the token and pass
# it to Giosg client by setting it to `window.giosgExternalIdentity`
external_identity = encode_giosg_external_user_identity_token(
    giosg_org_uuid="<YOUR_GIOSG_ORG_UUID>",
    user_id="<YOUR_USER_ID>",
    session_id="<YOUR_SESSION_ID>",
    signing_key="<YOUR_SIGNING_KEY>"
)

Using the above, generating a token for authenticated third-party user would look like this:

external_identity = encode_giosg_external_user_identity_token(
    giosg_org_uuid="12345678-1234-1234-1234-123456789012",
    user_id="user-123",
    session_id="session-123",  # or could be None
    signing_key="your-signing-key"
)

Using the above, generating a token for unauthenticated third-party session would look like this:

external_identity = encode_giosg_external_user_identity_token(
    giosg_org_uuid="12345678-1234-1234-1234-123456789012",
    user_id=None,
    session_id="session-456",
    signing_key="your-signing-key"
)

Testing the token

To test the generated token, you should set the window.giosgExternalIdentity variable to the generated token before loading the Giosg client script.

You should then be able to load the page and see the Giosg chat client loading without any errors if the token is valid. You should also be able to load the page on different browsers or incognito mode and see that the visitor ID is the same for the same token and chat sessions will continue to work as expected.

Test page example:

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Identity test page</title>
    </head>
    <body>

        <h1>Empty test page</h1>

        <script>
            window.giosgExternalIdentity = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc19hdXRoZW50aWNhdGVkIjp0cnVlLCJpZGVudGlmaWVyIjoiPFlPVVJfVVNFUl9JRD4iLCJleHAiOjE3NTMxOTE2NTQuMzkzNTIzLCJpc3MiOiI8WU9VUl9HSU9TR19PUkdfVVVJRD4ifQ._A5oExJKxq6BOi-wX8ok_oTHQ9C2Mhpoll_fUO7G4Jw";
        </script>
        <!-- giosg tag -->
        <script>
            (function(w, t, f) {
            var s='script',o='_giosg',h='https://service.giosg.com',e,n;e=t.createElement(s);e.async=1;e.src=h+'/live2/'+f;
            w[o]=w[o]||function(){(w[o]._e=w[o]._e||[]).push(arguments)};w[o]._c=f;w[o]._h=h;n=t.getElementsByTagName(s)[0];n.parentNode.insertBefore(e,n);
            })(window,document,"<Giosg organization id>");
        </script>
        <!-- giosg tag -->

        <p>Hello world</p>
    </body>
</html>

Important notes

Note that customer MUST always provide the external visitor identity token in window.giosgExternalIdentity for the logged out users of third-party systems also! This is to ensure that when a third-party system user logs out, the visitor ID will be changed and possible chats of the logged in user are not visible.

Customer is responsible for ensuring that the token is generated with a correct data! Giosg will trust the identifier value given in the token as long as the token validates. Giosg has no way of detecting if customer has used wrong identifier value, for example wrong user ID or same ID for multiple users.

So a care needs to be used while generating the token. The identifier value should be unique for each user in the third-party system and for each unauthenticated session.

Possible error responses

If the token is missing required data, invalid or expired, Giosg platform will return an HTTP 400 Bad Request error with a message indicating the problem.

Possible error messages include:

• Expired external identity token: If the token has expired.
• Invalid external identity token algorithm: If the JWT token is not signed with the expected algorithm HS256.
• Invalid external identity token issuer: If the JWT token issuer (iss) does not match the Giosg organization UUID.
• Could not decode external identity token: <token>: If the JWT token cannot be decoded, for example if it is malformed or no valid key was found.
• Missing mandatory field in external identity token: <field name>: If the JWT token is missing a mandatory field, such as identifier or is_authenticated.
• Field identifier is mandatory and cannot be empty.: If the identifier field is empty in the JWT token.

Fetching the chats of the external visitor

Once you have had conversations with the external visitors, you can fetch the chats of the visitor using the Giosg API and the external visitor identity token. You can use the List external visitors chats in a room API to retrieve the chats.

When you have fetched the chats, you can also fetch the messages of the chats using the List chat messages API.

Notes

• Actual generated visitor ID is not controlled by the third-party system, but is generated by Giosg platform based on the provided identifier in the token.
• Giosg does not clear the cookies from the browser when the visitor logs out from the third-party system. For this reason, the third-party system should always provide the window.giosgExternalIdentity variable with a new token when the user logs out.

Need help?

Go to https://giosg.com and as in a chat and you will be redirected to correct place! 😊

Endpoints used in this tutorial

List external visitors chats in a room API

List chat messages API