VSee Messenger Web API Documentation

This document describes the VSee API in its latest implementation on a high level and is intended for prospective customers to get a feeling of what the VSee API is capable of and how much work it would take to implement in existing or future products.

The APIs described in this document require at least VSee R36 (15.0.0.707 (21214)).

VSee API Overview

VSee API consists of three main parts and three supporting sections:

  • VSee URI API which allows API Commands to be created and passed on to users

  • VSee User Management API, allowing management of API users

  • VSee Presence API, which will notify your application of the status of the users

Supporting sections

  • Stats API to retrieve call stats on calls made through API

  • Contacts API to adjust user address books

  • Recording API to retrieve VSee recordings made through API Cloud Recording (separate feature)

‘Beta’ features

  • ActiveAPI to keep track of your clients in real time, including call status, and other useful info.

VSee Detection and Installation

At a basic level, the VSee installation process is orchestrated by the partner, who directs the user to the appropriate installation URL. The user then downloads and installs VSee.

VSee used to support automatic detection, but since Chrome and Firefox have discontinued their support for NPAPI plugins, we have decided to stop supporting this way of detecting the VSee client.

Best practice is currently to offer the user a choice: have they have installed VSee already? or do they want to download now? Upon downloading and first use, set a cookie to remember this.

VSee provides a JavaScript that can direct partners to the correct URL for the download, as well as a set of screenshots with text instructions for different platforms and browsers. 

Please include http://api.vsee.com/js/vseedetect.js to get access to the VSee Javascript library. It is not recommended that you make a local copy of this file because back-end requirements may change and this file can be updated without notice.

VSee URI API

The core of the VSee API is the URI API, where an application can create URIs that will launch and configure the VSee client and execute additional commands. Common scenarios include providing the user with a button on a website that includes this URI to start a call to a provider.

The format of the URI is:

vsee:[apikey]?q=[urikey]

apikey: A string uniquely identifying the partner providing the URI.

urikey: A string uniquely identifying the URI.

 

These URIs are generated by the VSee API server. Partner’s server-side code can obtain the obfuscated URI using the VSee HTTP API. The desired commands are passed in. The API server validates and stores them, generates the obfuscated URI, and returns it to the partner for embedding.

Using said URI, the VSee client then looks up the stored parameters from the API server. The URI is valid only for a certain amount of time, so that saved or stale URIs cannot be used to make unauthorized calls.

A single URI can map to one or more commands. As opening a URI from a webpage often involves user intervention (clicking the link, responding to browser permission prompt), this allows getting as much done as possible with minimum user intervention.

URI Generation

In order to create the above mentioned URIs, an application connects to the VSee server through HTTPS and generates the URI by passing commands into the API.


Authentication

  • API key: public key identifying the partner company using the API

  • Secret key: private key used purely for server-server API access

Obfuscated URI creation

  • https://api.vsee.com/uri/create?apikey=...

  • All queries are POST

  • e.g. API is called with JSON data. Each set of URI commands will return its own URI that will cause VSee to execute each of those sets of commands.

{"secretkey": secretkey, "uris":[ [first set of uri commands], [second set of uri commands], ...] }
  • Returns:

  • Return status: 200, JSON (on success):

{ "status":"success", "data": ["first uri string", "second uri string", ...] }
  • Return status:400, JSON (on request / data error):

{ "status":"fail", "data": "error message" }
  • Return status: 500, (on server error)

  • An empty string is returned in place of the URI string should there be a non-critical error.

Each URI can have one or more commands, which are processed sequentially by the VSee client. All command names and parameters are case-sensitive.

Example of command sequence:

Initialization (“init”) block:

Each command sequence may begin with an initialization (“init”) block, containing one or more commands. These commands are executed before client login. Commands that customize the VSee client UI should generally be placed here. Also, note that the “setUser” command MUST be called in the “init” block.

If present, the “init” block MUST be first in the command sequence.

Operational commands:



  • Specifies the credentials that VSee should use to log in.
    Must be called in “init” block only.
    { "setUser" : { "username" : string, "password" : string } }

  • Call the specified user. Exits VSee when the call ends.
    { "startCall" : { "username" : string } }

  • Wait for an incoming call. Exits VSee when the call ends, or if no call is received for a certain amount of time (by default, 20 minutes). Incoming call can also be automatically accepted either from any user, or from only the specified user.
    { "waitForCall" : {
        "timeout" : int, (optional, default 1200 seconds)
        "autoaccept" : boolean, (optional, default false)
        "acceptuser" : string (optional, default none)
        }
    }

  • Hang up. In a group call, leaves the meeting and closes all video windows.
    { "hangup" : {} }

  • Shut down VSee.
    { "exit" : {} }

  • Show AV setup dialog
    Must be called AFTER the “init” block.
    { "showAVSetup" : {} }

 

