Menu
VivoMeetings Embedded video and voice is an easy-to-implement video meetings API. Embed video meetings into your existing application or website with a few lines of code.
Vivomeetings is a real-time communications tool commercialized as a white-label product for partners to deploy their own branded version. Most often, white-label solutions follow the VivoMeetings model of service, which is similar to other enterprise offerings for scheduling, video meetings, webinars, transcriptions, recordings, and physical meeting room support.
Numerous channel partners have deployed versions of ICC under their own brand, and sometimes with their own integrations and additional services.
This document outlines the interface characteristics of Vivomeetings platform for real-time communication. The Application Programming Interface described within will provide methods by which developers may request and send instructions to and from the platform with the objective to integrate 3rd party applications, and extend ICC’s functionality.
RCC is a cloud-based, multi-tenant solution that provides scale and security.
Below is a diagram outlining a high-level view of system architecture.
The Vivomeetings Communication Cloud has a global network of media Points of Presence (POPs). These POPs connect to each other using Amazon’s high quality and low latency private network forming a network mesh architecture. The result is high-quality voice, and video for participants all across the globe.
Vivomeetings currently has POPs in the following countries:
Meeting Hosts have a dedicated meeting URL and can host video meetings. Hosts belong to a company and a company can belong to a domain, for example, VivoMeetings.com.
VivoMeetings APIs and Embedded Meetings can be used directly on VivoMeetings.com, however many partners require a full Whitelabel implementation with their own custom domain. .com/conf/call/1234567 is an example of a Whitelabel meeting URL.
When using the API on VivoMeetings.com developers can manage Host accounts under a single Company and Embed meetings of those Hosts in their own website or application. We call those Company Admins.
Partners that need a full Whitelabel and meetings on their own domain can create companies and hosts under those companies. We call these partners Resellers.
HTTPS POST, mime-type application/json, with the request body being a JSON-serialized dictionary (key-value pairs).
All requests except Authenticate must include, besides the parameters listed under Request at each individual method, an auth_token parameter, as received in the response to the Authenticate method. Unless otherwise indicated, all request Input parameters are required.
The FQDN for API requests will be that of a company, typically the initial admin company created for the reseller during onboarding. E.g. the entire URL for an authenticated request would be https://reseller-admin.reseller.tld/enterprise_api/authenticate.
Response HTTP status code will indicate the overall status of the request:
Response mime-type will be application/json, the body being a JSON-serialized dictionary including, besides the values listed under Response at each method, a ‘message’ with details of any errors.
Before calling other methods, API consumers must authenticate. The credentials will be those of a host created from the Admin UI at least the Company Admin level. (It can coincide with a real host, but typically resellers will create a dedicated ‘host’ for API use.)
Also see 12. OAuth for details on using OAuth with the API. – Download API documentation
ResellerAdmin/CompanyAdmin
POST "/enterprise_api/authenticate"
Request body (application/json):
{
"email": "api@partner.tld",
"password": "Sup3rSecret!"
}
Response body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98"
Before calling other methods, API consumers must authenticate. The credentials will be those of a host created from the Admin UI at least the Company Admin level. (It can coincide with a real host, but typically resellers will create a dedicated ‘host’ for API use.)
Request:
Response:
Only full Whitelabel partners need to create companies. Developers using the API on VivoMeetings.com do not need to create companies.
A Company represents the customer. A company could be any organization that subscribes to a conferencing service. A company has any number of Host Accounts. Host accounts are the end-users.
A company stores basic details about the customers.
/enterprise_api/company/create
ResellerAdmin Only
POST "/enterprise_api/company/create"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"subdomain": "joe",
"name": "The Joe Company",
"openid_provider": true
}
Response body (application/json):
{
"id": 5
}
Request:
Response:
A host is able to organize and host meetings and conference calls. Each host has a dedicated meeting URL that can be used to host meetings on-demand with no other API calls necessary.
POST "/enterprise_api/host/create"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 5,
"name": "John Host",
"email": "john@company.tld",
"password": "SoSecret5!",
"no_welcome_email": true,
"role": "HOST",
"openid_sub": "23081912eca",
“subscription_ids”: [102, 104],
"moderator_pin": 9876543,
"access_code": 1234567
}
Response body (application/json):
{
"host_id": 9,
"name": "John Host",
"email": "john@company.tld",
"primary_dialin_number": "+1-416-555-1234",
"meeting_url": "https://company.reseller.tld/conf/call/1234567",
"role": "HOST",
"openid_sub": "23081912eca",
"access_code": {"number": "1234567"},
"moderator_pin": {"number": "9876543"},
"password_creation_link": "https://...",
"login_token_public_key": "a1b2c3e4d5f6...",
"subscription_ids": [110, 111]
}
Request:
Response:
Host accounts you create have a dedicated meeting URL that can be used at any time to host a meeting. You don’t have to schedule a meeting however sometimes developers may want to have meetings scheduled.
Scheduled meetings will send calendar invitations to participants and can send email and text message reminders.
Scheduled meetings can also have additional features like having a unique meeting URL and access code. This is typically desirable for meeting hosts that have many back-to-back meetings or want extra security.
POST "/enterprise_api/conference/create"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"host_id": 1,
"subject": "Test Conference",
"agenda": "An agenda",
"start": "2020-09-19 13:00:00",
"time_zone": "Europe/London",
"duration": 60,
"auto_record": "none",
"auto_transcribe": false,
"one_time_access_code": true,
"security_pin": "123456",
"mute_mode": "conversation",
"participants": [ 2, 3 ]
}
Response body (application/json):
{
"conference_id": 183,
"subject": "Test Conference",
"agenda": "An agenda",
"start": "2020-09-19 13:00:00",
"end_time": "2020-09-19 14:00:00",
"active": false
"time_zone": "Europe/London",
"duration": 60,
"auto_record": "none",
"auto_transcribe": false,
"one_time_access_code": 987654321,
"security_pin": "123456",
"mute_mode": "conversation",
"participants": [ 1, 2, 3 ]
}
Request:
POST "/enterprise_api/conference/create"
Request body (application/json):
{
"participant_emails": [
{“email”: “bob@RoyalTeck.com”, “moderator”: true},
{“email”: “alice@RoyalTeck.com”, “moderator”: false}
]
}
Response:
You can embed VivoMeetings in your own web application or native mobile application.
You can embed any of the pages visible on VivoMeetings into your web application using an iframe with the src parameter set to the meeting room URL. In your iframe attributes, allow the camera, microphone, and fullscreen so that our meeting room and/or Livestream player works as intended.
Compatibility notes: The host page(s) must have a valid SSL certificate for our iframe to work correctly in Chrome. For our iframe to be usable in Internet Explorer if it is nested more than one level deep (if our iframe is within another iframe, or deeper) all ancestors of our iframe must belong to the same host.
Example, to embed our meeting room:
<iframe
allow="camera;microphone;fullscreen;autoplay"
src="[your-domain].com/conf/call/123456?
name=Steve+Irwin&
skip_join=true”
/>
Example, to embed our meeting room with the camera off
<iframe
allow="camera;microphone;fullscreen;autoplay"
src="[your-domain].com/conf/call/123456?
name=Steve+Irwin&
skip_join=true&
mute=camera”
/>
You can embed any of our other pages by the same means.
If you would like the user to be logged into our system while viewing our iframe, please sign them in using SSO (section 10.2 below).
VivoMeetings video conferences can be live-streamed via HTTP & HLS. You can embed our live stream player into your web application or mobile application using an iframe. In your iframe attributes, allow autoplay and full screen so that our live stream player works as intended.
The live stream URL [your-domain].com/livestream/123456 where 123456 is the access code of the meeting room being live-streamed.
Example, to embed our livestream player:
<iframe
allow="fullscreen;autoplay"
src="[your-domain].com/livestream/123456"
/>
You can customize the meeting room to fit your own look and feel with full customization of the branding as well as removing any feature not required. Customization is controlled in two ways. First by using one of the URL parameters below in your iframe src parameter or by requesting to have certain controls hidden.
Optional parameters:
Hiding features from your meeting room:
Most UI controls displayed in the meeting room can be configured to be hidden for specific use cases. To customize the controls available in your meeting room please contact us .
The following controls can be hidden or displayed:
The following image can be used as a key to request which controls you’d like to hide:
Strip layout is an additional optional parameter you can include on an iframe that will render the video conference iframe in a thin bar you can place at the bottom of your application allowing for the rest of the screen to be devoted to your application.
Example, to embed our as a strip for gaming or watch parties:
<iframe
allow="camera;microphone;fullscreen;autoplay"
src="[your-domain].com/conf/call/123456?
strip_layout=true&
skip_join=true”
/>
Example, for a watch party, display volume control and hide most others:
The meeting iframe will post messages about the participant state that your application can catch and act on. The messages that are currently supported relate to the participant leaving the meeting. New messages can be added, let us know what events you care about!
The iframe will post a message like this
window.parent.postMessage({type: ‘vivomeetingsLeaveCallEvent’, reason: ‘left’})
The reason field can have the following values:
Below is some sample code for catching and acting on these events:
Sample code for catching and acting on these events
window.addEventListener("message", event => {
if (event.data.type == 'vivomeetingsLeaveCallEvent' && event.data.reason == 'left') {
// they "left"
}
}, false);
Using the host_id and login_token_public_key available from the host’s endpoints you can log hosts into our application seamlessly, without presenting them with a login screen. Certain UI elements will be hidden from these users, such as the change password and change email address features. Please note that these endpoints should be visited directly by the host/user, not by your server. Therefore you don’t have to provide the API authorization token obtained from 3.0.
To SSO a host in the current browser tab or a new tab, have your page (in the client’s browser) submit a POST request. Hyperlinks submit as GET so to make it a POST you will have to insert the link in a or as a javascript function on your page.
Required parameters:
Optional parameters:
POST "/auth"
Request body (application/json):
{
"host_id": 8,
"login_token_public_key": "a1b2c3d4e5f6",
"redirect_url": "/conf/calls/upcoming",
"after_call_url": "https://en.wikipedia.org"
}
SSO is important when you embed the meeting room in your own application so that the host of the meeting can be recognized by the VivoMeetings platform and display the correct Host controls like End Meeting, Recording, etc. Please contact us before using this feature so that we can set up our response headers to properly authorize your host domains. To SSO through an iframe, use the /auth endpoint as the src attribute of the iframe. Required parameters:
Optional parameters:
<iframe allow="camera;microphone;fullscreen" src="[your-domain].com/auth?host_id=8&login_token_public_key=a1b2c3d4e5f6&redirect_url=/conf/calls/upcoming&after_call_url=https://en.wikipedia.org" />
Become a Partner
Partner Portal
Affiliate Program