Tip: If you haven't added a live chat button to your Helprace portal yet, now is a good time to do this. This allows customers to start a chat with you right from your Helprace portal.

Go to your live chat settings and and specify the email address for sending offline chat messages.

These settings may vary according to chat software. If your chat provider has a built-in ticketing system, these settings may be quite difficult to find :).

Here's how to set up forwarding in certain chat providers:

Tawk.to

Go to Settings > Mail Notifications.

Here you can add emails where chat transcripts, offline form and missed chat notifications will be sent. Insert your support email address here (e.g. go to Settings > Mailboxes in Helprace to see your list of addresses).

LiveChat

Go to Settings > Installation > Email and click on the 'Forward messages from visitors' at the bottom.

Specify emails where offline form and missed chat notifications will be sent. Insert your support email address here (e.g. go to Settings > Mailboxes in Helprace to see the list of your addresses).

Go to Chat Settings > Archives Forwarding and specify an email for chat transcripts.

Webhooks can be triggered when users, tickets, community topics or KB articles are created or updated.

Getting started

You can view, add, update, and remove webhooks via API. For convenience you can use our API docs page, which allows you to call API endpoints (e.g. Create Hook) without writing a single line of code.

Turn on API on the Settings > INTEGRATIONS > API page in your admin panel.

Generate an API key on that page.

Go to the WebHooks > Create Hook page in API docs.

Login to API docs by providing your account name and separately your email with the API key in the following format:

your@email.com/api_key:your_generated_api_key

Click -> button to login.

Click on BODY SAMPLE on the left and then click on the JSON sample to paste it into the request body.

Modify the code as you see fit. For instance you can specify a desired event (or an array of ["multiple", "events"]) or change the callback_url.

Go to the WebHooks > Description page to learn more about using Webhooks in Helprace.

Try the Webhook Tester. It's a 3rd party site that allows you to test your webhook events without writing an actual webhook handler. You can copy a unique URL from that site and use it as a callback_url in your webhooks.

The example below shows a fragment of a ticket with a user sidebar on the right. The sidebar contains a sample "hugeCommerce" app, which pulled data from a shopping cart on this customer. 

Two kinds of apps

There are two kinds of apps:

1. Static App - can be setup in minutes, but has limited functionality. Useful for simple quick integrations.
2. Dynamic App - requires a bit of programming and unleashes full potential of integrating your Helprace with your internal or 3rd party system.

Static App

You can setup a Static App to add some basic HTML in the user sidebar. It will appear in every ticket and every user page in the admin panel.

Static App supports placeholders. They will be replaced by actual values, like customer email or ticket subject, when user sidebar is loaded. See the full placeholder list in the placeholders reference.

Here is an example of a Static App.

Find customer on Facebook

App code looks like this:

<a href="https://www.facebook.com/search/top/?q={$ticket.requester.email}" target="_blank">Find customer on Facebook</a>

When you click this link, it will take you to Facebook and search for any pages linked with the ticket requester's email address. If the search is successful, you'll see the customer's Facebook profile.

Link to conversation in user portal

<a href="{$ticket.user_url}" target="_blank">{$ticket.user_url}</a>

Dynamic App

Helprace makes an HTTP POST request to the endpoint URL you've specified in the app settings when a ticket or user page is opened in the admin panel.

The POST body contains a JSON encoded details. If a ticket page has been opened, JSON will include ticket details:

{
   "context":"ticket",
   "ticket":{
      "id":3687,
      ...
   }
}

If called from a user page, JSON will include user details. Note that the "context" also is different.

{
   "context":"user",
   "user":{
      "id":31,
      ...
   }
}

By checking the context you can display (or not display) different data on ticket and user profile pages.

Helprace expects response with a valid JSON containing "data" and optional "header".

{"data":"Body","header":"App header (optional)"}

By default the app title on the sidebar shows the app name you provided in the app settings. If "header" is included in the response, it will replace the app name in the app title. The header supports the same HTML formatting as the body, enabling you to show a quick summary even when app panel is collapsed.

"data" should contain your HTML. It will be sanitized and inserted in the user sidebar. Check the Style Guide for a list of allowed tags and attributes.

Please make sure your JSON response is valid and properly escaped.

If the endpoint returns an empty response or an error, the app won't render in the sidebar (unless Debug Mode is On).

Security

Helprace generates a signature using the secret key you set in the app settings. The signature is included in the request headers as X-HELPRACE-SIGNATURE. To verify if the request came from Helprace, compute the SHA256 HMAC hash of the request body and compare it to the X-HELPRACE-SIGNATURE. If the computed signatures match, you can be sure the request was sent from Helprace. Otherwise, we recommend discarding the request. Recommended length of a secret is 40 characters.