List of UI commands:

  • Set video window properties for a specific user
    Given a username, this sets the default video window position and size.
    For best results, set window position early -- before the call is placed or received. In most cases, this means calling this command in the “init” block.
    { "setVideoWindow" : {
    "username" : string,
    "x": int, (default 0)
    "y": int, (default 0)
    "width" : int, (default 320)
    "height" : int (default 240)
    "pinned" : boolean  (default false)
    }

  • Disable address book, add-contact buttons, and corresponding menu items
    Should be called in the “init” block.
    { "setAddressBook" : { "enabled" : boolean } }

  • Suppress first-time tutorial
    Should be called in the “init” block.
    { "setFirstTutorial" : { "enabled" : boolean } }

  • Suppress Outlook import request
    Should be called in the “init” block.
    { "setOutlookImport" : { "enabled" : boolean } }

  • Suppress post-call survey
    Should be called in the “init” block.
    { "setCallSurvey" : { "enabled" : boolean} }

  • Disable call history and missed-call dialog
    Should be called in the “init” block.
    { "setHistory" : { "enabled" : boolean} }

  • Suppress statistics window, which may contain usernames
    Should be called in the “init” block.
    { "setStatisticsWindow": { "enabled" : boolean } }

 

User Management API

In order to create and manage API users, VSee has implemented a User Management API that allows an application to execute the following actions:

Create user(s)

  • https://api.vsee.com/user/create?apikey=...

  • {
    "secretkey" : secretkey,
    "username" : username,
    "password" : unencrypted password,
    "fn" : firstname,
    "ln" : lastname
    }

  • Returns 200 on success
    { "status":"success", "data": null }

  • Returns 400: error in query
    { "status":"fail", "data": error message }

  • Returns status:409, JSON (on conflicting user):

{ "status":"fail", "data": error message }

  • Returns 500: server error
    { "status":"error", "message": error message }

  • CURL example:
    curl -X POST -H "Content-Type:application/json"
    https://api.vsee.com/user/create?apikey=...
    --data '{
    "secretkey":"...",
    "username":"testuser1",
    "password":"password1",
    "fn":"Firstname",
    "ln":"Lastname"
    }'



Update user(s)

  • https://api.vsee.com/user/update?apikey=...

  • {
    "secretkey" : secretkey,
    "username" : username,
    "password" : unencrypted password,
    "fn" : firstname,
    "ln" : lastname
    }

  • Returns 200 on success
    { "status":"success", "data": null }

  • Returns 400: error in query
    { "status":"fail", "data": error message }

  • Returns 500: server error
    { "status":"error", "message": error message }

  • CURL example:
    curl -X POST -H "Content-Type:application/json"
    https://api.vsee.com/user/update?apikey=...
    --data '{
    "secretkey":"...",
    "username":"testuser1",
    "password":"password1",
    "fn":"Firstname",
    "ln":"Lastname"
    }'



Delete user(s)

  • https://api.vsee.com/user/delete?apikey=...

  • {
    "secretkey" : secretkey,
    "username" : username
    }

  • Returns 200 on success
    { "status":"success", "data": null }

  • Returns 400: error in query
    { "status":"fail", "data": error message }

  • Returns 500: server error
    { "status":"error", "message": error message }

  • CURL example:
    curl -X POST -H "Content-Type:application/json"
    https://api.vsee.com/user/delete?apikey=...
    --data '{
    "secretkey":"...",
    "username":"testuser1"
    }'



List users

  • https://api.vsee.com/user/list?apikey=...

  • { "secretkey" : secretkey}

  • Returns 200 on success
    { "status":"success",
    "data": [ "username1", "username2" ... ] }

  • Returns 400: error in query
    { "status":"fail", "data": error message }

  • Returns 500: server error
    { "status":"error", "message": error message }

  • CURL example:
    curl -X POST -H "Content-Type:application/json"
    https://api.vsee.com/user/list?apikey=...
    --data '{
    "secretkey":"..."
    }'



