Callbridge Partner Embedded Video Conference Developer Guide
Callbridge embeddable video and voice conference is an easy-to-implement video conference API. Embed video conference and call into your existing application or website with a few lines of code.
Technical Architecture
iotum Communications Cloud (ICC) is a real-time communications tool commercialized as a white-label product for partners to deploy their own branded version. iotum retails parts of the solution under the brands Callbridge, FreeConference.com and Talkshoe. Most often, white-label solutions follow the Callbridge 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 iotum’s 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.
High-Level Architecture
ICC is a cloud-based, multi-tenant solution that provides scale and security.
Below is a diagram outlining a high-level view of system architecture.
Global Network
The Iotum 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.
Iotum currently has POPs in the following countries:
- United States
- Canada
- Germany
- Mumbai
- Hong Kong
- Sydney
General Information
Callbridge.com API vs. Full Whitelabel implementation
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, Callbridge.com.
Callbridge APIs and Embedded video conference can be used directly on Callbridge.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 video API on Callbridge.com developers can manage Host accounts under a single Company and Embed video conferences and calls 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.
Request method/format
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 method/format
Response HTTP status code will indicate the overall status of the request:
- 200 – the request succeeded
- 401 – for Authenticate, that the supplied credentials are invalid; for other methods, that the auth_token parameter is missing, or that the associated session has expired (use Authenticate to get a new auth_token)
- 403 – attempting to act on objects beyond the scope of one’s role (Reseller Admin beyond the current Reseller, Company Admin beyond the current Company)
- 404 – update, delete, and similar methods attempted where the indicated object does not exist
- 500 – internal server error
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.
Roles
- Host – may host conferences only.
- Company Admin – may host conferences, and via the web interface or this API, add/edit/delete hosts in his/her own Company.
- Reseller Admin – may host conferences, and via the web interface or this API, add companies, manipulate subscriptions, and add/delete/hosts in any of the Reseller’s Companies.
Authentication
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.)
Authenticate
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"
}
Request:
- email: the email of a host in that company that has the ResellerAdmin or CompanyAdmin role
- password: password for the said host
Response:
- auth_token: The token to be included with all subsequent requests, as described in the General section above. An auth_token expires five minutes after its last successful use in any of the methods below (i.e. it is ‘touched’ on each use).
Create a Company
Only full Whitelabel partners need to create companies. Developers using the video conference API on callbridge.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:
- subdomain: Every company has a subdomain that is used in their meeting URLs, i.e iotum.callbridge.com. The subdomain must be unique within the scope of each reseller domain.
- name: The name of the company as it should be displayed for billing purposes
- openid_provider: (optional) If this company is an OpenID-connect authentication provider, we will send users through your auth instead of our own. Please contact us before using this feature.
Response:
- id: id of the resulting new company
Create a Meeting Host
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:
- company_id: The id of the company you wish to add the Host to. (Required when the API consumer is a Reseller Admin; ignored when a Company Admin: host will be created in Company Admin’s own company)
- name: The name of the Host that will be displayed when joining meetings.
- email: The email address of the Host. This will be used for invitations and reminders as well as authentication.
- password: optional, to set on creation
- no_welcome_email: whether to not send the host a welcome email (optional, boolean, should probably be used with the above, and/or see password_creation_link in the Response)
- role: one of RESELLER_ADMIN, COMPANY_ADMIN, HOST – Only Reseller Admins can grant the Reseller Admin role; Reseller and Company Admins can grant the Company Admin or Host roles. Defaults to HOST if omitted.
- openid_sub: Optional. the OpenID subject identifier used for OAuth logins using your system rather than our login infrastructure. If your platform does not support OpenID OAuth, please ignore this parameter.
- moderator_pin: optional. Providing this parameter will request a custom moderator pin for this account. If the number is already taken, the request will fail. If omitted, a number will be generated automatically.
- access_code: optional. Providing this parameter will request a custom access code for this account. If the number is already taken, the request will fail. If omitted, a number will be generated automatically.
- subscription_ids: Optional. The list of subscription ids that defines which products the host is subscribed to.
- Providing this property will set the host’s subscriptions to the exact list provided. This means you can unsubscribe hosts from their subscriptions by omitting specific ids or by providing an empty array.
- If this property is omitted, the host’s existing subscriptions will be left intact.
- IMPORTANT: The host limit for each subscription will automatically be incremented if required so that the host limit remains greater than or equal to the number of hosts assigned to each subscription. Except in the case where hosts limit changes have been locked for the company, in which case an exception is raised.
- NOTE:
- Instead of passing subscription_ids, you can alternatively pass the following two optional arguments:
- plan_slug the slug of the plan to assign the host to.
- add_on_slugs: an array of product slugs of add-ons to assign the host to.
- Instead of passing subscription_ids, you can alternatively pass the following two optional arguments:
Response:
- host_id: The unique id of the host. This should be stored for all future API calls on that host.
- name: The name of the Host that will be displayed when joining meetings.
- email: The email address of the Host. This will be used for invitations and reminders as well as authentication.
- primary_dialin_number: The default dial-in number for the Host’s meeting invitations and reminders.
- meeting_url: The meeting url is the web location of the Host’s meeting room
- role: one of RESELLER_ADMIN, COMPANY_ADMIN, HOST
- access_code: to be used by non-moderator conference participants (access_code is an object; .number is the actual access code)
- moderator_pin: to be used by moderator (moderator_pin is an object; .number is the actual moderator_pin)
- password_creation_link: can be sent by resellers themselves to new hosts to allow setting a password (most useful in conjunction with no_welcome_email: true in the request)
- login_token_public_key: this is what you will need to submit to us to use our SSO feature. See section 8.0 for details.
- subscription_ids: An array of integers identifying the plan/add-on subscriptions that the host is currently assigned to.
Schedule a Meeting
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:
- host_id: unique identifier of the host
- subject: Subject
- agenda: Agenda
- start: Start time, this works in conjunction with the time_zone to set the correct time.
- time_zone: Time zone associated with the start time.
- duration: In minutes.
- auto_record: Optional. Indicates whether the conference should be recorded automatically and the format, allowable values are: none, audio, video. If omitted will default to none.
- auto_transcribe: Optional. Whether the recording should automatically be transcribed. Valid values are true or false. If omitted will default to false.
- one_time_access_code: true or false, when set to true an access code will be returned in the response.
- security_pin: Pin required to access the conference
- mute_mode: Optional. Sets the initial participant mute settings. Options are:
- conversation – Default, all unmuted
- q&a – Participants muted, but can unmute
- presentation – Participants muted and can not unmute if omitted will default to the conversation.
- participants: List of contact IDs to be included as participants.
- participant_emails: Alternatively participants can be listed via emails with moderators specified. If a participant’s email is not on the host’s contact list, it will be added:
POST "/enterprise_api/conference/create"
Request body (application/json):
{
"participant_emails": [
{“email”: “bob@iotum.com”, “moderator”: true},
{“email”: “alice@iotum.com”, “moderator”: false}
]
}
Response:
- conference_id: id of the conference
- subject: Subject
- agenda: Agenda
- start: Start time, this works in conjunction with the time_zone to indicate the correct time.
- end_time: The scheduled end time, according to the specified duration.
- active: Whether the call is active (is scheduled for the current time or has live participants)
- time_zone: Time zone associated with the start time.
- duration: In minutes.
- auto_record: Indicates whether the conference should be recorded automatically and the format.
- auto_transcribe: Whether the recording will be transcribed automatically.
- one_time_access_code: When the request has one_time_access_code set to true this field contains the conference access code.
- security_pin: Pin required to access the conference.
- mute_mode: The initial participant mute settings.Values as per the request.
- participants: List of participants in the conference, note the organizer is always included in the list.
- moderators: List of moderators in the conference
Embed A Video Conference
You can embed Callbridge’s video conference in your own web application or native mobile application.
Embed video conference in a web application or website
You can embed any of the pages visible on Callbridge 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 video conference:
<iframe
allow="camera;microphone;fullscreen;autoplay"
src="[your-domain].com/conf/call/123456?
name=Steve+Irwin&
skip_join=true”
/>
Example, to embed our video conference 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).
Embed a live stream player
Callbridge video conferences can be live-streamed via HTTP & HLS. You can embed our live stream player for video conferencing 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 for video calls and chats:
<iframe
allow="fullscreen;autoplay"
src="[your-domain].com/livestream/123456"
/>
Customizing the meeting room
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:
- name: string. If you provide this parameter when linking directly to a meeting room, the user will not be prompted to enter a name.
- skip_join: true/false. If you provide this parameter when linking directly to a meeting room, the user will not be presented with the video/audio device selection dialog. Instead, they will join the meeting using their system’s default camera and microphone.
- observer: true/false. Join the video room but have your camera off and this participant will not have a video tile displayed to others. They can still hear and be heard by others.
- mute:mic,camera. If you want to mute either the camera or microphone by default when joining the participant into the meeting room use this comma-delimited list. You can pass either ‘camera’, ‘mic’ or both ‘camera, mic’.
- view:gallery,bottom_speaker,left_side_speaker. The default view for meetings is gallery view. You can override this by specifying ‘bottom_speaker’ or ‘left_side_speaker’. ‘bottom_speaker’ is the preferred view for 1 on 1 video chats.
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:
- Screen Sharing
- Whiteboard
- Record
- Output volume
- Text Chat
- Participants
- Mute All
- Meeting Info
- Settings
- Full Screen
- Gallery View
- Connection Quality
The following image can be used as a key to request which controls you’d like to hide:
Customizations for Gaming and Watch Parties
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:
Meeting events
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: ‘iotumLeaveCallEvent’, reason: ‘left’})
The reason field can have the following values:
- ‘left’ – the user clicked the hangup button.
- ‘kicked’ – the user was removed by the moderator or host.
- ‘blocked’ – the user was removed by the moderator or host and is blocked from rejoining.
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 == 'iotumLeaveCallEvent' && event.data.reason == 'left') {
// they "left"
}
}, false);
Signing in on behalf of Hosts (SSO)
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.
SSO via POST (current tab or new tab)
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.
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"
}
<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" />
