CrankWheel API Documentation

Welcome to CrankWheel’s API documentation. We have three APIs that you can use:

  1. Our RESTful API, for retrieving usage information.
  2. Our JavaScript API for Instant Demos, where you can access advanced functionality of Instant Demos.
  3. Our URL-based email campaign API.

RESTful API

Our RESTful API is available to all customers, just go to the API tab in our self-service dashboard to create an API key.

We use a system called Postman to document our RESTful API, as it lets our customers easily test the API without writing any code.

Access the documentation here.

Note that for many purposes, you can use our Zapier integration to take new demo request or screen sharing session information and use it to trigger actions on other systems. For example, you can use Zapier to get lead capture information into your CRM. The Zapier integration is available on all plans, and you can enable it via the API tab on your self-service dashboard.

Also note that on our enterprise plan we offer direct Salesforce integration, and we are open to adding direct integrations for other CRM systems. Contact [email protected] if you would like to discuss this.

JavaScript API

Our JavaScript API may be used on any page where you have embedded your Instant Demos JavaScript snippet. To retrieve this snippet, log in to the CrankWheel self-service dashboard as an administrator (sign up first if needed), then visit the Instant Demos tab of the dashboard and retrieve the snippet. You may need to enable Instant Demos before seeing the snippet. Contact [email protected] if you need any asssistance with this process.

Note that if you installed your CrankWheel JavaScript snippet before September 25th 2017, your snippet may be missing some of the functionality described below. You can always switch out your existing snippet for the latest snippet, which you can retrieve as explained above.

The JavaScript API is best explained by example, please see the code examples and comments below.

Launching the Instant Demos lead capture

Normally, you would attach the Instant Demos lead capture to any button or clickable element by either setting the CSS style crankwheel-com-showu-launch-button on the element, or if it has a href attribute, setting the href to the URL #crankwheel-com-showu-launch-button or any URL that ends with this hash value, such as https://meeting.is/ss/showu/YOURCOMPANYSHORTNAME#crankwheel-com-showu-launch-button

Another way to show the Instant Demos lead capture dialog is programmatically:

// Launch the Instant Demos lead capture (note: you should wait until after the
// document is fully loaded to do this).
showu.launch();

Responding to Instant Demos events

There are several events sent by Instant Demos at the moment:

  1. open happens when the lead capture dialog opens up

  2. requestDemo is triggered when your prospect submits their phone number

  3. submitInfo happens each time the prospect submits an answer to an optional question (or clicks Next without entering any information) and contains an additional parameter with the ID (as per the Instant Demos question editor) and value of the question, with the value an empty string if the prospect did not fill in any information.

  4. submitLast happens once the prospect has clicked ‘Next’ on all optional questions and sees the screen where they are given an overview of their submitted details.

  5. agentFound happens when an agent has clicked “Handle request” for this demo request.

  6. callUnderway happens when the handling agent has clicked “Call confirmed” for this demo request.

  7. noAnswer happens if the handling agent clicks “No answer” for this demo request, to indicate that they tried to call but did not get through to the prospect.

  8. screenshareStarting happens if the handling agent starts sharing their screen to the prospect while the prospect is still on the web page where they initiated the demo request. Note that this is sent right before the browser navigates to a different page, so you need to take action immediately within the event handler (e.g. storing an item in local storage, or doing so indirectly by logging an event via Google Analytics) as there will likely not be time to make any network requests or perform any deferred processing.

Note that if a prospect decides to edit any of their submitted information, or clicks back to go back to a previous question, you may see submitInfo arriving in a different order than you expected, and it’s possible to receive submitLast more than once since the prospect may arrive at that screen and click the edit button to go through all the questions again.

Here is a simple example of listening to these events:

showu.onEvent('open', function () {
    console.log("instant demo opened");
});

showu.onEvent('requestDemo', function () {
    console.log("demo requested");
});

showu.onEvent('submitInfo', function (params) {
    console.log("optional info submitted, ID=" + params.id + ", value=" + params.value);
});

showu.onEvent('submitLast', function () {
    console.log("all info fields submitted");
});

showu.onEvent('agentFound', function () {
    console.log("agent has committed to handling");
});

showu.onEvent('callUnderway', function () {
    console.log("phone call has started")
});

showu.onEvent('noAnswer', function () {
    console.log("agent indicated there was no answer");
});

showu.onEvent('screenshareStarting', function () {
    console.log("screen share starting");
});

The JavaScript events documented above can, for example, be used to integrate events from Instant Demos with usage analytics systems. We have a quick guide on how to accomplish this for Google Analytics.

Knowing the agent capacity