This is how you can generate SHA256 HMAC hash in PHP:

hash_hmac('sha256', $json_payload, secret);

Debug mode

Turn on the "Debug Mode" option in the app settings to test your app. Debug mode allows you to call a non-HTTPS URL and app panel on the sidebar will render even if no response is received.

Clicking "Open App Debugger" will open a debugger in a new tab, where you can test your app with a different endpoint URL or request body.

Layout and design

Helprace includes a bunch of CSS classes to give your app a nice look. The "style" attribute is also allowed, so you can use your custom inline styles too. Check the Style Guide for a full reference, formatting examples and a list of allowed tags and attributes.

Enabling Single Sign On allows your Wordpress users to get logged in to your Helprace portal automatically when they login to your Wordpress site.

This step-by-step guide will help you with the installation and configuration process.

Installing the plugin

Automatic installation

Automatic installation is the easiest option as WordPress handles the file transfers itself and you don't need to leave your web browser. To do an automatic install of the Helprace Feedback Tab, log in to your WordPress dashboard, navigate to the Plugins menu and click Add New.

In the search field type "Helprace Feedback Tab & SSO plugin" and click Search Plugins. Once you've found our Helprace Feedback Tab plugin you can install it by simply clicking "Install Now". Activate the plugin and read on "Configuring the feedback tab" section below.

Manual installation

1. Download Helprace Feedback Tab & SSO plugin to your desktop
2. If downloaded as a zip archive, extract the Plugin folder to your desktop
3. Upload the plugin folder to the `wp-content/plugins` folder in your WordPress directory online
4. Activate the plugin through the 'Plugins' screen in WordPress
5. Enable and configure your feedback widget tab as described below

Configuring the feedback tab

1. If you do not have a Helprace account yet, sign up for a free trial here
2. Open your Wordpress admin panel and go to Helprace > Feedback Tab in the main menu to configure the plugin
3. Enable the plugin and specify the subdomain of your Helprace account (please, no alias here)
4. Select a desired type of integration: 'Tab' to show a feedback tab on all site pages automatically, or 'Own Link' to call the feedback widget when user clicks your custom link or button
5. If you selected 'Tab' for integration type, you can customize its look & feel and behavior: text on the tab, background and text color, etc.
6. If you selected 'Own Link', copy the sample code to a desired place in your Wordpress templates. Feel free to customize it as you like, you just need to preserve the JavaScript function call that opens the widget
7. Save the plugin settings

Setting Up Single Sign On (SSO)

1. Open your Wordpress admin panel and go to Helprace > SSO Auth in the main menu to configure the plugin
2. Check 'Single Sign-On (SSO)'. Click 'Save'
3. Specify your Helprace subdomain.
4. Go to your Helprace admin panel > Settings > SECURITY > Authentication
5. Enable 'Single Sign-On (SSO)'
6. Copy the 'Key' over to Wordpress as 'Security Key'
7. Copy 'Remote Login URL' and 'Remote Logout URL' over from Wordpress to Helprace
8. Click 'Save Changes' in plugin SSO settings

Just copy this HTML code to a desired place in your website templates and replace "http://acme.helprace.com" with the URL of your user portal:

<form action="http://acme.helprace.com/search" method="GET">
   <input name="q" value="">
   <input type="submit" value="Search">
</form>

User can type their query to the search field and press Enter or click the "Search" button. This will open the search results page in your user portal.

However, if all authorization options, except SSO, are disabled and Anonymous Access is not allowed, Helprace doesn’t show a login prompt when an unauthenticated user visits the portal. Instead, it redirects the user to the remote login URL in the same window. This is considered best behavior for a smooth user experience.

There is one exception to this. When you’re using the Feedback Widget and the following is true:

• Anonymous Access is disabled
• Helprace Login is disabled
• Social Authentication is disabled
• Single Sign-On is enabled
• Your authentication provider returns at least one of these headers:
  • X-Frame-Options: SAMEORIGIN
  • X-Frame-Options: DENY

In this case, Helprace would normally have to redirect the user to the remote login URL once they launch the Feedback Widget. If your authentication provider blocks its login screen from opening in an iframe, users won't see the login screen. They'll most likely see a white screen within the widget. 

In this case you need to force the remote login URL to open in a pop-up window. Once the user logs in, the pop-up is closed automatically and the user appears logged in in the Feedback Widget.

Please note that if you’re not using the Feedback Widget, it's recommended you keep this setting off, so that the user logs in without seeing any pop-ups.

