Integrating with Zendesk

Before you begin

1. You must have a Zendesk account. If not, create one.

   A Zendesk Chat Enterprise plan is required.

2. Decide whether you want to enable security.

   If you choose to enable security in Zendesk, you must collect the name and email address of each user. This information must be passed to the web chat so it can be provided to Zendesk when the conversation is transferred.

Setting up the Zendesk service desk connection

To set up a Zendesk service desk integration, complete the following steps:

1. Create a web chat integration. For more information, see Integrating the web chat with your website.

2. From the web chat integration page in Watson Assistant, set the Allow transfers to live agents switch to On, and then choose Zendesk as the service desk type, and then click Next.

3. Add the account key for your Zendesk account, and then click Next.

   To get the account key for your Zendesk account, follow these steps:

   • Log in to your Zendesk subdomain.

   • Open the Zendesk Chat Dashboard.

     From the Zendesk Support dashboard, you can click the Zendesk Products icon in the header, and then click the Chat icon.

     

   • Click your profile, and then click Check Connection.

     

   • Copy the account key value.

     

   • Return to the setup page in Watson Assistant, and then paste the key into the field.

4. Install the Watson Assistant private application in your Zendesk Chat subdomain.

   When you create a Zendesk Chat account, you specify a subdomain. Afterward, your Zendesk console is available from a URL with the syntax: <subdomain>.zendesk.com. For example, ibm.zendesk.com.

   IBM provides an application that you can install in your Zendesk Chat domain. When a customer asks to speak to a person, your assistant will share a chat summary for the transferred conversation with the Zendesk agent by using this private app.

   • Download the Watson Assistant Zendesk application from the Zendesk Chat setup page in Watson Assistant.

     On Safari, the application files are extracted from the ZIP file into a folder. To keep the file archived as a .zip file, so you can upload it later, edit the Safari preferences. Clear the Open safe files after downloading checkbox.

   • Log in to Zendesk with a user ID that has administrative privileges.

   • Install the Watson Assistant Zendesk app to your Zendesk Chat subdomain as a new private app.

     • First, make sure the Zendesk Agent Workspace is not enabled for your account: From the Zendesk navigation pane, go to Settings, and then click Agents. Deselect the Enable the Zendesk Agent Workspace checkbox.
     • Then download the app. From the Chat dashboard navigation pane, expand Settings, and then click Account.
     • Open the App tab.
     • Click Upload private app, and then browse for the application file that you downloaded earlier.

     

     For more information, see Uploading and installing a private app in Zendesk Chat.

5. Click Save and exit to finish setting up the connection to the Zendesk Chat service desk.

When you test the service desk integration, make sure there is at least one agent with Online status. Agent status is set to Invisible unless it is explicitly changed.

Watch a 4-minute video that provides an overview of setting up a connection to a Zendesk service desk:

The product user interface is slightly different from the interface that is shown in the video. However, the main steps are the same.

Securing the transfer to Zendesk

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 Zendesk documentation.

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 Passing sensitive data.

   Zendesk also expects iat and external_id name and value pairs. However, there's no need for you to 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, the connection will be 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 writing a function that ensures that name and email values are always provided, set the Authenticate anonymous user chat transfers switch to On.

Adding transfer support to your dialog

Update your dialog to make sure it understands when users request to speak to a person, and can transfer the conversation properly. For more information, see Adding chat transfer support.

Adding routing logic for transfers

When you enable transfers to the Zendesk service desk, no routing preferences are specified. The conversation is sent to any available agent. However, there might be times when you want to route a customer to a specific Zendesk department. For example, your dialog might have a root dialog node that conditions on a #close_account intent. For that branch of the conversation only, you want to transfer customers to agents in the Sales department who are authorized to offer incentives as a way to retain customers. You can direct transfers to specific departments by adding routing logic to your dialog.

You can specify alternate routing preferences based on:

• browser information
• the current topic of conversation