Authentication

The messaging Web Widget allows authentication of users so that their identity can be verified by agents using Zendesk.

Login

zE("messenger", "loginUser", jwtCallback<function>, loginCallback<function>)

Name	Type	Mandatory	Description
jwtCallback	function	true	A callback function to handle a new JWT generated during a user sign-in, or to manage an updated JWT when an existing session is accessed
loginCallback	function	false	A callback function to handle the result of the login attempt

When loginCallback is called, it receives an error parameter which will be either:

• null, indicating a successful login
• An instance of LoginFailedError which contains information about why the login failed

The LoginFailedError class has the following properties:

Name	Type	Description
messsage	string	A descriptive message that explains the error
reason	string	Provides additional details on the cause of the login failure
type	string	Indentifies the error type as LoginFailedError

Example:

zE( "messenger", "loginUser",
  function jwtCallback(callback) {
    callback("new-jwt-for-user")
  },
  function loginCallback(error) {
    if (error) {
      // Example error handling
      const { type, reason, message } = error
    }
  }
)

If your application has a login flow, or if a user needs to access the same conversation from multiple devices, you can use the loginUser API.

You can associate users with your own user directory by issuing a JWT credential during the login flow. For information on creating signing keys, see Authenticating end users in messaging. For information on creating JWT tokens, see Enabling authenticated visitors for messaging with Zendesk SDKs.

To properly initialize the Web Widget, call the login function as soon as the user logs into your website and their authentication is verified. This ensures the widget functions with the correct authenticated user flow once it is opened, either through end user interaction with the launcher or by calling the open function.

Expiring JWTs

If you want to generate credentials that expire after a certain amount of time, using JWTs is a good way to accomplish this.

The exp (expiration time) property of a JWT payload is honored by the messaging Web Widget. A request made with a JWT which has an exp that is in the past is rejected.

Keep in mind that using JWTs with exp means you need to handle regeneration of JWTs in the function that you provide when calling the loginUser API.

Dynamically fetching fresh JWT tokens with loginUser

When using the loginUser API, ensure that you provide a function that dynamically fetches a new JWT token each time the widget encounters a 401 error. This ensures that the user remains authenticated without needing to manually log in again.

zE("messenger", "loginUser", function (callback) {
  fetchJwtToken()
    .then(token => {
      callback(token)
    })
    .catch(error => {
      console.error("Failed to fetch new JWT:", error)
      // Optional: Log the user out or notify them
    })
})

Note:

• Using expiring JWTs: If you are using expiring JWTs, always fetch a new token inside the function you pass to loginUser. This guarantees that the token is valid and up-to-date.

• Static tokens: If you are not using expiring JWTs, you can pass a static token to the callback. However, this is not recommended as it does not account for security best practices, leaving your application vulnerable if the token is compromised.

• Error handling: Implement error handling in your token fetching logic to manage cases where the token cannot be retrieved.

Logout

zE("messenger", "logoutUser")

Your app may have a logout function that brings users back to a login screen. In this case, revert the messaging Web Widget to a pre-login state by calling the logoutUser API.

After a user is logged out, all conversation tags and conversation fields data is cleared. Use the Conversation Fields and Tags API again to apply conversation fields and tags data to a new conversation.