Integration, App Customisation and APIs
This guide details how you can customise your SimpleHelp apps or integrate them into your website and third party software.
A simple but effective form of branding is to embed the SimpleHelp app download buttons into your existing website. Once embedded the SimpleHelp components appear seamlessly alongside your existing images, text and other branding providing a fast, simple and highly effective way to give your customers a consistent support experience.
To embed the SimpleHelp customer client add the following to your web page:
Note: Make sure to replace 188.8.131.52 with the address or hostname of your server.
The embed script can be configured as follows:
- Required - The
srcline should contain the domain name or IP address of your SimpleHelp server. Replace
/technicianto embed technician download links.
Optional - The
configurationline specifies which download options are preferred. Options followed by a
*are preferred and highlighted. Valid options are:
online- the online standalone is a small executable that bundles the essential components required to start the application. Additional requirements on demand are downloaded when required. This is the recommended way to launch an application.
offline- the offline standalone is a larger executable that contains all essential and optional components. Here nothing is downloaded on demand.
Optional - Set
noto hide the application name.
Optional - Set
noto hide the image.
Example Basic Integrations
The following examples show a variety of common embed options:
Example 1 - Standard Download
A simple integration showing a custom logo and only the single online app download option.
Example 2 - Multiple Download
Another integration which provides the user with multiple launch options.
Example 3 - Minimal Download
A minimalist integration showing only the download button.
Web API Integrations
SimpleHelp v5.1 and later includes a comprehensive HTTP Web API. Easily connect to your SimpleHelp server and query it to perform the following tasks:
- See existing technician account details, create new accounts or remove existing accounts.
- Assign technicians to group, specify filters and perform general account management tasks.
- View the list of machines registering with the server.
- Collect hardware and monitoring information from a remote machine.
- View the list of historical sessions and collect details about each session.
See the HTTP web API documentation for more information.
Configuring App Downloads
SimpleHelp customer and technician downloads can be configured by passing in options via the download page URL or in the
src element of the embed script. Configuration options are included in the downloaded application permanently and will apply every time the application is run. This allows you to preconfigure settings that override the SimpleHelp defaults.
Passing in Configuration Parameters
Download options can be appended to the download link. For example, to set the width and height of the customer window to 500x500 pixels use the following page address:
The same parameters can be passed in with your web page embedding script as follows:
<script id = "jwEmbed" src = "http://184.108.40.206/customer/embed.js?width=500&height=500" … </script>
The following options are available for the customer, technician and access downloads.
|language||The language code of the application. SimpleHelp supports English (en), Dutch (nl), German (de), Portuguesse (pt), Swedish (sv), Italian (it), Spanish (es) and French (fr).|
|width||The width of the application window, in pixels.|
|height||The height of the application window, in pixels.|
Parameters for the Customer Application
The following options apply only to the remote support customer application.
|connectnow||Log customers directly into the waiting queue, skipping the disclaimer and details entry steps. For more information see the section Passing Customer Details into SimpleHelp below.|
|invite||Log the customer into the SimpleHelp server using a specific invitation code.|
|queuepassword||Log in using the specified queue password.|
|requestelevation||SimpleHelp, by default, requests the customer to elevate on Windows. Set this to no to skip this step.|
|filetransfer||Set this to no to disable file transfer.|
|chat||Set this to no to disable customer chat.|
|techniciangroup||Only allow technicians in the specified group to see and connect to this customer.|
|technician||Only allow technicians with matching usernames to see and connect to this customer. Specify one or more usernames as a comma-separated list, such as george,bob,frank|
|details_width||The width of the details window, in pixels.|
|details_height||The height of the details window, in pixels.|
|disclaimer_width||The width of the disclaimer window, in pixels.|
|disclaimer_height||The height of the disclaimer window, in pixels.|
Passing Customer Details into SimpleHelp
Prior to joining the waiting queue, customers are asked to accept a disclaimer and enter in their required details. It is possible to skip these steps by passing the customer's information into SimpleHelp. For example, if you wish to automatically add customer 'Bob' from company 'SimpleHelp' to the queue you can use the following:
To configure multiple aspects of the customer client simply chain multiple parameters together separating them with '&':
Connecting to a Specific Technician
Customers that join the waiting queue are visible to all technicians. If you wish to have customers be visible to specific technicians you can specify the technicians or technician groups on the customer link.
- Filtering By Technician Username - to filter by technician username you can specify a comma separated list on the connect link as follows:
http://220.127.116.11/customer?technician=<technician username>,<technician username>…
- Filtering By Technician Group - to filter by technician group you can specify the group on the connect link as follows:
Parameters for the Technician Application
The following options apply only to the technician application.
|technician||The technician username to use for automated login.|
|password||The technician password to use for automated login.|
|group||The technician group name to use for automated login.|
|machine||A URL encoded machine name to connect to. If specified, the session will launch and connect directly to this machine.|
Passing Technician Credentials into SimpleHelp
If you wish to automate the logging in of technicians you can pass their credentials on the technician login URL. For example, to log the technician Andy in technician group Administrators with password abcd1234 you can use the following link:
Including Parameters in POST Requests
SimpleHelp allows for the configuration of customer downloads by performing POST requests against the SimpleHelp server. If you wish to configure a download in this manner then you should not POST to the download choice pages:
Instead, POST options are only accepted for specific file downloads, such as:
Command Line Launch
SimpleHelp allows you to launch the technician session user interface from the command line. This is useful if you wish to integrate SimpleHelp with another application.
Technician Session Launching
The command line arguments to launch a Technician session are as follows:
Tech-windows32.exe JWVAPP SessionUI JW_launchapi=yes <other args>
where <other args> may be one or more of:
<server URL>- the URL of the SimpleHelp server to connect to (e.g.
<machine name>- the machine name or the machine ID to connect to.
<any data>- the machine to connect to, found by a filtering search. The filter will match all machine data looking for a match including IP address etc. To test your filter you can open the Technician Client and type the text into the Filter box in the access tab. Your text should match one machine only.
<language code>- used to force one language (e.g 'es' for Spanish).
<technician human readable name>
<screen | file | diagnostics>
NOTE: When using the JW_machine name (rather than the machine ID) the name MUST include the group separated by forward slashes. To get the full machine name to use you should open the tech client, select the machine in the Access tab and click the Get Direct Url' button below. The URL produced will have the full machine name URL encoded. You can then pass this through an online URL decoder to get the full machine name. An example full machine name might be:
US/Texas/Machine 1 [Windows x86]
When you pass this into the JW_machine parameter you should ensure you surround the entire argument with quotes:
"JW_machine=US/Texas/Machine 1 [Windows x86]"
NOTE: On macOS the command is open Technician.app --args and then these arguments. On other operating systems the command is just the executable and then these arguments.
The customer support client can also be launched and configured via the command line. To do this you should download the online or offline customer executable from your server, then to pass in any parameters, just prefix them with JW_, for example:
You can use any of the parameters mentioned earlier in the App Downloads section for the customer client in exactly the same way to configure whatever you wish.
NOTE: On macOS the command is open Customer.app --args and then these arguments. On other operating systems the command is just the executable and then these arguments.
NOTE: You may need to surround the arguments with double quotes " to make sure any spaces are preserved.
For more information on how to configure the remote access client for silent or preconfigured installation see this document.
Launching using a URL
If the SimpleHelp Technician application is already installed on a system it can be launched using a configurable URL. This allows for in depth integrations with third party software as SimpleHelp sessions can be started on-demand simply by invoking a URL, and without having to manually script the technician executable. SimpleHelp technician URLs take the form:
where arg=value can be any of the JW_ arguments specified above for command line launches. Remember that values need to be URL encoded. For example, to establish a session to a service called
George's Laptop, you can use a URL of the form:
Data Export and Logging
Advanced integrations of SimpleHelp often look to not only embed SimpleHelp components into a site, but also retrieve data from the SimpleHelp server. SimpleHelp includes a very powerful logging and data export framework that allows integrators to have SimpleHelp post event data to their integration point of choice. The configuration of the SimpleHelp server is covered in our Administrator Guide . A few of the things you can do with SimpleHelp include:
- Send emails to technicians, customers and administrators when sessions finish.
- Populate a database with customer information.
- Log failed technician log in attempts.
- Send email alerts when remote machines become available, or go offline.
- Log technician usage, customer activity and session details.