NAV
Logo
curl

Introduction

Welcome to the VisoCon REST API documentation. This document will show you how to manage videoconferences in your own source code.

The API can handle both String parameters and JSON objects.

Styling/Branding

As an admin user you will find the domain settings menu in your navigation bar when loggin into https://{your_subdomain}.eyeson.solutions. You will be able to:

Authentication

HTTP Header example:

curl "https://{your_subdomain}.eyeson.solutions/api/v2/users/me"
     -H "Authorization: Bearer ACCESS_TOKEN"

URL Parameter example:

curl "https://{your_subdomain}.eyeson.solutions/api/v2/users/me?access_token=ACCESS_TOKEN"

Our API requests are user-based. Meaning you will need to pass an user authentication workflow in order to execute any of these requests. To obtain an access token, you will have to authenticate the user in our system first.

To authenticate a user you can either follow the login workflow below or if the customer platform offers an OAuth interface you will find information in OAuth Login.

However, after you got the access_token you need to pass it through all upcoming API requests.

Responsive Webview

If you want to determine the correct login URL (otherwise see Basic Login or OAuth Login)

curl "https://{your_subdomain}.eyeson.solutions/api/v2/auth"

The above command returns JSON structured like this:

{
  "login_url": "https://{your_subdomain}.eyeson.solutions/login"
}

Attach a redirect_uri your app can handle to the login URL:

curl "<login_url>?redirect_uri=yoursheme://login_finished"
     -X POST

The access token will be attached to your redirect_uri as hash key

"yoursheme://login_finished#access_token=d-3T2BW1Do5_TEzljMozNs9iNbf2nav3G-gmviXfTHg&expires=2014-04-16T10:33:22+00:00&refresh_token=mO6ZwM6Jqczz__2EMpMr8qUcFVcnx9x0_pADwHCxbQE"

In order to handle the below described login workflows the easy-way you can ask the API for the right login URL. When you open the URL in a native webview the user will see a responsive designed login mask which returns him back to a custom URL scheme after successful login. Signup and forgot password will be provided in the webview, too.

Get correct login URL (optional)

GET /api/v2/auth

Parameter Required Description
oauth_setting_id optional Get specific entry point if you have configured multiple OAuth clients in your VisoCon environment

Basic Login

Login:

curl "https://{your_subdomain}.eyeson.solutions/api/v2/auth"
     -X POST
     -d "email=your@email.com&password=yourPassword"

The above command returns JSON structured like this:

{
  "access_token": "d-3T2BW1Do5_TEzljMozNs9iNbf2nav3G-gmviXfTHg",
  "expires": "2014-04-16T10:33:22+00:00",
  "refresh_token": "mO6ZwM6Jqczz__2EMpMr8qUcFVcnx9x0_pADwHCxbQE"
}

Basic authentication requires a present user in our system.

POST /api/v2/auth

Parameter Required Type
email required String
password required String

Errors

Parameter Description
404 User does not exist
424 Too many login attempts
401 Username or password wrong

OAuth Login

If the customer platform offers an OAuth interface (both 1&2 supported) you can handle user authentication process even faster. Users originate from the customer system will be stored in the VisoCon system once they approve access during the OAuth handshake.

See Responsive Webview if you want to know how to handle this workflow.

GET /api/v2/auth/oauth

Parameter Required Type
oauth_setting_id optional String
redirect_uri optional String

Errors

Parameter Description
500 See error message

Refresh access token

curl "https://{your_subdomain}.eyeson.solutions/api/v2/auth/refresh"
      -H "Authorization: Bearer ACCESS_TOKEN"
      -X POST
      -d "refresh_token=REFRESH_TOKEN"
{
  "access_token": "ooXMKYq2fdkTPJrBS9B_QL3jcEoXZOWKrOqucWF4X68",
  "expires": "2014-04-16T10:33:22+00:00",
  "refresh_token": "O4Bh05Kb4xj2IozteQhA9PkIgJ4MHMb7MPMk5G8jnl8"
}

In case your access token expired you can exchange it for a new one once.

POST /api/v2/auth/refresh

Parameter Required Type
refresh_token required String

Errors

Parameter Description
401 Access token missing
401 Access token wrong
401 Access token expired
401 Refresh token wrong

Users

Search users

GET /api/v2/users

Parameter Required Type Default
q required String Query string
page optional Integer 1
limit optional Integer 25

Create/Update/Delete

POST /api/v2/users

