Building Custom Apps

The Custom App pulls data in real time from your internal systems into the Helprace user sidebar. The sidebar appears on the right on ticket and user profile pages.

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.