Limitations:

  • Whenever a user is created using the user management API, it will automatically get a "partnerid+" string attached to the front (partnerid is replaced by the actual partner id).

  • All usernames specified with regards to user management API should not have the "partnerid+" string appended at the front. However, when this username is used to login a user, the "partnerid+" should be attached in the 'setUser' command.

  • Creation of large batches of users can be performed in bulk by sending a user list to VSee.

  • All passwords must not be blank.

  • All queries are POST.

Presence API

The real-time presence updates for VSee users can be obtained via JavaScript during run-time.

The following files are used in our examples. http://api.vsee.com/examples/presence.html

Please include http://api.vsee.com/js/vseepresence.js to get access to the VSee Javascript library. It is not recommended that you make a local copy of this file because back-end requirements may change and this file can be updated without notice.

filename

description/purpose

jquery.js

Jquery (Include ours for maximum reliability or a reasonably modern version of your own choosing)

pubnub.js

This is the low level pubnub API.  While it is possible to link directly to pubnub to get their API, the version hosted on our site will have been tested to work with our software.

vseepresence.js

Vsee presence JavaScript library



The following code in the HTML <head> to initialize

The presence API installs a jQuery plugin that makes it easy to make UI changes based upon presence state changes.  They are described below but both need to determine which user's presence information should drive the changes.  You can simply pass in the username like this:

 $('<some jquery selector').vsee('method', { username: 'demo@vsee.com' });

However, that often won't be useful if you are monitoring more than one user's presence.  In that case, the username can be embedded directly in the DOM as an attribute. First the elements directly selected by jQuery are checked for the username attribute.  If it isn't there, then it looks to see if there is a single element inside the selected element with the username attribute.  If there is, it's value is used.  If not, the closest surrounding element with a username attribute is used.

 

For example:



Call

Username selected

Why

Call

Username selected

Why

$('#div1').vsee

demo@vsee.com

div1 has username attribute directly

$('#div2').vsee

demo@vsee.com

This one is a little confusing.  It selects the username from its parent (div1) since div2 has no username attribute but div4 and div5 both do.  Child elements are only used if there is only one.  There would be no way to know which one is the correct one.

$('#div3').vsee

tom@vsee.com

div4 (an enclosed element) has username attribute

$('#div6').vsee

milton@vsee.com

div6 has the attribute so div1's doesn't matter

 

This example is intentionally convoluted and confusing.  In practice you wouldn't ever nest username attributes like this but the system is flexible enough that you can insert the attribute where it is convenient and it will still work as long as it is accessible using these rules.

One final note, if you already have the usernames in the DOM as attributes, but you are not using the attribute “username,” you can override it like this:

$('selector').vsee('method', { usernameAttr: "vseeid" });

There are two jQuery methods demonstrated here that should cover most needs.  The first, the call to VSee ('presenceClasses'), adds css classes to the elements selected by the jQuery selector, $('.status-alert').  

 

In the body of the html file, there are the following divs:



Each status-alert div will have classes added in the form of "vsee_presence_<presence>" where presence is the current user status like 'available', or 'offline'.  These classes will be updated when the user's presence changes.  

The example takes advantage of this with the following style rules:

So, as each user's status changes, the background color of the div will change.

The other jQuery plugin based method is the call to vsee('showByPresence').  This simply shows and hides elements based upon the user's presence state.  You can use the default rules (hide elements when the user is offline, loading, or unknown states) or supply your own rules with either an include or exclude list.

If you need to implement features that cannot be implemented through CSS, you can execute arbitrary code when a user’s status changes.  In the example above, the call to subscribe sets up a callback that is executed every time the user (in this case "tom@vsee.com") status changes.  The new status is passed in to the callback.  In the example, I use the status to only execute some code when "tom@vsee.com" becomes available.

Finally, for any user that is currently subscribed (either by calling .subscribe directly or through one of the jQuery plugin methods) you can get their current state at any time by calling getUserState.

Stats API

The VSee stats API is an easy way for partners to retrieve call statistics on their users. Stats are stored for three months on VSee API servers and can be retrieved with a simple HTTP Post call akin to the other API REST calls.

A successful result will look like this:

Contacts API

In case an application needs to have control over the user’s address book, this can be achieved through the contacts API. This API allows a partner to add and remove groups and contacts in a user’s address book.

This API call is akin to above mentioned APIs.