PUT /api/v2/users/{user_id}

DELETE /api/v2/users/{user_id}

Parameter Required Type Default
name required String
surname required String
email required String (unique)
password required String (min. 6 chars)
avatar optional URL
company optional String
active optional Boolean true
admin optional Boolean false

Get user

Get my own credentials:

curl "https://{your_subdomain}.eyeson.solutions/api/v2/users/me"
      -H "Authorization: Bearer ACCESS_TOKEN"
{
  "id": 1,
  "email": "michael.maier@visocon.com",
  "name": "Michael",
  "surname": "Maier",
  "sip_username": "1@visocon.com",
  "sip_password": "$2a$10$Xr5sJ1QJhqbvscP25.GyIedQRMl9kuRmt3Ecvln6vzOnja/cPcDYe"
}

Get by id:

curl "https://{your_subdomain}.eyeson.solutions/api/v2/users/18"
      -H "Authorization: Bearer ACCESS_TOKEN"
{
  "id": 1,
  "email": null,
  "name": "Michael",
  "surname": "Maier",
  "sip_username": "1@visocon.com",
  "sip_password": null
}

Get my own credentials

GET /api/v2/users/me

Get by id

GET /api/v2/users/{user_id}

Find user by e-mail

GET /api/v2/users/<email>

Contacts

The API collects serveral data about system-wide users as well as external data sets (e.g. XING profiles, individual e-mail invitations, recent calls, ...) that were ever connected to the user profile. The user object will indicate whether the user is available in the system or not (important when trying to call).

Get my contacts

curl "https://{your_subdomain}.eyeson.solutions/api/v2/users/me/contacts"
      -H "Authorization: Bearer ACCESS_TOKEN"
{
  "contacts": [
    {
      "id": 1,
      "label": "Web Pro",
      "email": "dummy_email_1@visocon.com",
      "avatar": null,
      "pending": false,
      "user": {
        "id": 18,
        "name": "Dummy",
        "surname": "Master",
        "sip_username": "18@visocon.com",
      }
    },
    {
      "id": 2,
      "label": "Sales guy",
      "email": "dummy_email_2@visocon.com",
      "avatar": null,
      "pending": false,
      "user": null
    }
  ]
}

GET /api/v2/users/me/contacts

Parameter Required Type Default
q optional Query string  
include optional "emails"  none
order optional ["last_activity"]  surname,name
page optional Integer 1
limit optional Integer 25

Get pending requests

GET /api/v2/users/me/contacts?pending=true

Parameter Required Type Default
order optional ["last_activity"]  surname,name
page optional Integer 1
limit optional Integer 25

Get sent requests

GET /api/v2/users/me/contacts?sent=true

Parameter Required Type Default
order optional ["last_activity"]  surname,name
page optional Integer 1
limit optional Integer 25

Request new contact

POST /api/v2/users/me/contacts

Parameter Required Type
user_id required Integer

Accept contact request

PUT /api/v2/users/me/contacts/{contact_id}

Deny contact request

DELETE /api/v2/users/me/contacts/{contact_id}

Remove contact

DELETE /api/v2/users/me/contacts/{contact_id}

Invite people

POST /api/v2/invitations

Parameter Required Type
contact_id optional (preferred) Integer
email optional (unless contact present) String
subject required String
content required String

P2P

Call someone

Basic setup to be available for calls

<script type="text/javascript">
    (function(w,d) {
    w.eyeson={ready:false};
    var v=d.createElement('script');v.type='text/javascript';
    v.async=true;v.src='https://{your_subdomain}.eyeson.solutions/jsapi.js?access_token={access_token}';
    var s=d.getElementsByTagName('script')[0];s.parentNode.insertBefore(v,s);
    })(window,document);
</script>

Calling someone

eyeson.call('{user_id}')

Being available for a point-to-point videocall on your website just needs the embedding of our JavaScript snippet on the right.

Call history

curl "https://{your_subdomain}.eyeson.solutions/api/v2/users/me/calls"
      -H "Authorization: Bearer ACCESS_TOKEN"
{
  "calls": [
    {
      "id": "lsmfuusftvb3uotb1rpb",
      "origin": {
        "type": "user",
        "user": {
          "id": 18,
          "name": "Dummy",
          "surname": "Master",
          "sip_username": "18@visocon.com",
        }
      },
      "destination": {
        "type": "user",
        "user": {
          "id": 23,
          "name": "Max",
          "surname":"Mustermann",
          "sip_username": "23@visocon.com",
        }
      },
      "from": "2015-01-13T15:11:25.624+00:00",
      "to": "2015-01-13T15:11:25.624+00:00",
      "status": "missed",
    }
  ]
}