If you have more than one login option enabled or Anonymous Access is allowed, this setting is irrelevant. It won’t change the behavior, as the remote login URL will be opened in a pop-up every time. That's why this setting is hidden in this case.

To start using the API you need to turn the API.

Go to the  Settings > INTEGRATIONS > API page and check Turn API on.

Check the Helprace API Documentation page for a complete API reference. It also allows you to try different API requests without writing a single line of code.

Single Sign-On can be used in conjunction with other authentications mechanisms, such as social authentication (via Facebook, Twitter, and Google) and native Helprace login.

Helprace Single Sign-On is based on JWT (JSON Web Token).

JWT code examples

JWT implementation is straight forward and there are plenty of libraries for any stack. We provide code examples here:

https://github.com/Helprace/helprace-jwt-sso-examples

If you implement JWT in any other stack, we would be happy to feature it there as well. Please comment on this article to let us know what you have implemented.

The Single Sign-On authentication process

Once you enable Single Sign-On, a new button with a lock icon appears on the login screen.

If you disable the native Helprace login, social login options and anonymous access (found on Settings > SECURITY > Authentication page), users will be redirected to the SSO remote login URL and logged in immediately when they come to your Helprace portal.

When users clicks this button, they are routed to a remote login URL, which is a login page in your system (external to your Helprace portal).

Here are the Single Sign-On (SSO) authentication process instructions (when SSO is the only authentication option):

