Integrating with Zendesk

Before you begin

1. Sign up for or switch to a Zendesk Service account with an Enterprise plan, which is required.

2. Create a subdomain for your service desk. After you sign up and specify a subdomain, your Zendesk console is available from a URL with the syntax: <subdomain>.zendesk.com. For example, ibm.zendesk.com.

3. Log in to your Zendesk subdomain.

4. Open the Zendesk Dashboard.

5. Click the Products icon (four blocks) in the header, and then select the Chat icon.

6. Click your profile, and then select Check Connection.

   

7. Keep this screen open for the Connect Zendesk to your assistant step.

   

You also need to decide whether to enable security for Zendesk after setup. More information at Securing the transfer to Zendesk.

Setting up the Zendesk service desk connection

In your watsonx Assistant installation:

1. Go to the Integrations page by clicking the integrations icon () in the left menu. For more information, see Integrating the web chat with your website.

2. Click Web chat and then click Open.

3. Select an environment, and click Confirm.

4. Go to the Live agent tab.

5. Click Zendesk.

Securing the transfer to Zendesk

You must collect the name and email address of each user if enabling security in Zendesk. This information must be passed to the web chat so it can be provided to Zendesk when the conversation is transferred.

When you add security to your Zendesk integration, you ensure that the visitors you are helping are legitimate customers. Enabling visitor authentication also enables support for cross-domain traffic and cross-browser identification. For more information, see the Enabling authenticated visitors in Zendesk.

Before you can secure the Zendesk connection, complete the following required tasks:

1. Secure the web chat. For more information, see Securing the web chat.

2. Encrypt sensitive information that you pass to the web chat.

   When you enable security in Zendesk, you must provide the name and email address of the current user with each request. Configure the web chat to pass this information in the payload.

   Specify the information by using the following syntax. Use the exact names (name and email) for the two name and value pairs.

   {
   user_payload : {  
            name: '#{customerName}',
            email: '#{customerEmail}'
     }
   }     
   

   For more information, see Encrypting sensitive data in web chat.

   Zendesk also expects iat and external_id name and value pairs. However, you need not provide this information. IBM automatically provides a JWT that contains these values.

   For example:

   const userPayload = {
    "name" : "Cade Jones",
    "email" : "cade@example.com",
   }
   

   // Sample NodeJS code on your server.
   const jwt = require('jsonwebtoken');
   const RSA = require('node-rsa');
   
   const rsaKey = new RSA(process.env.PUBLIC_IBM_RSA_KEY);
   
   /**
   * Returns a signed JWT. Optionally, adds an encrypted user_payload in stringified JSON.
   */
   function mockLogin(userID, userPayload) {
       const payload = {
         sub: userID, // Required
         iss: 'www.ibm.com', // Required
         acr: 'loa1' // Required
         // A short-lived exp claim is automatically added by the jsonwebtoken library.
       };
       if (userPayload) {
           // If there is a user payload, it is encrypted in base64 format using the IBM public key.
           payload.user_payload = rsaKey.encrypt(userPayload, 'base64');
       }
       const token = jwt.sign(payload, process.env.YOUR_PRIVATE_RSA_KEY, { algorithm: 'RS256', expiresIn: '10000ms' });
       return token;
       }
   

3. From the Zendesk application, enable visitor authentication.

   • From the Chat dashboard navigation pane, expand Settings, and then click Widget.
   • Open the Widget security tab.
   • In the Visitor Authentication section, click the Generate button.

   For more information, see Enabling authenticated visitors in the Chat widget. You do not need to follow the steps to create a JWT. The Assistant service generates a JSON Web Token for you.

4. Copy the shared secret from Zendesk.

To secure the Zendesk connection, complete the following steps:

1. In the Authenticate users section, set the switch to On.

2. Paste the secret that you copied from the Zendesk setup page into the Zendesk shared secret field.

3. Decide whether to allow unidentified users to access Zendesk.

   The web chat integration allows anonymous users to initiate chats. However, as soon as you enable visitor authentication, Zendesk requires that the name and email of each user be provided. If you try to connect without passing the required information, a connection is refused.

   If you want to allow anonymous users to connect to Zendesk, you can provide fictitious name and email data. Write a function to populate the two fields with fictitious name and email values.

   For example, your function must check whether you know the name and email of the current user, and if not, add canned values for them:

   const userPayload = {
    "name" : "Jane Doe1",
    "email" : "jdoe1@example.com",
   }
   

   After you write a function to ensure that name and email values are always provided, set the Authenticate anonymous user chat transfers switch to On.

For security reasons, the secret authentication fields are removed from view after initial setup.

Adding transfer support to your actions

Update an action to make sure it understands when users request to speak to a person, and can transfer the conversation properly.