GET /api/v2/users/me/calls

Parameter Required Type Default
page optional Integer 1
limit optional Integer 25
before optional  ISO 8601 (URL encoded)
after optional  ISO 8601 (URL encoded)

Mark as seen

PUT /api/v2/users/me/calls/{call_id}

Remove single entry

DELETE /api/v2/users/me/calls/{call_id}

Remove all entries

DELETE /api/v2/users/me/calls

Call events

If you try to call somebody you have to inform the API.

POST /api/v2/users/{user_id}/calls

Parameter Required Type
id required SIP Call ID
status required ["ringing", "missed", "accepted", "declined", "terminated", "busy", "cancelled"]

Messages

GET /api/v2/users/me/messages

Parameter Required Type Default
type required ["chat", "image", "call"]
before optional ISO 8601 (URL encoded)
after optional ISO 8601 (URL encoded)
seen  optional  Boolean  
order optional "asc", "desc" asc
page optional Integer 1
limit optional Integer 25

Mark as read

PUT /api/v2/users/me/messages/{message_id}

Send message to user

POST /api/v2/users/{user_id}/messages

Parameter Required Type Description
type required ["chat", "image", "slide"]
content required String Chat message, image description, presentation slide URL
call_id required String URL encoded
image optional File Attachment for "image"

Send temporary message to contact (when not a user yet)

POST /api/v2/users/me/contacts/{contact_id}/messages

Parameter Required Type
type required ["chat", "image"]
content required String

Webinars & Meetings

Upcoming/Archive

GET /api/v2/users/me/webinars

Parameter Required Type  Default
archive optional Boolean
limit optional Integer 25
page  optional  Integer 1

Meetings where I've been added but didn't respond yet

GET /api/v2/users/me/invitations

Parameter Required Type
archive optional Boolean

Accept invitation

See Join participants list

Invitation status will be set to "accepted" automatically

Set invitation status to "maybe"

PUT /api/v2/webinars/{webinar_id}/invitations/{invitation_id}

Parameter Required Type
status required "maybe"

Decline invitation

Invitation status will be set to "declined" automatically

DELETE /api/v2/webinars/{webinar_id}/invitations/{invitation_id}

Get meetings of all users (admin only)

GET /api/v2/webinars

Create/Update/Delete

POST /api/v2/meetings POST /api/v2/webinars

PUT /api/v2/webinars/{webinar_id}

DELETE /api/v2/webinars/{webinar_id}

Parameter Required Type Default Description
title required String
from required ISO 8601 (URL encoded)
to required ISO 8601 (URL encoded)
timezone optional ISO 8601 Offset UTC
privacy optional ["public", "private"] "private"
recording optional Boolean  false
description optional  String
history_shared  optional Boolean false Recording and Statistics will be accessible to all participants
business_data_required optional  Boolean false Participants have to provide their business address before they can join
speaker_chat  optional Boolean  false Participants can only chat with speakers, not to each other
text_overlay  optional Boolean  false Display name inserts of currently active speakers in video

Aliases

Aliases are used for call-ins by phone (SIP-gateway assumed)

POST /api/v2/webinars/{webinar_id}/aliases

DELETE /api/v2/webinars/{webinar_id}/aliases/<alias>

Parameter Required Type Default
alias optional String Alias will be generated if left empty

Invitations

Get invitations of current meeting

GET /api/v2/webinars/{webinar_id}/invitations

Parameter Required Type Default
status optional ["added", "invited", "accepted", "declined", "maybe"] "added"
limit optional Integer 25
page optoinal Integer 1

Add someone to the invite list

POST /api/v2/webinars/{webinar_id}/invitations

Parameter Required Type Description
contact_id any_of Integer Preferred
user_id any_of Integer Unless any of the others present
group_id any_of Integer Unless any of the others present
email any_of String Unless any of the others present
subject optional String Send a message. If defined, content must be defined, too.
content optional Text Send a message. If defined, subject must be defined, too.

Send an invitation message

POST /api/v2/webinars/{webinar_id}/reminders

