Create a room

Optional parameters:
starturl (string) - url of the initial webpage to be shown.
title (string) - a description of the room, this will show in analytics.
bookmarks (array) - overrides the default bookmarks displayed in the room.
(each bookmark must contain: name (string) - description of the bookmark, link (string) - url to the webpage).
session (object) - adds session data to the created room.
session.cookies (array) - cookies to add to the room
(each cookie must contain: domain (string), path (string), name (string), value (string), secure (bool), httponly (bool))
session.storage (array) - storage key/value pairs to add to the room
(each storage must contain: domain (string), name (string), value (string))
disabledfeatures (array) - features to disable in the room, the options include:
MODE_DOCUMENT_SHARE
MODE_VIDEO_SHARE
MODE_SCREEN_SHARE
MODE_LOGOUT
TOOLS_SCREEN_RECORDING
TOOLS_VIDEO_CHAT
TOOLS_AUDIO_CHAT
TOOLS_12MANY_VIDEO
TOOLS_MOUSE_TRACKING
TOOLS_DISCONNECT_USER


POST /api/v3/create HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "starturl":"http://www.samesurf.com",
   "title": "Product demo",
   "bookmarks": [
      {
         "name": "Samesurrf",
         "link": "https://www.samesurf.com"
      }
   ],
   "session": {
      "cookies": [
         {
            "domain": "twitter.com",
            "path": "/",
            "name": "auth_token",
            "value": "your_auth_token",
            "secure": true,
            "httponly": true
         }
      ],
      "storage": [
         {
            "domain": "mydomain.com",
            "name": "test",
            "value": "test_value"
         }
      ]
   }
}

Example Response:

HTTP/1.1 200 OK
Date: Sun, 20 May 2018 17:26:48 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "room":"123456789",
   "token":"ABCDEF123456",
   "leadertoken":"ABCDEF123456",
   "privateinvitation":"https://realtime.samesurf.com/{room}/{leadertoken}",
   "publicinvitation":"https://realtime.samesurf.com/{room}/{token}",
   "success":true
}

This is an example using jQuery for ajax, and jsrsasign to create the JWT token.


var token_body = {
  iat: Math.floor(new Date().getTime() / 1000),
  sub: "YOUR API KEY",
};

var token = KJUR.jws.JWS.sign("HS256", { typ: "JWT" }, token_body, "YOUR API SECRET");
var data = {
  starturl: "http://www.yahoo.com"
};

$.ajax({
   url: "https://api.samesurf.com/api/v3/create",
   dataType: "json",
   type: "POST",
   data: JSON.stringify(data),
   beforeSend: function (xhr) {
      xhr.setRequestHeader("Content-Type", "application/json");
      xhr.setRequestHeader("Authorization", "Bearer " + token);
   },
   error: function () {
      // error handler
   },
   success: function (data) {
      return data;
   }
});

The last example used the HS256 signing algorithm and embeds the secret in a page. If you don't wish to do this, you could call the api from you own server, or enable the "none" algorithm for the api key. Here is an example doing just that:


var token_body = {
   iat: Math.floor(new Date().getTime() / 1000),
   sub: "YOUR API KEY",
};
var token = KJUR.jws.JWS.sign("none", { typ: "JWT" }, token_body);
var data = {
   starturl: "http://www.yahoo.com"
};
$.ajax({
   url: "https://api.samesurf.com/api/v3/create",
   dataType: "json",
   type: "POST",
   data: JSON.stringify(data),
   beforeSend: function (xhr) {
      xhr.setRequestHeader("Content-Type", "application/json");
      xhr.setRequestHeader("Authorization", "Bearer " + token);
   },
   error: function () {
      // error handler
   },
   success: function (data) {
      console.log("this is a link to the room", data.publicinvitation);
      return data;
   }
});

Scheduling a room

As well as creating a room to be used straight away, as in the previous examples, you can also schedule a room to be used at a specified date.

Pass through an eventtime for the room to be scheduled, you can also specify the timezone with the eventtime if it's not UTC time.

