Zendesk Setup

Zendesk Tickets Handover

Here you will learn how to set up a ticket handover to Zendesk.

Note: To perform all of the following steps you need to have administrator rights in both apps – Solvemate Web App and Zendesk.

1. Create the integration in Solvemate Web App

Log into the Solvemate Web App and configure the integration.

Go to Admin > Integrations and pick Zendesk API.

Web App Integration

2. Fill in integration details

Web App Integration

Add the Domain Name

Add the sub-domain of your companies Zendesk account to the field Domain Name in the Solvemate Web App.

Example in case of Solvemate

  • Solvemate’s Zendesk domain https://solvemate.zendesk.com/agent/admin,
  • copy the “solvemate” (without https:// and the dot,
  • paste it to the field Domain Name in the Solvemate Web App.

Add the email of the user account

Add the email of the admin user account at Zendesk.

Add the API Key

  • Log into Zendesk with the same email address as used above
  • Go into Settings > Channels > API
Zendesk token
  • Click on the ➕ to create a new token. Give this token the description Solvemate, and copy paste the API Token into Solvemate Web App field API Key.
Zendesk create token

3. Activate the integration in Solvemate Web App

Verify integration is active

Make sure the integration is activated in Admin > Integrations section.

Create Zendesk API integration component

Navigate to Workspace > Components choose Add new Component at the top left corner and pick “Zendesk Tickets” (or any other name you gave to the integration), enter title.

Web App Create component

Configure Zendesk API integration component

You can now open and edit the component - add and change fields required from the user, enable file uploads, set it as a fallback etc.

Note: Field key email with Field type mail (reply-to) is mandatory for the integration to function properly.

Component config

Zendesk Chat Handover

This guide will walk you through the process on how to set up a Zendesk Chat connection in the Solvemate Web App and how to use the Zendesk Chat in the Solvemate widget.

Note: To perform all of the following steps you need to have administrator rights in both apps – Solvemate Web App and Zendesk Chat dashboard.

To complete the setup you will need to login in the following accounts:

  • Solvemate Web App
  • Zendesk Support
  • Zendesk Chat Dashboard

Zendesk chat dashboard
To open Zendesk Chat Dashboard from Zendesk Support click on the Product Tray icon and choose Chat.

1. Create the integration in Solvemate Web App

Log into the Solvemate Web App and configure the integration.

Go to Admin > Integrations and pick Zendesk Chat.

Web App Integration

2. Fill in integration details

Web App Integration

Add the Domain Name

Add the sub-domain of your companies Zendesk account to the field Domain Name in the Solvemate Web App.

Example in case of Solvemate

  • Solvemate’s Zendesk domain https://solvemate.zendesk.com/agent/admin,
  • copy the “solvemate” (without https:// and the dot,
  • paste it to the field Domain Name in the Solvemate Web App.

Add Zendesk Chat Account Key

You get the Zendesk Chat Account key in the Zendesk Chat dashboard.

  • Click on the on the profile icon in the top right corner of the dashboard
  • Then click on Check connection - a modal window opens
Zendesk Chat Account key
  • Copy the value from the field Account Key
Zendesk Chat Account key 2
  • Paste the Account Key to the related field Account Key in the Solvemate Web App

Add Snippet Key

You get Snippey Key in the Zendesk Support dashboard.

  • Navigate to Settings -> Channels -> Widget -> Setup

  • Copy the value after key= ….

Zendesk Snippet Key
  • Paste this value into related field Snippet Key in the Solvemate Web App

Add API client

You can add new API Client from the Zendesk Chat dashboard.

  • First copy the Redirect URL from the Solvemate Web App and keep it in the clipboard
Redirect URL
  • In Zendesk Chat dashboard on the left hand menu navigate to Settings -> Account -> API & SDKs and click on Add API Client
Add API client
  • Fill sensible entries in Client name and Company fields. Paste the Redirect URL (from the Solvemate Web App) into Redirect URLs field and click Create API Client
Add API client
  • Copy the Client ID and paste into related field Client ID in the Solvemate Web App
Add API client

Save & Authorize

Last step is to authorize Solvemate to communicate with your companies Zendesk Chat instance.

  • click Save & Authorize in the Solvemate Web App -> you are forwarded to an authorization page hosted by Zendesk
  • click on Allow -> you get forwarded back to the Solvemate Web App

Congratulations! You now successfully set up the Zendesk Chat handover option for your Solvemate chatbot.

3. Activate the integration in Solvemate Web App

Verify integration is active

Make sure the integration is activated in Admin > Integrations section.

Create Zendesk Chat integration component

Navigate to Workspace > Components choose Add new Component at the top left corner and pick “Zendesk Chat” (or any other name you gave to the integration), enter title.

Configure Zendesk Chat integration component

You can now open and edit the component - change custom texts, set it as a fallback etc.

Component config

Zendesk Chat SDK

Solvemate offers the possibility to handover conversations to the Zendesk Live Chat. You can exactly configure in which cases you want to offer this possibility to your customers. You can find out out more about this feature on Handover Overview.

Technically, the Zendesk Widget will be loaded into the Solvemate Widget as soon as a handover is initiated. This allows to seamlessly integrate both interfaces, while providing all the Zendesk Chat functionalities that you may be using already.

The Solvemate Widget provides a wrapper around the Zendesk SDK. This means that you can use the same commands and callbacks as described in the Zendesk Widget Documentation but the Solvemate Widget SDK is in between.

Commands

Commands are passed to the Zendesk Widget with solvemateCli.zendeskChatExecuteCommand. For example:

zE('webWidget', 'setLocale', data<string>);

becomes

solvemateCli.zendeskChatExecuteCommand('setLocale', data<string>);

Callbacks

Event callbacks can be set via solvemateCli.zendeskChatAddCallback. For example:

zE('webWidget:on', 'chat:connected', function() {
    console.log('successfully connected to Zendesk Chat!');
});

becomes

solvemateCli.zendeskChatAddCallback('chat:connected', function() {
    console.log('successfully connected to Zendesk Chat!');
});

Binding

Commands and callbacks can be set before the Solvemate Widget has been fully loaded. After running the init script, commands can be added as callbacks. They will be applied as soon as the Solvemate Widget is fully initialised.

solvemate('callbacks', [
    function() {
      solvemateCli.zendeskChatExecuteCommand('setLocale', 'en');
    },
]);

Authenticated visitors

Solvemate Zendesk SDK supports Authenticated Visitors feature as described in Enabling authenticated visitors in the integrated Web Widget aritcle.

Preemptive

The configuration should allow to download jwt token before initialising Solvemate Widget.

fetch('JWT_TOKEN_ENDPOINT').then(function(res) {
  res.text().then(function(jwt) {
    // ... widget initisation
    
    solvemate('integrationConfiguration', { zendeskChat: { jwtToken: jwt } });
    
    // ... other callback functions
  });
});

Delayed

The configuration should allow to download jwt token on Zendesk Chat initialisation.


// ... widget initisation

// to delay rendering until jwt is received
solvemate('integrationConfiguration', { zendeskChat: { authenticate: false } });

solvemate('callbacks', [
  // ... other callbacks
  function () {
    solvemateCli.zendeskChatAuthenticate(function (handleJWTCallback, handleErrorCallback) {
      fetch('JWT_TOKEN_ENDPOINT', { method: 'POST', /* other data */ }).then(function(res) {
        res.text().then(function (jwt) {
          handleJWTCallback(jwt);
        });
      }).catch(function() {
        // to initialise zendesk chat without jwt
        handleErrorCallback();
      });
    });
  },
]);

Zendesk Google Analytics for Chat in the Web Widget

To send Zendesk chat events from within Solvemate Widget to Google Analytics or other analytics tools you can listen to all of the events listed using the userEvents JavaScript API.

You can add a callback that will send the events to your analytics tool.

Example of a Solvemate Widget integration that sends Zendesk Chat events to Google Analytics:

(function(s,o,l,v,e,m,a,t){t='solvemateConfig';s[e]=s[e]||function(x,y)
{(s[t]=s[t]||{})[x]=y;};a=o.createElement(l);a.async=1;a.src=v;o.body.appendChild(a);
})(window,document,'script','https://widget.solvemate.com/v2/init.js','solvemate');

solvemate('projectID', 'your_project_id');

solvemate('callbacks', [
    function () {
        solvemateCli.zendeskChatAddCallback('userEvent', function (event) {
            gtag('event', 'Zendesk chat from Solvemate', {
                'event_category': event.category,
                'event_label': event.properties,
                'event_action': event.action,
            });
        });
    },
]);