Parameter Required Type Description
subject required String  
content required String
invitation_status optional ["added", "invited", "accepted", "maybe", "declined"] Message will be delivered to users who have the selected invite status
trigger required ["send", "schedule", "event"] Send immediately / Schedule to specific time (minutes_before_start required) / Send as soon as the user becomes the selected invitation_status
minutes_before_start optional Integer required if trigger is set to "schedule"

Save an invitation message as template

POST /api/v2/users/me/reminders

Parameter Required Type Description
name  required String Name of the template
subject required String  
content required String

Delete an invitation message template

DELETE /api/v2/users/me/reminders/{reminder_id}

Participants list

Join participants list

GET /api/v2/webinars/{webinar_id}/participations/new

Possible responses

Parameter Description
202 User has been accepted
428 Additional data required (redirect user to participation_url)
402 Payment required (redirect user to participation_url)

Force add user to participants list

Only organizer and co-speaker are able to execute!

POST /api/v2/webinars/{webinar_id}/participations

Parameter Required Type
user_id required Integer

Show a specific participant

Only organizer, co-speakers and oneself are able to execute!

GET /api/v2/webinars/{webinar_id}/participations/{user_id}

Remove user from participants list

Only organizer and co-speaker are able to execute!

DELETE /api/v2/webinars/{webinar_id}/participations/{user_id}

Messages

GET /api/v2/webinars/{webinar_id}/messages

Parameter Required Type Default
type required "chat", "slide", "master_status", "user_status"
before optional ISO 8601 (URL encoded)
after optional ISO 8601 (URL encoded)
order optional "asc", "desc" asc
page optional Integer 1
limit optional Integer 25

Send message to meeting room

POST /api/v2/webinars/{webinar_id}/messages

Parameter Required Type
type required "chat", "slide"
content required String (e.g. Chat message, Slide URL, ...)

Heartbeat

The moderator has to send a heartbeat every 60 seconds

PUT /api/v2/webinars/{webinar_id}/participations/{user_id}

Termination

POST /api/v2/webinars/{webinar_id}/messages

Parameter Required Type
type required "shutdown"

Recording

GET /api/v2/webinars/{webinar_id}/recordings

DELETE /api/v2/webinars/{webinar_id}/recordings/{recording_id}

Activity Feed

All interactions

curl "https://{your_subdomain}.eyeson.solutions/api/v2/users/me/activities"
      -H "Authorization: Bearer ACCESS_TOKEN"
{
  "activities":[
    {
      "type": "message",
      "message": {
        "content": "My message",
        "created_at": "2015-04-10T13:18:52.238Z",
        "id": "5527cdbc4d696305216c0100",
        "type": "chat",
        "origin": {
          "type": "user",
          "user": {
            "id": 110,
            "email": null,
            "name": "Dummy",
            "surname": "User",
            "avatar": "https://{your_subdomain}.eyeson.solutions/assets/default_avatar.png",
            "sip_username": "110@visocon.com",
            "sip_password": null
          }
        },
        "destination": {
          "type": "user",
          "user": {
            ...
          }
        },
        "seen_by": [110]
      }
    }
  ]
}

GET /api/v2/users/me/activities

Parameter Required Type Default
page optional Integer 1
limit optional Integer 25
seen  optional  Boolean  

User interactions

Returns all activities between self and given user.

GET /api/v2/users/{user_id}/activities

Parameter Required Type Default
before optional ISO 8601 (URL encoded)
after optional ISO 8601 (URL encoded)
order optional "asc", "desc" asc
page optional Integer 1
limit optional Integer 25

Push Notifications

Android

Register device

Android:
https://developer.android.com/google/gcm/client.html

POST /api/v2/users/me/devices/android

Parameter Required Type
registration_id required String

Unregister device

DELETE /api/v2/users/me/devices/android/{registration_id}

iOS

Register device

iOS:
https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html

POST /api/v2/users/me/devices/ios

Parameter Required Type
device_token required String

Unregister device

DELETE /api/v2/users/me/devices/ios/{device_token}

Webhooks (beta)

Webhooks are HTTP POST requests to pre-defined endpoints containing JSON objects similar to the above described API responses.

Webhook endpoints can be configured in your domain settings as long as you have got admin rights.

Types

Webhook Type Description Contains
invitation_created Will be triggered when a new person has been added Invitation
invitation_updated Will be triggered when an invitation status has been updated Invitation
participant_joined Will be triggered when a new participant has joined Participation
recording_available Will be triggered after each video meeting or webinar which has been recorded as soon as the recording
files are available. Webinar