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:

Copy
Full screen
Small screen
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.

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

Decoding JWT

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

  • email — an email address
  • sub — user ID

Copy
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.

Copy
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.

Copy
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:

Copy
Full screen
Small screen
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 instruction 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 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 Show Visitor request, you should get Visitor ID. You can find it in your Zendesk Chat account by choosing a required visitor.

Example of the Show Visitor request:

Copy
Full screen
Small screen
http
  • http
  • curl
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:

Copy
Full screen
Small screen
http
  • http
  • curl
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"
}

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.

Was this article helpful?
Thank you!
Is there anything we can improve? Message
We’re sorry to hear that
Please explain why this article wasn’t helpful to you. Message
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.
Rate this page
Rate this page
Is there anything we can improve?

Don’t want to answer

Thank you for your feedback!
Last updated: April 12, 2021

Found a typo or other text error? Select the text and press Ctrl+Enter.

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!