This document describes a draft version of Mind API and is subject to change at any time without notice.
Mind API is a cloud platform (aka PaaS) that enables you to build applications where group of people communicate on the Internet using voice and video. For example, you can easily build a standalone application for video conferencing from scratch, or embed audio and video communication capabilities into an existing chat application, and do a lot more. Here is a list of features of Mind API:
Mind API allows you to take a full advantage of described functionality without a need to dive deep into low level details. All the complexity is hidden behind a simple HTTP-based API which can be used directly on the server, but we highly encourage you to stick with one of our SDKs on the client:
Mind API is RESTful and built on top of HTTP. It uses predictable resource URIs and standard HTTP response status codes to indicate errors. The API accepts and returns JSON in the HTTP body. We use standard HTTP methods and authentication which are understood by almost any off-the-shelf HTTP client. We support cross-origin resource sharing, allowing you to interact directly with our API from a client-side web application deployed to its own domain. Mind API uses WebSockets to keep all the parts of your application in sync (they also help tracking the presence of participants).
To demonstrate what you can do with Mind API we have developed a simple web-application for video conferencing. It allows you to create a media room where up to 5 participants can communicate using voice, video and text messages. The room is automatically destroyed in 15 minutes after creation. Try it yourself.
To use Mind API you will need an application ID and a token. For development purpose we suggest you to start with
our free shared application ID 00e1db72-c57d-478c-88be-3533d43c8b34
and corresponding token:
W1VJggwnvg2ldDdvSYES07tpLCWLDlD5nFakVJ6QSCPiZRpAMGyAzKW07OpM1IpceZ2WT5h5Mu7Ekt7WDTQzMUoQkVTRE4NdYUFE
They allow creating unlimited number of conferences with up to 5 participants and up to 15 minutes duration each. These limits should be enough for you to start developing your application. To get an application ID and a token without such limits, please fill out a form here.
Authentication is performed using bearer HTTP authentication scheme,
thereby all HTTP requests to Mind API must include an access token which must be sent in the Authorization
HTTP
request header:
Authorization: Bearer <token>
If the client is unable to set the headers (which is the case for Javascript WebSocket API), the token can be
sent as a value of access_token
HTTP request parameter. Any request without a valid token will return 401 -
Unauthorized
HTTP response status code.
There are two types of accesss tokens: application token and participant token. Application token is requested together with the application ID. Application token gives anyone who is using it a full access to Mind API on behalf of corresponding application. This type of token is required to create and delete conferences, it is intended to be used on server-side code only and should never be exposed in public, i.e. never share your application token in publicly accessible areas such GitHub, client-side code, and so forth.
Participant token is generated whenever your create a new participant in the conference. It can't be used for conference creation or deletion (like application token), but it gives an ability to act on behalf of the corresponding participant, and is intended to be passed to (and used on) a client-side code. Every participant token is tied to a single conference. It invalidates if conference ends or if the participant was expelled from the conference.
Mind API uses conventional HTTP response status codes to indicate whether a specific API request has been
completed successfully of failed. In general, 200
indicates success, 4xx
indicate a failure due to supplied
parameters, and 500
indicates an error on the server-side.
Status Code | Description |
---|---|
200 - OK |
The request was successful and the value (if there is any) was returned. |
400 - Bad Request |
A required attribute of the request is missing or has an invalid value. |
401 - Unauthorized |
No valid token was provided. |
403 - Forbidden |
The request is not allowed, e.g. an attendee participant is not allowed to delete a conference. |
404 - Not Found |
The requested resource doesn't exist. |
415 - Unsupported Media Type |
Unsupported media type was specified in the `Content-Type` HTTP request header. |
500 - Server Error |
Something went wrong on the server-side. |
Mind API uses WebSockets to keep an application and participants* informed of all the changes in the conference, and to track the presence of the participants: if WebSocket connection is opened on behalf of a participant he is considered to be online, otherwise Mind API treats him as offline. This means that any participant has only to open or close WebSocket connection to join or leave the conference, respectively, but you don't have to do it manually on behalf of the participant (i.e. on the client), because SDK will do it for you. For opening WebSocket on behalf of the application (i.e. on the server) — to make it receive notifications — use the following URI:
wss://api.mind.com/<applicationId>/<conferenceId>
WebSocket opening request requires a token. Every WebSocket connection is tied to only one conference. To receive notifications about multiple conferences, your server has to open multiple WebSockets — one for every conference.
A separate notification is sent for every change in the conference. It is sent to everyone except the one who
caused the change. Each notification is a JSON with three attributes: type
, location
and resource
. The
type
attribute can have one of the following values: created
, updated
and deleted
. They correspond to
creation of a new resource and modification and deletion of the existent one, respectively. The location
attribute contains an URI of the affected resource. The URI is relative to the conference, /
URI means the
conference itself. The resource
attribute stores an initial or a new value of the created or updated resource,
respectively. Here is an example of the notification which is sent when a new participant is created:
{
"type": "created",
"location": "/participants/24300bf9-d9f2-4bbf-9719-8660d110bc63",
"resource": {
"id": "24300bf9-d9f2-4bbf-9719-8660d110bc63",
"online": false,
"name": "John Doe",
"role": "speaker",
"media": {
"audio": false,
"video": false
},
"secondaryMedia": {
"audio": false,
"video": false
}
}
}
Usually any WebSocket is closed by the one who has opened it, but it also can be closed at the initiative of the
Mind API: if an online participant is deleted its WebSocket is closed with 4001
code, if an entire conference
is deleted all opened WebSockets tied to the conference are closed with 4000
code. Again, you don't have to
worry of these codes on the client if your use SDK.
* Here we are talking about participants who use Mind API/SDK only. Any participant who has joined the conference using SIP or H.323 receives no notifications, and her presence is tied to the state of the call: she is online till she is on the phone, otherwise she is offline.
Creates a new conference for an application. The creation can be performed by the application only.
applicationId required | object <uuid> (ApplicationId) Example: 00e1db72-c57d-478c-88be-3533d43c8b34 The ID of an application |
Conference parameters
name | string Default: "" |
recordingLayout | string Default: "mosaic" Enum: "mosaic" "selector" |
id | string <uuid> |
name | string |
recording | object (ConferenceRecording) |
{- "name": "Meeting name",
- "recordingLayout": "mosaic"
}
{- "id": "1cf69ae4-4c54-47cf-b409-97e88f62fe12",
- "name": "Meeting name",
- "recording": {
- "layout": "mosaic",
- "started": false
}
}
Returns a conference with the given ID. If detailed
parameter is set to true
then the conference will include a list of all participants. The list is ordered according to the same rules which apply when listing participants. If detailed
parameter is omitted or explicitly set to false
then the conference will not contain participants
list.
applicationId required | object <uuid> (ApplicationId) Example: 00e1db72-c57d-478c-88be-3533d43c8b34 The ID of an application |
conferenceId required | object <uuid> (ConferenceId) Example: 1cf69ae4-4c54-47cf-b409-97e88f62fe12 The ID of a conference |
detailed | boolean Default: false Specifies if returned conference should include a list of all participants or not |
id | string <uuid> |
name | string |
recording | object (ConferenceRecording) |
participants | Array of objects (Participant) Nullable Included only if |
{- "id": "1cf69ae4-4c54-47cf-b409-97e88f62fe12",
- "name": "Meeting name",
- "recording": {
- "layout": "mosaic",
- "started": false
}, - "participants": [
- {
- "id": "24300bf9-d9f2-4bbf-9719-8660d110bc63",
- "online": true,
- "name": "John Doe",
- "role": "speaker",
- "layout": "mosaic",
- "media": {
- "audio": true,
- "video": true
}, - "secondaryMedia": {
- "audio": true,
- "video": true
}
}
]
}
Deletes a conference with a given ID. The deletion assumes expelling of all the participants and deleting all the data tied with the conference. The deletion can be performed either by application which created it or by any conference participants who has corresponding permission granted.
applicationId required | object <uuid> (ApplicationId) Example: 00e1db72-c57d-478c-88be-3533d43c8b34 The ID of an application |
conferenceId required | object <uuid> (ConferenceId) Example: 1cf69ae4-4c54-47cf-b409-97e88f62fe12 The ID of a conference |
Modifies parameters of a conference with a given ID. The conference parameters can be modified either by an application which created it or by any conference participant who has corresponding permission granted.
applicationId required | object <uuid> (ApplicationId) Example: 00e1db72-c57d-478c-88be-3533d43c8b34 The ID of an application |
conferenceId required | object <uuid> (ConferenceId) Example: 1cf69ae4-4c54-47cf-b409-97e88f62fe12 The ID of a conference |
name | string Nullable |
id | string <uuid> |
name | string |
recording | object (ConferenceRecording) |
{- "name": "Modified meeting name"
}
{- "id": "1cf69ae4-4c54-47cf-b409-97e88f62fe12",
- "name": "Meeting name",
- "recording": {
- "layout": "mosaic",
- "started": false
}
}
Subscribe a calling participant to the conference media. If the participant is already subscribed to the conference media it will be resubscribed with the specified parameters.
applicationId required | object <uuid> (ApplicationId) Example: 00e1db72-c57d-478c-88be-3533d43c8b34 The ID of an application |
conferenceId required | object <uuid> (ConferenceId) Example: 1cf69ae4-4c54-47cf-b409-97e88f62fe12 The ID of a conference |
sdp | string |
sdp | string |
{- "sdp": "v=0\no=- 435746465422294 1 IN IP4 0.0.0.0\ns=-\nt=0 0\na=group:BUNDLE audio video\na=msid-semantic:WMS 805e4df9-3e77-43c3-ae3c-b241023bd3ee\na=ice-options:trickle\nm=audio 9 UDP/TLS/RTP/SAVPF 111\nc=IN IP4 0.0.0.0\na=mid:audio\na=msid:805e4df9-3e77-43c3-ae3c-b241023bd3ee d1792305-16a4-4558-8b7b-869bdb50c70f\na=rtcp:9 IN IP4 0.0.0.0\na=rtcp-mux\na=sendrecv\na=rtpmap:111 opus/48000/2\na=fmtp:111 minptime=10;useinbandfec=1\na=ssrc:1144085914 cname:Ird0ziC5R1aJNIFbYoWBuw\na=ice-ufrag:XR2q\na=ice-pwd:d0+3J62t/LQw5zKDqoWOPnkX\na=ice-options:trickle\na=fingerprint:sha-256 8B:47:3A:61:FE:78:E3:73:E9:BE:5D:8B:4A:22:15:0B:81:EE:20:18:72:A1:BB:0C:B1:51:7D:40:59:31:0A:A2\na=setup:active\nm=video 9 UDP/TLS/RTP/SAVPF 96 108 124\nc=IN IP4 0.0.0.0\na=mid:video\na=msid:805e4df9-3e77-43c3-ae3c-b241023bd3ee a5615fa7-aae3-4e9f-b4ee-b1d4af40199e\na=rtcp:9 IN IP4 0.0.0.0\na=rtcp-mux\na=rtcp-rsize\na=sendrecv\na=rtpmap:96 VP8/90000\na=rtpmap:108 red/90000\na=rtpmap:124 ulpfec/90000\na=extmap:2 urn:ietf:params:rtp-hdrext:toffset\na=extmap:3 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time\na=rtcp-fb:96 ccm fir\na=rtcp-fb:96 nack\na=rtcp-fb:96 nack pli\na=rtcp-fb:96 goog-remb\na=ssrc:3074292572 cname:Ird0ziC5R1aJNIFbYoWBuw\na=ice-ufrag:XR2q\na=ice-pwd:d0+3J62t/LQw5zKDqoWOPnkX\na=ice-options:trickle\na=fingerprint:sha-256 8B:47:3A:61:FE:78:E3:73:E9:BE:5D:8B:4A:22:15:0B:81:EE:20:18:72:A1:BB:0C:B1:51:7D:40:59:31:0A:A2\na=setup:active\n"
}
{- "sdp": "v=0\no=- 435746465422294 1 IN IP4 0.0.0.0\ns=-\nt=0 0\na=group:BUNDLE audio video\na=msid-semantic:WMS 805e4df9-3e77-43c3-ae3c-b241023bd3ee\na=ice-options:trickle\nm=audio 9 UDP/TLS/RTP/SAVPF 111\nc=IN IP4 0.0.0.0\na=mid:audio\na=msid:805e4df9-3e77-43c3-ae3c-b241023bd3ee d1792305-16a4-4558-8b7b-869bdb50c70f\na=rtcp:9 IN IP4 0.0.0.0\na=rtcp-mux\na=sendrecv\na=rtpmap:111 opus/48000/2\na=fmtp:111 minptime=10;useinbandfec=1\na=ssrc:1144085914 cname:Ird0ziC5R1aJNIFbYoWBuw\na=ice-ufrag:XR2q\na=ice-pwd:d0+3J62t/LQw5zKDqoWOPnkX\na=ice-options:trickle\na=fingerprint:sha-256 8B:47:3A:61:FE:78:E3:73:E9:BE:5D:8B:4A:22:15:0B:81:EE:20:18:72:A1:BB:0C:B1:51:7D:40:59:31:0A:A2\na=setup:active\nm=video 9 UDP/TLS/RTP/SAVPF 96 108 124\nc=IN IP4 0.0.0.0\na=mid:video\na=msid:805e4df9-3e77-43c3-ae3c-b241023bd3ee a5615fa7-aae3-4e9f-b4ee-b1d4af40199e\na=rtcp:9 IN IP4 0.0.0.0\na=rtcp-mux\na=rtcp-rsize\na=sendrecv\na=rtpmap:96 VP8/90000\na=rtpmap:108 red/90000\na=rtpmap:124 ulpfec/90000\na=extmap:2 urn:ietf:params:rtp-hdrext:toffset\na=extmap:3 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time\na=rtcp-fb:96 ccm fir\na=rtcp-fb:96 nack\na=rtcp-fb:96 nack pli\na=rtcp-fb:96 goog-remb\na=ssrc:3074292572 cname:Ird0ziC5R1aJNIFbYoWBuw\na=ice-ufrag:XR2q\na=ice-pwd:d0+3J62t/LQw5zKDqoWOPnkX\na=ice-options:trickle\na=fingerprint:sha-256 8B:47:3A:61:FE:78:E3:73:E9:BE:5D:8B:4A:22:15:0B:81:EE:20:18:72:A1:BB:0C:B1:51:7D:40:59:31:0A:A2\na=setup:active\n"
}
Returns a recording of a conference with given ID as MP4 file.
applicationId required | object <uuid> (ApplicationId) Example: 00e1db72-c57d-478c-88be-3533d43c8b34 The ID of an application |
conferenceId required | object <uuid> (ConferenceId) Example: 1cf69ae4-4c54-47cf-b409-97e88f62fe12 The ID of a conference |
Starts or resumes recording of a conference.
applicationId required | object <uuid> (ApplicationId) Example: 00e1db72-c57d-478c-88be-3533d43c8b34 The ID of an application |
conferenceId required | object <uuid> (ConferenceId) Example: 1cf69ae4-4c54-47cf-b409-97e88f62fe12 The ID of a conference |
Stops or pauses recording of a conference.
applicationId required | object <uuid> (ApplicationId) Example: 00e1db72-c57d-478c-88be-3533d43c8b34 The ID of an application |
conferenceId required | object <uuid> (ConferenceId) Example: 1cf69ae4-4c54-47cf-b409-97e88f62fe12 The ID of a conference |
Sends a new message to a conference (i.e. to all participant of the conference) or a specific participant or the application
applicationId required | object <uuid> (ApplicationId) Example: 00e1db72-c57d-478c-88be-3533d43c8b34 The ID of an application |
conferenceId required | object <uuid> (ConferenceId) Example: 1cf69ae4-4c54-47cf-b409-97e88f62fe12 The ID of a conference |
sendTo required | string <uuid> The addressee of the message. It can be the ID of a participant or the ID of the application or (if you want to send the message to the application and to all participants at once) the ID of the conference |
text required | string |
id | string <uuid> |
sentTo | string <uuid> |
sentBy | string <uuid> |
sentAt | string <date-time> |
text | string |
{- "sendTo": "1cf69ae4-4c54-47cf-b409-97e88f62fe12",
- "text": "Message text"
}
{- "id": "3f09f6e0-3712-4485-9edf-7af1807b3617",
- "sentTo": "1cf69ae4-4c54-47cf-b409-97e88f62fe12",
- "sentBy": "24300bf9-d9f2-4bbf-9719-8660d110bc63",
- "sentAt": 1516883710000,
- "text": "Message text"
}
Returns a list of all participants in the conference with the specified ID. The participants are returned in no particular order and there is no guarantee that the order will remain constant over time, but if the list is requested by a participant then it is guaranteed that the participant takes the first place in the list.
applicationId required | object <uuid> (ApplicationId) Example: 00e1db72-c57d-478c-88be-3533d43c8b34 The ID of an application |
conferenceId required | object <uuid> (ConferenceId) Example: 1cf69ae4-4c54-47cf-b409-97e88f62fe12 The ID of a conference |
id | string <uuid> |
online | boolean |
name | string |
role | string Enum: "moderator" "speaker" "attendee" |
layout | string Enum: "mosaic" "selector" |
media | object (Media) |
secondaryMedia | object (Media) |
[- {
- "id": "24300bf9-d9f2-4bbf-9719-8660d110bc63",
- "online": true,
- "name": "John Doe",
- "role": "speaker",
- "layout": "mosaic",
- "media": {
- "audio": true,
- "video": true
}, - "secondaryMedia": {
- "audio": true,
- "video": true
}
}
]
Creates a new conference participant. Only application is permitted to performed this operation.
applicationId required | object <uuid> (ApplicationId) Example: 00e1db72-c57d-478c-88be-3533d43c8b34 The ID of an application |
conferenceId required | object <uuid> (ConferenceId) Example: 1cf69ae4-4c54-47cf-b409-97e88f62fe12 |