CrankWheel automatically determines how many agents are available based on whether they have recently been active on their computer, and whether they are already doing a screen share using CrankWheel. It then determines what the service capacity of your sales team is: full_capacity (50% or more of your team seems to be available), half_capacity (less than half your team seems to be available) or no_capacity (nobody is available). You might wish to use these values, for example to change the text on a button to reflect the expectation you want to set, e.g. make it say “Get an Instant Demo” when there are agents available, and “Book a Demo” when there aren’t. In its lead capture dialog, CrankWheel uses the service capacity to determine which set of messaging and which behavior to use, and you can configure messaging based on behavior in the Instant Demos configuration, which you can access through the self-service dashboard (click Instant Demos, then the button to Configure).

// This will log on of "full_capacity", "half_capacity" or "no_capacity"
showu.getCapacity(function (cap) { console.log(cap); });

Pre-populating known fields

If you already know the answer to one of the questions you normally ask your prospects during lead capture, for example if they are already logged into your web page so you know their name and email, you can pass this information along to the Instant Demos lead capture dialog so that it doesn’t ask the questions matching the information.

The key for each item is identical to the ID parameter that you will see when you edit the lead capture questions in the Instant Demos interactive editor (access it through the self-service dashboard).

Call this API any time before the lead capture dialog is opened to prepopulate.

showu.populateFields({
    name: 'Joi',
    email: '[email protected]'
});

You may also pre-populate arbitrary information into the lead capture to have it transferred through the lead capture process so that it ends up in emails with lead capture information, or in your CRM or via our API. For example if this prospect has created an account in your system you may want to transfer the account ID along with the other information you already know:

showu.populateFields({
    email: '[email protected]',
    accountid: '9114354'
});

On the other end, the account ID in the example above would show up as prospect-accountid in the prospect information that you can retrieve via the RESTful API, or via Zapier.

Note that standard UTM parameters typically used to track marketing efforts (utm_source, utm_medium and so forth) are automatically pre-populated as arbitrary information for any demo request.

Email campaign API

In email campaigns, you can link to a URL that looks like this to launch the Instant Demos lead capture when the link is clicked:

https://meeting.is/ss/showu/YOURCOMPANYSHORTNAME

Replace YOURCOMPANYSHORTNAME with the short name you chose for your company. You can see it by logging into the self-service dashboard as an administrator and going to Edit company, or if you open the main CrankWheel UI it is shown at the bottom of the UI.

If you wish to pre-populate fields, you may do so using query parameters matching the ID of the field. When you send an email, you typically know the prospects email address, and so will typically want to pre-populate it. Let’s also imagine you already know their name. Here’s how you would pre-populate that:

https://meeting.is/ss/showu/[email protected]&name=Joi

URL command API

If you need to cause the CrankWheel presenter UI to appear (as if the presenter had clicked the CrankWheel button), this can be done using a “magic” hash code that you can add to the URI of the currently-displayed web page, or by opening a fresh browser tab to a “magic” URL.

Magic hash

The former approach works well when you know CrankWheel is installed, or if you don’t want anything to happen when CrankWheel isn’t already installed.

Just set the following hash value on the location of your current page:

#crankwheelmagicshowui:main

This can be done in JavaScript as such:

// In case the hash was already set, clear it so that CrankWheel notices
// the new change.
if (location.hash == '#crankwheelmagicshowui:main') {
    location.hash = '#';
}
location.hash = '#crankwheelmagicshowui:main';

Magic URL

This simpler approach opens a web page that will cause the CrankWheel UI to show and then close the tab of the web page, or if CrankWheel is not already installed, it will show instructions for how to install it.

Simply open a new browser tab to this URL:

http://crankwheel.com/install/#crankwheelmagicshowui:mainandclose

Or, in HTML, using an anchor as follows:

<a href="http://crankwheel.com/install/#crankwheelmagicshowui:mainandclose" target="_blank">Launch CrankWheel</a>

Or, using JavaScript:

window.open('http://crankwheel.com/install/#crankwheelmagicshowui:mainandclose', '_blank');

Setting parameters

For either of the above types of URL commands, you can pass several parameters in URLs by using the :extraparams: syntax:

#crankwheelmagicshowui:main:extraparams:emailaddress=...&countrycode=...&phonenumber=...
http://crankwheel.com/install/#crankwheelmagicshowui:mainandclose:extraparams:emailaddress=...&countrycode=...&phonenumber=...

Each of the parameter fields should be URL-encoded. They are used to pre-populate the fields shown after you start screen sharing and want to send somebody a link. They are:

  • emailaddress: Your contact’s email address.
  • countrycode: The country code of your contact’s phone number. If you leave this unset, CrankWheel tries to determine your location in the world and use your country’s country code, by default.
  • phonenumber: Your contact’s phone number, not including country code.

You can set any or all of the fields when specifying :extraparams:.

Webhook API

We have a webhook API that sends a webhook for every event occurring during an Instant Demos lead capture and handling of the prospect via the Instant Demos mechanism. This API is currently experimental and subject to change. Contact [email protected] if you would like to explore use of the webhook API.