Integration with Zendesk Chat

How It Works

Integration with Zendesk Chat allows to check, whether the Zendesk Chat visitor is the Xsolla Login user or not. The external_id parameter that is used at 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 an 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 method.

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:

go get github.com/dgrijalva/jwt-go
go get github.com/rs/cors

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.

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)
    return
}

Decoding JWT

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

  • email — an email address
  • sub — user ID

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.

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.

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

Authenticating Visitor into Zendesk Chat

Allows to add 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:

zChat.init({
    account_key: ACCOUNT_KEY,
    authentication: {
        jwt_fn: function(callback) {
            fetch('https://example.com:8001/generate/token', {
                credentials: "include"
            }).then(function(res) {
                res.text().then(function(body) {
                    const jwt = JSON.parse(body).token;
                    callback(jwt)
                });
            });
        }
    }
});

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

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

Working with Visitor

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

For working with the Visitors group of methods 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. Make sure that the 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:

GET /api/v2/visitors/9855790-xjj3u5xPWhW1Fv HTTP/1.1

Host:
www.zopim.com

Headers:
Authorization: Bearer <token>

Example of the response:

{
  "banned": false,
  "notes": "",
  "id": "9855790.xjj3ukxyIhn6j3",
  "email": "email@email.com",
  "phone": "",
  "created": 1586950554,
  "name": "email@email.com",
  "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.