Integration with Zendesk Chat

How it works

Integration with Zendesk Chat allows you to link users of the Xsolla Login product to your project with Zendesk Chat visitors who submit questions to your support team. The external_id parameter that is used on Zendesk’s side corresponds with the user ID in your Login project. If you identified a visitor as an Xsolla Login user, you will have the ability to manage their account via Publisher Account.

Who can use it

Partners who have already integrated Login and have a Zendesk Chat account.

How to get it

To link a visitor:

  1. Authenticate a user in your Login project by one of the following requests:
  2. Generate a Zendesk JWT.
  3. Authenticate a visitor into Zendesk Chat.

Generating Zendesk JWT

The Zendesk JWT is based on a token received from the Xsolla Login server when authenticating a user in your Login project. You can store a token in cookie files on a required domain and add it to a HTTP request when generating a Zendesk JWT.

You can also set your own format of a response when implementing the call.

Below is a simplified version of a Zendesk JWT getting flow based on Go. The full Zendesk JWT generation code is found on GitHub.

Install the following packages before generating a JWT:

Full screen
Small screen
go get
go get

To get a Zendesk JWT:

  1. Validate a JWT.
  2. Decode a JWT.
  3. Form a list of JWT claims.
  4. Sign a JWT.

Validating JWT

Extract a JWT from cookie files and validate it by a secret key found in Publisher Account > your Login project > General settings > Secret key.

Full screen
Small screen
cookie, err := r.Cookie("token")

token, err := jwt.Parse(cookie.Value, func(token *jwt.Token) (interface{}, error) {
  if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
    return nil, errors.New("unexpected signing method")
  return []byte(loginSecret), nil

var loginClaims jwt.MapClaims
var ok bool
if loginClaims, ok = token.Claims.(jwt.MapClaims); !ok || !token.Valid {
  writeErrorResponse(w, "00-01", "Token is invalid", http.StatusUnauthorized)

Decoding JWT

Decode a JWT and extract values of the following claims from it:

  • email — an email address
  • sub — user ID

Full screen
Small screen
var sub, email string
sub, _ = loginClaims["sub"].(string)
email, _ = loginClaims["email"].(string)

Forming list of JWT claims

Form a list of claims for a JWT. You can find descriptions of every claim in Creating a JWT token module.

Full screen
Small screen
zendeskClaims := jwt.MapClaims{}
zendeskClaims["name"] = email
zendeskClaims["email"] = email
zendeskClaims["external_id"] = sub
zendeskClaims["iat"] = time.Now().UTC().Unix()

Signing JWT

Sign a token with a secret key of your Zendesk Chat account. You can find it in Chat dashboard > Settings > Widget > Widget security tab > Visitor Authentication.

Full screen
Small screen
zendeskToken := jwt.NewWithClaims(jwt.SigningMethodHS256, zendeskClaims)
zendeskTokenString, _ := zendeskToken.SignedString([]byte(zendeskSecret))

Authenticating visitor into Zendesk Chat

This allows adding the following visitor data to Zendesk Chat:

  • name
  • email address
  • identifier
Visitor data is added while generating a Zendesk JWT.

Use a received Zendesk JWT to authenticate a visitor into Zendesk Chat. Initialize the Web SDK with the authentication option in the following way:

Full screen
Small screen
  account_key: ACCOUNT_KEY,
  authentication: {
    jwt_fn: function(callback) {
      fetch('', {
        credentials: "include"
      }).then(function(res) {
        res.text().then(function(body) {
          const jwt = JSON.parse(body).token;

The visitor authentication flow is described in the instruction and Web SDK.

Social networks may not pass data about user email addresses. Follow the instruction to request an email-address.

Working with a visitor

After successful authentication, a visitor will be displayed in your Zendesk Chat account > Visitors module.

For working with the Visitors endpoint, you will need to get a token (instruction). When working with data of a visitor who is linked to your Login project:

  1. Get visitor data.
  2. Visitor is linked to your Login project.

Getting visitor data

To execute the Get a Visitor request, you should get Visitor ID. You can find it in your Zendesk Chat account by choosing a required visitor.

Example of the Get a Visitor request:

Full screen
Small screen
GET /api/v2/visitors/9855790-xjj3u5xPWhW1Fv HTTP/1.1
Authorization: Bearer <token>

Example of the response:

Full screen
Small screen
HTTP/1.1 200 OK
Content-Type: application/json

  "banned": false,
  "notes": "",
  "id": "9855790.xjj3ukxyIhn6j3",
  "email": "",
  "phone": "",
  "created": 1586950554,
  "name": "",
  "external_id": "82cd5e0c-c3ff-11e9-b199-c1e5fc81c37f"

If a visitor is linked to your Login project, the external_id parameter in received data will correspond with user ID. You can find user ID in Publisher Account > your Login Project > Users > Username/ID.