CrankWheel API Documentation

Welcome to CrankWheel’s API documentation. We have several APIs that you can use, the main ones being:

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

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 support@crankwheel.com 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 support@crankwheel.com 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:

open happens when the lead capture dialog opens up
requestDemo is triggered when your prospect submits their phone number
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.
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.
agentFound happens when an agent has clicked “Handle request” for this demo request.
callUnderway happens when the handling agent has clicked “Call confirmed” for this demo request.
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.
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: 'joi@crankwheel.com'
});

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: 'somebody@example.com',
    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/YOURCOMPANYSHORTNAME?email=joi@crankwheel.com&name=Joi

Requesting a specific agent

In most cases, you want incoming Instant Demos requests to go to all agents in the team that is configured to handle that particular Instant Demos widget. This way, you have a pool of people ready to jump on a call with the inbound prospect.

However, CrankWheel also has support for requesting a call through Instant Demos, that should only be handled by one particular agent. This can be appropriate for example if an account already has an account manager, and you are sending them an email with some account status information, and want them to be able to easily request a call from their account manager.

Requesting a specific agent is achieved by pre-populating a field named requested-agent-email that contains either the email address of the agent, or a Base64-encoded version of the agent’s email address.

This could be accomplished using the email campaign API or with any hard-coded URL. In these examples we assume you have set up a separate widget named “specificagentwidget” for these requests:

https://meeting.is/ss/showu/YOURCOMPANYSHORTNAME/specificagentwidget?requested-agent-email=exampleagent@yourcompany.com

or using the JavaScript API for pre-populating fields, such as

// The btoa() function accomplishes the Base64-encoding
showu.populateFields({
    requested-agent-email: btoa('exampleagent@yourcompany.com')
});
showu.launch('specificagentwidget');

When using this functionality, you will likely want to set up a separate Instant Demos widget, and configure a team to handle that widget, that includes all agents that you want to enable to receive specific-agent Instant Demos requests. There is a separate Instant Demos template you can use to start with a widget like that, named “Request a specific agent for a callback (English)”. If you create a URL or use JavaScript to trigger a specific-agent request, and the agent in question is not a member of the team for the widget, then all owners and administrators on your account will receive a warning for such requests (up to once per hour) to make sure they get handled correctly.

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 opening a fresh browser tab to a “magic” URL.

Magic URL

This simple 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

Using the URL command, you can pass several parameters in URLs by using the :extraparams: syntax:

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 support@crankwheel.com if you would like to explore use of the webhook API.

Embedding API

All parts of CrankWheel’s viewer experience can be embedded in an iframe. When this is done, there are a couple of postMessage events that the CrankWheel viewer interface will send to the parent frame during the screen sharing session, all demonstrated in this jsfiddle.

Browser tab sharing API

CrankWheel provides a couple of ways that web pages can interact with CrankWheel’s “browser tab” screen sharing mode by reading or writing attributes of the page’s DOM.

Cropping hints

For certain use cases, you may want to share only part of a web page that is shared using CrankWheel’s “browser tab” mode of sharing.

Web pages can provide specifications to CrankWheel of an amount of additional crop to apply along the left, right, top and bottom edges of the browser tab, specified in the same dimension as window.innerWidth and window.innerHeight use, effectively logical pixels.

Here’s how to do it:

Add the className crankwheel-extra-crop-data to an element on the page (CrankWheel will use the first it finds if there are multiple). The element should exist and have this class from DOM load or at least before browser tab sharing starts, and you should not remove the class from the element to add it to a different element during the lifetime of the document.
On that element, any or all of the following attributes can be added, each of which has an integer value: data-crankwheel-crop-top, data-crankwheel-crop-right, data-crankwheel-crop-bottom and data-crankwheel-crop-left.
The integer values of those data items are used to control cropping, from the top/right/bottom/left edges. The units of the values are the same as the units of window.innerWidth and window.innerHeight.
CrankWheel will monitor those data values for changes and update the cropping area when they are changed. Any value that is omitted is treated as if it had been set to 0, i.e. no cropping on that side.

Cropping applies to the current page only and will reset as soon as the page is navigated or a different browser tab is shared. Cropping is never applied when sharing full screen or application window. You can try out the cropping feature by visiting this page and screen sharing it using CrankWheel’s browser tab mode. You can also view that page’s source to see a simple implementation of how on-page hints are provided. That page allows specifying crops as absolute pixel values, but a more typical use case would be to select a given element of the page, determine its placement in pixels away from the left, right, top and bottom edges of the viewport, and adjust the crop based on that to show just the given element and its contents.

Detect when current tab is shared

When a browser tab is being shared, the document loaded in that browser tab can detect whether or not CrankWheel is currently sharing it. Note that this is true only for the “browser tab” mode of screen sharing in CrankWheel, and the web page will not be able to detect whether full screen or application window screen sharing is ongoing.

Here’s how:

Add the className crankwheel-screen-sharing-indicator to an element on the page (CrankWheel will use the first one it finds, if any).
When screen sharing starts for that particular browser tab, CrankWheel will set the data-crankwheel-is-sharing-this-tab attribute on the first such element to the string "true". When screen sharing is ended or changed to share a different browser tab or full screen or an application window (i.e. the current tab is no longer being shared), CrankWheel will set that attribute to the string "false".

Note that non-existence of the attribute should be interpreted the same as a value of "false" i.e. the tab is not being screen shared.

Also note that the attribute will be set to "true" as soon as a tab is selected for screen sharing, even if no viewers are currently connected to the screen sharing session.

You can see this functionality in action by visiting this page and screen sharing it using CrankWheel’s browser tab mode. You can also view that page’s source to see an example implementation of observing changes of the attribute using a MutationObserver.

Reseller API

Our reseller API is available to resellers and other partners only. It is primarily a RESTful API documented here.

In addition to the RESTful API for integration partners, the WYSIWYG editor for Instant Demos is embeddable into their applications using URL parameters to provide URLs linking back to the reseller partner’s dashboard. An example that links back to example.com for the dashboard and example.com/instructions for the instructions button would be:

https://meeting.is/ss/instant_demo/configure?dashboard_url=http://example.com&instructions_url=http://example.com/instructions

An URL like the above would typically be used in conjunction with an SSO URL generated by the “Grant token” API with the dest_url parameter included and set to /ss/instant_demo/configure (plus parameters such as above).

Integration guides for specific scenarios

We have a small collection of integration guides for specific scenarios: