Getting Started
Requests in general
Relay exposes an HTTPS REST server.
The base URL is https://relay.bluejeans.com/api/.
Requests and responses use JSON to encode their bodies. Make sure you send a Content-Type: application/json header on requests that have bodies.
Authentication is provided by Basic Auth or Access Tokens. Here's a Basic Auth example.
Suppose your username is
swordfishand your password istxburocks.Encode your credentials:
base64("swordfish:txburocks")→c3dvcmRmaXNoOnR4YnVyb2Nrcw==.Use the base64 result in this header for each request:
Authorization: Basic c3dvcmRmaXNoOnR4YnVyb2Nrcw==.
Listing endpoints
This will return a list of all endpoints that have been provisioned in your enterprise. Endpoints must be provisioned before they can be dialed from Relay.
GET https://relay.bluejeans.com/api/endpoints HTTP/1.1
Authorization: Basic c3dvcmRmaXNoOnR4YnVyb2Nrcw==
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": "4fb18e00e4b0378e4f3e5858",
"name": "Boardroom",
"ipAddress": "10.4.9.146",
"port": 443,
"listenerServiceId": "527ca9e2776a7e02dd2e15fe",
"controlProtocol": "POLYCOM_HTTP_REALPRESENCE",
"signalingProtocol": "H323",
"dialStyle": "ANNEX_O",
"addressStyle": "IP_ADDRESS",
"username": "admin",
"password": null,
"calendarId": "bluejeansnet.com_2d3437363932363533392533@resource.calendar.google.com",
"calendarType": "GOOGLE"
}
]
(endpoints.list documentation, Endpoint entity documentation)
Now we know that the Boardroom endpoint has an id of 4fb18e00e4b0378e4f3e5858, in addition to the IP address and other provisioning information.
Note: The password field will always appear as null, even if a password has been set.
Provisioning endpoints
We currently have one endpoint provisioned. Let's add another one, Cool Runnings (a LifeSize Express 220 with a Jamaican bobsled wallpaper).
A. Create
This will register a new endpoint with Relay. It will be able to place calls with default settings, and will have no calendar.
Assume that the Listener Service 527ca8e2776a7e02dd2e15fe has already been installed and provisioned.
POST https://relay.bluejeans.com/api/endpoints HTTP/1.1
Authorization: Basic c3dvcmRmaXNoOnR4YnVyb2Nrcw==
Content-Type: application/json
{
"name": "Cool Runnings",
"ipAddress": "10.4.4.125",
"listenerServiceId": "527ca8e2776a7e02dd2e15fe",
"controlProtocol": "LIFESIZE_SSH",
"username": "auto",
"password": "lifesize"
}HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "5452bb63e4b0b248931bce5d",
"name": "Cool Runnings",
"ipAddress": "10.4.4.125",
"port": null,
"listenerServiceId": "527ca8e2776a7e02dd2e15fe",
"controlProtocol": "LIFESIZE_SSH",
"signalingProtocol": null,
"dialStyle": null,
"addressStyle": null,
"username": "auto",
"password": null,
"calendarId": null,
"calendarType": null
}(endpoints.insert documentation, Endpoint entity documentation)
The response contains all optional fields filled in with default values. Password is always returned as null, even if it's set.
B. Update
You can modify existing provisioning information for an endpoint. You can choose whether you want to send all the fields of the endpoint again, or just the ones that changed.
Assume that Cool Runnings changed IP addresses from 10.4.4.125 to 10.4.4.236, and we want to tie the endpoint to a room resource calendar in Google Calendar.
To re-send the entire JSON body, use endpoints.update:
POST https://relay.bluejeans.com/api/endpoints/5452bb63e4b0b248931bce5d HTTP/1.1
Authorization: Basic c3dvcmRmaXNoOnR4YnVyb2Nrcw==
Content-Type: application/json
{
"id": "5452bb63e4b0b248931bce5d",
"name": "Cool Runnings",
"ipAddress": "10.4.4.236",
"port": null,
"listenerServiceId": "527ca8e2776a7e02dd2e15fe",
"controlProtocol": "LIFESIZE_SSH",
"signalingProtocol": null,
"dialStyle": null,
"addressStyle": null,
"username": "auto",
"password": "lifesize",
"calendarId": "bluejeansnet.com_glpvpaukd87pna8u0680kjomd8@group.calendar.google.com",
"calendarType": "GOOGLE"
}HTTP/1.1 200 OK
// same response format as endpoints.insert aboveTo send only the fields that changed, use endpoints.patch:
PATCH https://relay.bluejeans.com/api/endpoints/5452bb63e4b0b248931bce5d HTTP/1.1
Authorization: Basic c3dvcmRmaXNoOnR4YnVyb2Nrcw==
Content-Type: application/json
{
"ipAddress": "10.4.4.236",
"calendarId": "bluejeansnet.com_glpvpaukd87pna8u0680kjomd8@group.calendar.google.com",
"calendarType": "GOOGLE"
}HTTP/1.1 200 OK
// same response format as endpoints.insert aboveReading calendars
Show our Endpoint's meetings near the current time (looks backwards in time 30 minutes to the meetings's end time, and looks forward 14 hours into the future for the meeting's start time):
GET https://relay.bluejeans.com/api/meetings?endpoint=5452bb63e4b0b248931bce5d HTTP/1.1
Authorization: Basic c3dvcmRmaXNoOnR4YnVyb2Nrcw==HTTP/1.1 200 OK
Content-Type: application/json
[
{
"calendarEventId": "aackik07sucq77q6mqa2up1cso",
"calendarType": "GOOGLE",
"cluster": "PROD",
"description": "Join my meeting using https:\/\/bluejeans.com\/10990",
"endTime": 1414707507095,
"endpointIds": [ "5452bb63e4b0b248931bce5d" ],
"id": "539837779bab9338fa9a6a3e",
"meetingId": "10990",
"organizer": "ben@bluejeansnet.com",
"passcode": null,
"startTime": 1414703907095,
"title": "My Personal Meeting"
}
](meetings.list documentation, Meeting entity documentation)
This tells us that Cool Runnings' calendar contains one event near the time of the request.
The event has a title of My Personal Meeting and a description of Join my meeting using http://bluejeans.com/10990. The server has extracted the Blue Jeans meeting URL information to provide the meetingId 10990 and passcode null.
If the meetingId is null, that means there was no Blue Jeans meeting URL in the calendar invitation's description or location fields.
Dialing into a meeting
Now that we have an endpoint and a meeting, we can dial into a Blue Jeans meeting.
Suppose our meeting ID is 10990 and that the meeting is passcodeless (no passcode for guests) and moderatorless (meeting will start when any guests join; no moderators are required to join).
A. Check your passcode (optional)
Before sending the dial command to the endpoint, you can make an API request to check whether the given passcode would result in a successful call.
This will catch cases where the user supplied an invalid passcode, no passcode at all, or their passcode is fine but the meeting cannot start yet because no moderator has joined, so maybe the user wants to enter a moderator passcode to start the meeting.
Regardless of the response of this check, you can always issue the join request — this is an advisory check only.
GET https://relay.bluejeans.com/api/meetings/10990/joinflow HTTP/1.1
Authorization: Basic c3dvcmRmaXNoOnR4YnVyb2Nrcw==HTTP/1.1 200 OK
Content-Type: application/json
"JOIN_NOW"(meetings.joinflow documentation)
Now we know that our given meeting ID and lack of a passcode is valid and will take us straight into a meeting, instead of getting stuck at an IVR for an invalid passcode.
B. Join
Okay, enough preparation, let's dial this thing.
POST https://relay.bluejeans.com/api/endpoints/5452bb63e4b0b248931bce5d/join?meetingid=10990 HTTP/1.1
Authorization: Basic c3dvcmRmaXNoOnR4YnVyb2Nrcw==HTTP/1.1 204 No Content(endpoints.join documentation)
The 204 response means that the endpoint started dialing. If there was an error, such as an incorrect endpoint password or an offline endpoint, the response would have a 500 status code and a JSON body with error details.
If this step fails, here are some places to check:
Endpoint's call history: does the dial string look correct?
Listener Service logs: did the endpoint respond to our HTTP/SSH command with an error or malformed response?
Endpoint's admin interface: can you log in to the Endpoint's web-based administrative with the same credentials and dial from there?
H.323/SIP gateway logs: did the dial string get transformed into an invalid format? You may need a custom DialStyle.
Blue Jeans H.323/SIP connector logs: I'm so sorry.
C. Hang up
POST https://relay.bluejeans.com/api/endpoints/5452bb63e4b0b248931bce5d/hangup HTTP/1.1
Authorization: Basic c3dvcmRmaXNoOnR4YnVyb2Nrcw==HTTP/1.1 204 No Content