A Little API Magic Lets Your Users Request Remote Support from Any Site

It’s easy for remote customers to request help using the Bomgar support portal web page that’s hosted on the appliance; and with Bomgar Enterprise Edition you can host as many independently customized portal pages as you wish.  But it’s also possible to start a Bomgar support session from any web page, on any web server, anywhere.  All it takes is a little API call.  Let me show you some of the simple API calls that can be used to start sessions.  You may find these useful to incorporate on existing web pages to improve and streamline the support experience for your customers.

But first…
Before we can start playing with the API, we need to adjust security settings and privileges.  Since Bomgar is always focused on secure remote support it is important to note that access to the command API and reporting API can be limited through Bomgar Group Policies.  First, let’s enable the API itself.  Open the /login administrative interface and navigate to Management>Security.  Locate and select the “Enable XML API” checkbox.  This update takes effect immediately; so there’s no “Save” button to implement the change.
 
Immediately below the “Enable XML API” checkbox is another API-related attribute, “Allow HTTP Access to XML API.”  This attribute is disabled by default and I strongly suggest that you leave it disabled.  It is a best practice to always perform API calls using secure sockets HTTPS access rather than clear text transmission via HTTP.  While we won’t be sending credentials via the API calls covered in this note, it is still best to take advantage of SSL encryption.

Next, let’s adjust your privileges so you can fully experiment with all aspects of the Bomgar API.  While in the /login administrative interface select either Users & Security>Group Policies or Users & Security>User Accounts to set these privileges.  For security and administrative efficiency it’s best to set privileges via Bomgar Group Policies rather than User Accounts.

In any event, enable the “Allowed to use reporting API” and “Allowed to Use Command API” privileges.

Everything and More
All API examples presented in this post are based on the API Programmer's Guide 1.8.0 that’s available here: https://www.bomgar.com/docs/content/documents/bomgar-api-guide-1.8.0.pdf. The web-based API is enormously full-featured and contains methods for tightly integrating Bomgar with incident tracking and workstation management products.  Projects of that scale make use of the XML data files and the Bomgar outbound event triggers for client-server architectures.  For our purposes, we’re concerned with just the few pages devoted to session start.

Starting Sessions
Let’s begin with the simplest command that starts a session in the General Queue.  Such a command looks like this:

https://your.domain.com/api/start_session.ns?issue_menu=1

You can test these commands out by substituting your actual domain name for the your.domain.com place holder in the example above and then pasting the result into a browser address field.  Once you craft the final syntax of the API call, you will use it in the HTML code of the web page as a hyperlink probably associated with a graphic or icon of some sort.  Here’s an HTML example that hyperlinks a line of text:

<p><a href="https://your.domain.com/api/start_session.ns?issue_menu=1">Click here to start a remote support session.</a></p>

Imagine placing a link such as this at the end of a self-help tutorial on a Frequently Asked Questions web page.  If the customer’s issue is not resolved by following the self-help, they could immediately request assistance from a service technician without having to navigate away from the self-help page over to the Bomgar portal page.

Issue Submission
The above command simply pops the remote customer into the General Queue; but since in our imaginations they are perusing a self-help web page, that implies that they have a specific issue.  Wouldn’t it be nice if the API call would specify that issue and automatically route the incoming session request to the appropriate team?  Good news!  All it takes is one tiny addition to the API call.

https://your.domain.com/api/start_session.ns?issue_menu=1&id=4

In this example the id parameter at the end of the API call identifies an issue that’s associated with a team.  Teams and their issues are defined in the /login administrative interface under Configuration>Support Teams.  But here is a possible complication.  As you might be aware, issue submission on the Bomgar portal page optionally can be configured to identify available service technicians instead of team issues.  If that’s the case then the id parameter would identify a particular service technician.  Since using Issue Submission to identify service technicians is a relatively rare use case, I won’t cover that here.  However, if you’re interested in that implementation option it’s covered in the API Programmer's Guide.

Can you chat for moment?
So far our examples have involved downloading the Customer Client and starting a full remote support session.  But perhaps you’d like to initiate a Bomgar Click-to-Chat interaction before launching remote control.  The simple way to do that is to add a parameter to the above examples.  For instance, let’s add c2cjs=1 to our request to start a session in the general queue.  The resulting command looks like this:

A hyperlink such as this, whether directing the incoming text chat request to the general queue or to a specific team (perhaps one that’s enabled for Equilibrium?), could be very impressive to your remote customers.  Imagine placing Click-to-Chat hyperlinks and buttons on any of your corporate web pages where customer contact with a service technician could advance your business objectives.(Note that the API Programmer’s Guide details two methods for initiating Click-to-Chat connections and this is the second option listed. The first method provided uses a very short JavaScript program of just a few lines together with an onclick event to invoke the script.  You might look into this method if you’re going to make wide use of custom Click-to-Chat entry points.)

How about the other side?
The Bomgar API can be used to streamline service technician activities as well as making life easier for your remote customers.  Bomgar offers a client scripting API that can:
 
- Start a support session with a specific Jump Client
- Prompt service technicians to create session keys
- Start a vPro session with a specific remote computer
- Start the Bomgar Representative Console application

These are very powerful capabilities and I’ll provide just one example in order to show that power doesn’t always equal complexity.  Suppose your workstation management product has a web interface that lists all your computer assets and that you have installed Bomgar Jump Clients on some of these computers.  With just a little bit of scripting, you could add the ability for a service technician to launch a Bomgar support session directly from the workstation management interface.  How cool is that?
 
First let’s look at the API call and then examine how it works:

http://your.domain.com/api/client_script.ns?type=rep&operation=generate&action=start_pinned_client_session&search_string=Fedora15

The operative pieces of this call are the commands start_pinned_client and search_string.  The start_pinned_client portion is pretty self-explanatory; so let’s look at the other parameter.

The search_string identifies the target computer and this can specify a variety of criteria.  In my example above, the target is identified by hostname as it appears in a Representative Console list of Jump Clients.  Other criteria can be used, including the contents of the comment field, the public IP address, or the private IP address.  If the search_string matches more than one Jump Client, then the service technician receives a prompt to choose which target in order to complete the jump.  And if the service technician is not logged into their Bomgar Representative Console application, the console will be started and the technician will be prompted to log in.
 
Where do we go from here?
We’ve barely scratched the surface of all the activities that can be done with the Bomgar application programming interface.  The intent of this post is to stir your imaginations and foster new methods to streamline the support process while improving the efficiency of your service desk and offering improved service to your remote customers.  Much can be accomplished with even the simple commands covered above; and, if desired, the API can be leveraged with much more complex integrations to enable Bomgar to work with CRM products, incident tracking systems, call routing and management components, statistical tracking and reporting, as well as workstation management products such as Dell KACE.

Brian Page, Senior Solutions Engineer at Bomgar

Stay Up To Date

Get blog posts delivered directly to your inbox whenever we post! You may unsubscribe at any time.