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:
   • Authentication via username and password (JWT and OAuth 2.0).
   • Authentication via social networks (JWT and OAuth 2.0).
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:

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

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

• email — an email address
• sub — user ID

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

Forming list of JWT claims

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

Signing JWT

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

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.

Working with visitor

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

Example of the Show Visitor request:

GET https://www.zopim.com/api/v2/visitors/9855790-xjj3u5xPWhW1Fv HTTP/1.1
Authorization: Bearer <token>

curl --request GET \
  --url https://www.zopim.com/api/v2/visitors/9855790-xjj3u5xPWhW1Fv \
  --header 'authorization: bearer_token'

Example of the response:

HTTP/1.1 200 OK
Content-Type: application/json

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

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

Checking visitor linking to Login project