VSee HIPAA compliant cloud recording API

As an additional feature to our API services, VSee offers a cloud recording functionality where any calls made through the VSee API can be recorded directly into VSee’s secure cloud storage (through AWS S3 services).

These recordings can be accessed through VSee’s recording API that lists stored recordings.

Encrypted recordings can be retrieved through this API by acquiring a temporary access token or generating temporarily accessible hyperlinks.

For more information, please contact your sales representative.

Beta ActiveAPI

Vsee’s ActiveAPI is a relatively new way to connect to API clients. This allows an API partner to connect to running API clients directly and get real time information on their status.

Connections are created through Firebase 3rd party service, which has a variety of libraries available.

Through this connection, an application can also influence the VSee client directly and execute any API command straight away, without ‘manual’ URI execution through a user or browser website, as would be required for the URI API.

For more information, please contact an API Support representative.

API Details

VSee Client Launch Handling

This section describes what happens when a VSee URI is opened in the browser. In all cases, when VSee executes the commands referred to by the URI, it does so in the original order specified.

VSee is not installed

Behavior is browser-dependent, with some browsers notifying the user that the program that handles the URI is not installed, and others failing silently.

To improve the UX for this case, partner web pages can use a VSee-provided JavaScript API (to be implemented) to detect if VSee is installed locally. If VSee is not installed, a new window can be opened and directed to the appropriate location, where the client installer is instantly downloaded. The user can then run it to install VSee.

VSee is installed but not running

Clicking the URI will start VSee (assuming user grants permission) and pass it the URI. 

API parameters are applied to VSee upon launch, before any user interface element is displayed to the user. VSee then executes the commands.

VSee is installed, running, but not logged in

Windows: Clicking the URI will start a second instance of VSee and pass it the URI. The second instance detects the first instance, passes it the URI, and terminates itself. The first instance then executes the commands.

Mac & iOS: Clicking the URI will pass it to the running instance, which executes the commands.

VSee is installed, running, but logged in as another user

Windows: Clicking the URI will start a second instance of VSee and pass it the URI. The second instance detects the first instance, passes it the URI, and terminates itself.

Mac & iOS: Clicking the URI will pass it to the running instance.

All platforms: In all cases, user is then notified that his original VSee session will be logged out for the duration of the call, and restored after the call has ended. Existing call and message windows are closed. VSee then logs in as the embedded user and executes the URI commands. When the call ends, VSee logs back in as the original user.

VSee is installed, running, and already logged in as the desired user

Windows: Clicking the URI will start a second instance of VSee and pass it the URI. The second instance detects the first instance, pass it the URI, and terminates itself. The first instance then executes the commands.

Mac & iOS: Clicking the URI will pass it to the running instance, which executes the commands.

In this case, VSee detects that the desired user is already logged in, and proceeds to apply API parameters such as UI modifications, if there is any difference between that of the running instance and the parameters.

VSee is installed, running, logged in as desired user, and in a call

Extending case 7.5, if the URI contains a call command, the new person is added to the existing call. If the URI has a hang-up command, VSee hangs up or leaves the meeting, as appropriate.

This case will occur when a URI is clicked to end the call or to add another person into the call via the web UI.

Call Termination

Calls can be terminated by a URI command triggered from the browser, or via the VSee UI. Presence API can be used to be notified when the user is no longer in a call.

Permissions & Privacy

There is a need to protect the privacy of certain users e.g. doctors. Specifically, to prevent others from communicating with them (call, IM, etc.) outside the intermediation of the partner app. This can be achieved by suppressing the address book during partner calls, and ensuring that user IDs are not displayed elsewhere in the VSee UI.

Updates

  • Regular updates on Windows are silent. At most they may delay call start slightly when being applied, but will not require any user intervention.

  • Regular updates on Mac involve a UI dialog. VSee will investigate if this can be suppressed. Otherwise, notice of Mac updates will be provided to partners.

  • Updating on iOS is user-driven from the App Store.

  • Forced updates (infrequent) require user intervention. Ample notice will be provided to partners ahead of such updates.

  • It is possible to disable automatic updates by editing the registry

  • There is an MSI installer available to roll out the latest VSee version to a corporate network, and prevent automatic updates by users.

Example URI API JSON

The following example sets a variety of VSee properties as well as window placement and then start a call.

Upon call end, VSee will exit.

This second example generates TWO URI’s, one to login the user and the second to make the actual call