Where could I find the iAdvize public key?

Please see 2.4 iAdvize Public key (use for Production)

Expiration: session & token

There are 2 distinct things:

  • the lifetime of the encrypted token that the brand provides, for which we recommend a lifetime of 1 minute (but it could equal the session duration desired by the brand) (by default, it is set at 1 minute).

  • and the lifetime of the iAdvize session, which specifies when the engagement/conversation session must re-verify the visitor's identity, and this one is based on the brand's use case: A bank would prefer a short delay (for example 7 minutes). For an electricity supplier, 20-30 minutes seems acceptable (by default, it is set at 60 minute).

How do we know that the visitor is authenticated?

Read this section to see examples of what is seen on the agent side and on the visitor side.

When do I need to call the activate function?

The activate function needs to be called every time that the iAdvize tag is loaded. It means that you will need to call the activate function on every page change, once per page.

What happens when a visitor logs in and logs out?

Visitor id might change during the conversation if the visitor logs in and logs out.

userId defined in the JWE should remain static and constant. Visitor id (used when the visitor isn't authenticated) is different and is an iAdvize internal data. All the cases of authentication during a conversation, that could impact the visitor id (but not the userId) are described here.

My visitor is authenticated (a JWT is in the local storage) but I don’t have a padlock πŸ”’ on the desk of the agent

Be sure, when you are in an authenticated space of your website where the visitor authentication is enabled, to remove the usage of the `extId` system: About the External ID usage (extId)

Activation success or failure

How can I test my JWE?

Test your JWE with this GraphQL API call:

curl --request POST \
  --url https://api.iadvize.com/graphql \
  --header 'Authorization: Bearer <REPLACE GRAPHQL BEARER TOKEN HERE>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"mutation TestJWE {\n  testVisitorAuthenticateFromCredentials(input: {projectId: \"YOUR PROJECT SID\", credentials: \"<REPLACE JWE HERE>\"}) {\n    visitorSessionToken {\n      accessToken\n    }\n  }\n}\n","operationName":"TestJWE"}'

Otherwise, with this implementation:

const activation = await iAdvize.activate(async () => {
  return {
    authenticationOption: {
      token: visitor_token,
console.log(`activation : ${JSON.stringify(activation, null, 2)}`);

You should see this in the console:

activation : {
  "authentication": {
    "option": {
      "token": "<Response token>"
    "status": "authentication-success"

Error type

Why it happens

What to do about it

A valid authentication option must be provided,

The brand makes a mistake on authenticaton.option

Give valid arguments: authenticationOption : { type: 'SECURED_AUTHENTICATION', token: visitor_token }

An activation is already ongoing

The brand calls activate several times in a row before resolving the first one

Wait for call to finish (you can await iAdvize.activate)

Can't activate twice, please logout first

The brand calls activate several times in a row after the first has been successfully resolved

Logout before login if already authenticated

Failed to fetch authentication with a server error

Something went wrong on the server side

In this case, there could be different errors: wrong keys, no flag set, wrong token, etc. (this is on the iAdvize side so the client can create a ticket)

Failed to authenticate visitor from credentials : the website is not correctly setup (null)

JWT not valid

Ensure you set all the required claims with the right prefixes


Ensure the JWT is signed with the right algorithm

         "alg": "RS256"

Ensure the JWE is encrypted with the right algorithm

         "enc": "A256GCM",
         "alg": "RSA-OAEP-256"

Ensure you use the right private key and the right iAdvize public key. Ensure iAdvize setup your public key in your settings.

Last updated