1. An unauthenticated user navigates to your Helprace portal page (e.g. https://mycompany.helprace.com).
2. The user is redirected to the Single Sign-On script in your system.
3. A script on your side authenticates the customer using your proprietary login process.
4. Your script builds a JWT request that contains the relevant user data.
5. You redirect the customer to the Helprace endpoint at https://auth.helprace.com/jwt/mycompany?jwt= with the JWT payload.
6. Helprace decodes the user details from the JWT payload and then grants the user a session.

As you can see, this process relies on browser redirects and passing signed messages using JWT. The redirects happen entirely in the browser and there is no direct connection between Helprace and your systems, so you can keep your authentication scripts safely behind your corporate firewall.

Configuring your JWT implementation

To perform SSO for a user, you need to send several required attributes to Helprace as a base64-encoded hash. In addition to the required attributes you can specify additional user details. These details will be updated in the Helprace user profile.

Specify HS256 as the encryption algorithm in the header of your JWT payload (it is often used by default).

{
  "typ":"JWT",
  "alg":"HS256"
}

Redirect the user with the JWT payload to the following Helprace endpoint:

https://auth.helprace.com/jwt/acme?jwt={payload}

Note to use the 'https' protocol and replace 'acme' with your Helprace subdomain (domain alias is not allowed here).

Here is the list of supported attributes.

If a user's email has been changed and they log in via SSO with the same external_id, the new email will be added to the user's account. The previous email will also be preserved.

Enabling JWT Single Sign-On in your Helprace

In order to start using JWT Single Sign-On you need to enable it in your Helprace admin panel.

1. Go the Settings > SECURITY > Authentication page.
2. Check the "Single Sign-On (SSO)" option.
3. Enter the Remote Login URL. This is where your user will be redirected when they attempt to login to your Helprace via SSO.
4. Enter the Remote Logout URL. This is where Helprace will return your users to after they log out.
5. Copy the Key to your SSO script.

The return_to URL for login

Typically, users would expect to return to a page they were on previously while logged in via Single Sign-On. There are two possible cases to this depending on where they start the session:

User lands on a Helprace portal page

In this case users are redirected to your Single Sign-On script (set in Remote Login URL) and then back to Helprace. Helprace returns users to the page they were on before logging in. This happens automatically and doesn't require any setup on your part. If a user creates a knowledge base article and clicks "publish" while being unauthenticated, the post will be published immediately after the user gets back on Helprace after successful SSO authentication.

User lands on a page of your website or application

You can authenticate a user through redirecting them to Helprace and back to your app. Another options is to make use of so-called "Silent Authentication" by passing the URL with JWT payload to the src parameter of <iframe> or <img> tag and thus authenticating the user on the background.

Redirection

Your SSO script redirects users to your Helprace portal with JWT payload and return_to URL, which is normally the page within your website/application that users were on before they have been redirected to Helprace. Helprace will redirect users to the return_to URL after successful authentication.

This can be enabled by adding return_to GET parameter to the URL with the JWT payload:

https://auth.helprace.com/jwt/acme?jwt={payload}&return_to=https://acme.com/page-to-show-after-login

Where "https://acme.com/page-to-show-after-login" is the URL you would like to return the user to.

Silent authentication

Iframe

Display a 1×1px <iframe> on your SSO script page. Use the same URL with payload in "src" parameter of the image. There is no need to provide return_to in this case.

<iframe src="https://auth.helprace.com/jwt/acme?jwt={payload}" width="1" height="1" style="border: none;"></iframe>

Pixel

Display a 1×1px <image> on your SSO script page. Use the same URL with payload in "src" parameter of the image. There is no need to provide return_to in this case.

<img src="https://auth.helprace.com/jwt/acme?jwt={payload}" width="1" height="1" />

Authentication via an image is supported in Firefox, Safari and Chrome browsers, but not supported in IE and EDGE.

The return_to URL for logout

Just like with the login option, users would expect to land on the same page they were on before logging out. It might also be a specific page set by you. There are four possible cases to this depending on where user logs out first and if the Remote Logout URL setting is present:

User clicks Logout while being on a Helprace portal page

If Remote Logout URL is set

The user will be redirected to that URL after logging out from Helprace. It will also send a return_to parameter with the URL of the page the user were on before they clicked Logout:

https://acme.com/logout?return_to=https://acme.helprace.com/i4-some-kb-article-for-example

This allows you to configure your website or application to redirect the user back to that Helprace page.

If Remote Logout URL is NOT set

The user will be logged out from Helprace and stay on the Helprace page he were on before clicking Logout. 

User clicks Logout in your website or application

To log user out from Helprace as well, your website or application needs to redirect the user to the Helprace logout page:

https://acme.helprace.com/auth/logout

You can tell Helprace to redirect user back to your site or application after it logs him out. For that you need to pass return_to URL to Helprace:

https://acme.helprace.com/auth/logout?return_to=https://acme.com/page-to-show-after-login

What happens next depends on the Remote Logout URL setting.

If Remote Logout URL is set

After logging the user out, Helprace will redirect the user to the Remote Logout URL and pass your return_to URL as a parameter. E.g.:

https://acme.com/logout?return_to=https://acme.com/page-to-show-after-login

Your website or application needs to redirect the user to the return_to URL that it receives from Helprace.

If Remote Logout URL is NOT set

After logging the user out, Helprace will redirect the user to the return_to URL. E.g.:

https://acme.com/some_page

SSO log and troubleshooting

SSO requests and server responses are displayed on the Settings > LOGS > Single Sign-On (SSO) Log page

Preventing repetitive authorization requests

When implementing SSO on your end, please make sure to prevent unnecessary repetitive authorization requests to Helprace.

For example, when you redirect user with JWT payload to Helprace and they are successfully authenticated, you should keep a record of this in your app. Check that record next time before sending user to Helprace for authentication. If the record says that the user is already logged in, do not redirect them to Helprace.

This record should be reset when user navigates to the Remote Logout URL page.

Authentication settings

You can find multiple authentication options on the Settings > SECURITY > Authentication page. Different combinations of these settings allow you to create your own custom login setup.

SSO for all agents and users

Disable all options, with the exception of "Single Sign-On (SSO)". When an unauthenticated user or agent opens your Helprace page they will be immediately logged in via SSO.

By leaving "Anonymous Access" turned on, users and agents would need to click the Login button to authenticate. However, they can browse the user portal anonymously without logging in.

SSO for customers and native Helprace logins for agents

Same settings as with the previous scenario. Agents can login via direct login URL with their native Helprace username and password.

http://account.helprace.com/backup-login

"account" must be replaced with your account name.

SSO for agents and native Helprace login or social authentication for users

Turn on "Single Sign-On (SSO)" option and at least one of the following two options: "Helprace Login", "Social authentication".

"Anonymous Access" could be turned on or off according to your preferences.

Your customers can login using their Helprace passwords or via social login.

Manual user control

Disable "Allow new users registration", "Social Authentication" and "Single Sign-On (SSO)" options. Invite or import users with desired permissions manually from the admin panel "People" page.

You may want to disable "Anonymous Access" which blocks your user portal to users you didn't invite beforehand.

1. Sign in to your Analytics account, and go to the admin page.
2. Select an account from the drop-down in the Account column.
3. Select a property from the drop-down in the Property column.
   
   
4. Click Tracking Info.
   
   
   
   The tracking ID is a string like UA-12345678-1. The first set of numbers (12345678, in the example) refers to your account number, and the second set (01, in the example) refers to the specific property number associated with the account. The tracking ID is in large font on the Tracking Info page.
5. Copy your tracking ID to the Settings > Google Analytics page in Helprace Admin Panel and turn on the "Enable Google Analytics" option.
   
   
6. Click Save.