Required parameters:
eventtime (string) - date in format dd/MM/yyyyThh:mm:ssZ, you only need the Z if the time is UTC.

Optional parameters:
timezone (string) - you only need to add a timezone if the event time is not in UTC, example "Europe/London".
lengthinminutes (number) - duration of scheduled event.
invitees (string) - comma seperated list of invitee email address, these will be emailed an invitation.
invitemessage (string) - extra text to add to the invitation email.


POST /api/v3/create HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "starturl":"http://www.samesurf.com",
   "title": "Product Demo",
   "eventtime": "2017-02-22T16:30:00",
   "timezone": "Europe/London"
}

Example Response:

HTTP/1.1 200 OK
Date: Sun, 20 May 2018 17:26:48 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "room":"123456789",
   "token":"ABCDEF123456",
   "leadertoken":"ABCDEF123456",
   "privateinvitation":"https://realtime.samesurf.com/{room}/{leadertoken}",
   "publicinvitation":"https://realtime.samesurf.com/{room}/{token}",
   "success":true
}

Find running rooms

Optional parameters:
skip (number): number of rooms to skip.
limit (number): maximum number of rooms to return.


POST /api/v3/runningrooms HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "skip": 5
   "limit": 5
}

Example Response:

HTTP/1.1 200 OK
Date: Sun, 20 May 2018 17:26:48 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "rooms": [
      {
         "room": "123456789",
         "starttime": "2016-12-19T14:20:22Z",
         "publicinvitation": "https://realtime.samesurf.com/{room}/{leadertoken}",
         "privateinvitation": "https://realtime.samesurf.com/{room}/{token}",
         "title": "Room Title"
      },
      ...
   ],
   "totalrooms": 15,
   "success": true,
}

Create limited use invitation

Required parameters:
room (string) - room number.
usagelimit (int) - number of times the invitation can be used
isleader (bool) - whether the user should become the leader if they are the first user to enter the room.

Optional parameters:
usersname (string) - automatically set the user's name when they enter the room.


POST /api/v3/createlimitedusetoken HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "room":"123456789",
   "usagelimit": 1,
   "isleader": true
}

Example Response:

HTTP/1.1 200 OK
Date: Sun, 20 May 2018 17:26:48 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "token":"ABCDEF123456",
   "link":"https://realtime.samesurf.com/{room}/{token}",
   "success":true
}

Delete limited use invitation

Required parameters:
token (string) - token for invitation.


POST /api/v3/deletelimitedusetoken HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "token":"ABCDEF123456"
}

Example Response:

HTTP/1.1 200 OK
Date: Sun, 20 May 2018 17:26:48 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "success":true
}

Accessing analytics overview

There are no required parameters for this call.


POST /api/v3/analyticsoverview HTTP/1.1
Host: api.samesurf.com
Content-Length: 0
Authorization: Bearer YOUR-BEARER-TOKEN

Example Response:

HTTP/1.1 200 OK
Date: Sun, 20 May 2018 17:26:48 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "url_latest": "http://www.google.com",
   "url_most_popular": "google.com",
   "rooms_total": 131,
   "rooms_today": 20,
   "rooms_thisweek": 43,
   "rooms_thismonth": 102,
   "averageduration_alltime": 34,
   "averageduration_today": 28,
   "averageduration_thisweek":33,
   "averageduration_thismonth": 33,
   "success": true
}

Accessing list of rooms

Optional parameters:
skip (number): number of rooms to skip.
limit (number): maximum number of rooms to return.


POST /api/v3/analyticsrooms HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "skip":20,
   "take": 20
}

Example Response:

HTTP/1.1 200 OK
Date: Sun, 20 May 2018 17:26:48 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "total_rooms": "123",
   "rooms": [
      {
         "room": "123456789",
         "title": "Product Demo",
         "date": "2017-01-13T10:10:16Z",
         "duration": 1234,
         "screenrecordings": 1
      },
      {
         "room": "234567890",
         "title": "Testing",
         "date": "2016-12-22T16:22:01Z",
         "duration": 2687,
         "screenrecordings": 2
      }.
      ...
   },
   "success": true
}

Accessing room analytics

Required parameters:
room (string) - room number

Optional parameters
version (int) - the room version if the same room number has been used multiple times, default is 0.


POST /api/v3/roomanalytics HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "room":"123456789",
   "version": 1
}

Example Response:

HTTP/1.1 200 OK
Date: Sun, 20 May 2018 17:26:48 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "title": null,
   "events": [
      {
         "type": "start",
         "date": "2017-01-13T10:10:26Z",
         "sender": "",
         "target": "",
         "data": "564906354"
      },
      {
         "type": "url",
         "date": "2017-01-13T10:10:26Z",
         "sender": "",
         "target": "",
         "data": "http://www.google.com"
      },
      ...
   ],
   "users": [
      {
         "guid": "F65CFEB90EF3D44DC759AC129BFE1F5BF2A29986",
         "host": true,
         "joinedat": "2017-01-13T10:10:26Z",
         "leftat": "2017-01-13T10:11:06Z",
         "name": "Host",
         "ipaddress": "1.2.3.4",
         "city": "London",
         "country": "United Kingdom"
      },
      ...
   ],
   "success": true
}

Create subscription

This call can only be made from a reseller subscription.

Required parameters:
name (string) - name of subscription to be created, must be unique
licensecount (number) - number of licenses for subscription

Optional parameters:
configuration_overrides (array) - override settings that control how the subscription and their rooms function
(each override must contain: key (string) - name of override, value (string) - value of override).
Valid keys:
communications_active
default_logout_url
demotimer_active
demotimer_logout_url
disable_urlbar_all
disable_urlbar_follower
hide_bookmark_add
hide_bookmark_header
hide_bookmarks
hide_modes_menu
inroomchat_active
invitations_active
passcontrol_active
preload_host_invitations
social_changename_active
suppress_beforeunload
welcome_active
bookmarks (array) - overrides the default bookmarks
(each bookmark must contain: name (string) - description of the bookmark, link (string) - url to the webpage).
disabledfeatures (array) - features to disable in the subscription, the options include:
MODE_DOCUMENT_SHARE
MODE_VIDEO_SHARE
MODE_SCREEN_SHARE
MODE_LOGOUT
TOOLS_SCREEN_RECORDING
TOOLS_VIDEO_CHAT
TOOLS_AUDIO_CHAT
TOOLS_12MANY_VIDEO
TOOLS_MOUSE_TRACKING
TOOLS_DISCONNECT_USER


POST /api/v3/reseller/createsubscription HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "name":"ResoldSubscriptionName",
   "licensecount": 10,
   "configuration_overrides": [
      {
         "key":"communications_active", 
         "value":"false"
      },
      {
         "key":"default_logout_url",
         "value":"http://www.mywebsite.com"
      }
   ],
   "bookmarks": [
      {
         "name": "Samesurrf",
         "link": "https://www.samesurf.com"
      }
   ],
   "disabled_features": [
      "MODE_SCREEN_SHARE",
      "MODE_VIDEO_SHARE"
   ]
}

Example Response:

HTTP/1.1 200 OK
Date: Sun, 20 May 2018 17:26:48 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "success":true
}

Delete subscription

This call can only be made from a reseller subscription.

Required parameters:
name (string) - name of the subscription to be deleted


POST /api/v3/reseller/deletesubscription HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "name":"ResoldSubscription1"
}

Example Response:

HTTP/1.1 200 OK
Date: Sun, 20 May 2018 17:26:48 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "success":true
}

Create api key

This call can only be made from a reseller subscription.

Required parameters:
subscription (string) - name of subscription


POST /api/v3/reseller/createapikey HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "subscription":"ResoldSubscriptionName"
}

Example Response:

HTTP/1.1 200 OK
Date: Sun, 20 May 2018 17:26:48 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "success":true,
   "apikey": "generated_api_key",
   "apisecret": "generated_api_secret"
}