Coviu provides a session based API for creating and restricting access to coviu calls. The core concepts exposed are
- Session: A coviu call that occurs between two or more parties at a specified time, and has a finite duration.
- Participants: Users who may participate in a coviu call.
Participants join a call by following a session link in their browser, or mobile app. The session link identifies the participant, including their name, optional avatar, and importantly their role. As such, it is important that each person joining the call be issued a different session link, i.e. have a distinct participant created for them. A participant's role identifies whether that user may access the call directly, or if they are required the be let in by an existing participant.
Add this dependency to your project's POM:
<dependency>
<groupId>com.coviu</groupId>
<artifactId>coviu-sdk</artifactId>
<version>0.1.0</version>
</dependency>The full set of api documentations is available in the api directory. There's also a working example in the examples directory
A session can be created by constructing a SessionCreationRequest with a start and end time.
import com.coviu.core.*;
import com.coviu.core.auth.*;
import com.coviu.sessions.model.*;
import com.coviu.sessions.api.SessionApi;
import org.joda.time.DateTime;
public class SessionApiExample {
public static void main(String[] args) {
ApiClient client = new ApiClient();
client.setCredentials("myApiKey", "myApiKeySecret", null);
SessionApi api = new SessionApi(client);
// Create a session that starts in an hour and finishes an hour later.
SessionCreationRequest scr = new SessionCreationRequest()
.startTime(DateTime.now().plusHours(1))
.endTime(DateTime.now().plusHours(2));
try {
Session s = api.createSession(scr);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling SessionApi#addSessionParticipant");
e.printStackTrace();
}
}
}Example output
class Session {
featureFlags: []
sessionId: 32c22a74-bc97-4d06-a0c2-ef8d502258c2
teamId: e1bbc77f-5312-4e82-b3c0-b629c22aeb50
clientId: 2a6a7b2c-2f44-4410-ad18-531f942d9453
participants: []
picture: null
startTime: 2017-02-15T11:57:40.664+11:00
endTime: 2017-02-15T12:57:40.664+11:00
canceledTime: null
sessionName: null
}
In order for a call to take place, you will need to add two or more participants to the session
// ...
ParticipantCreationRequest r = new ParticipantCreationRequest()
.displayName("Joe")
.role("host");
try {
Participant p = api.addSessionParticipant(s.getSessionId(), r);
Session s2 = api.getSessionById(s.getSessionId(), false);
System.out.println(s2);
} catch (ApiException e) {
//...
}
class Session {
featureFlags: []
sessionId: 8627196e-0a86-4527-b606-f11838dc258d
teamId: 34aaeb76-0d41-4135-aac4-6c629a6999d5
clientId: 47eaf1b7-cc72-4d74-a543-578bba0bde3b
participants: [class Participant {
sessionId: 8627196e-0a86-4527-b606-f11838dc258d
state: ciz66y7dl000ltz68z9mfm09j
displayName: Joe
participantId: 0df16821-a1de-4ba0-9613-3fddd3e97e2e
clientId: 47eaf1b7-cc72-4d74-a543-578bba0bde3b
role: HOST
picture: null
deletedAt: null
coviuUserId: null
entryUrl: http://dev.localhost:3000/session/0df16821-a1de-4ba0-9613-3fddd3e97e2e
}]
picture: null
startTime: 2017-02-15T12:00:26.014+11:00
endTime: 2017-02-15T13:00:26.016+11:00
canceledTime: null
sessionName: null
}
Notice that we constructed a HOST, by setting the .role("host"). This means our participant may join the call directly, without
the having to ring. Possible values for role are host and guest. Values are not case sensitive.
If no value is set, the role defaults to guest.
Note that it is also possible to add participants directly to the session when you're creating the session by adding them with addParticipantsItem to the SessionCreationRequest.
ParticipantCreationRequest pcr = new ParticipantCreationRequest()
.displayName("Joe")
.role("host");
SessionCreationRequest scr = new SessionCreationRequest()
.startTime(DateTime.now().plusHours(1))
.endTime(DateTime.now().plusHours(2))
.addParticipantsItem(pcr);It's possible to recover a list of sessions that have been booked, held, deleted etc. Sessions are returned one page at a time.
SessionApi api = new SessionApi(client);
Integer page = 0; // Integer | The page number to return
Integer pageSize = 200; // Integer | The number of sessions per page. Max 200. Default 200.
DateTime startTime = DateTime().now(); // DateTime | Includes sessions that start at or after start_time.
DateTime endTime = DateTime().now().plusDays(30); // DateTime | Include sessions that start upto and including end_time..
Boolean includeCanceled = false; // Boolean | Includes sessions that have been canceled.
Boolean deletedParticipants = false; // Boolean | Also include participants that have been removed from the session.
String state = null; // String | Return only sessions containing participants with the supplied state value.
String order = null; // String | Order the results. forward returns oldest first by start time. backwards includes newest first by startime.
try {
SessionPage result = api.getSessionPage(page, pageSize, startTime, endTime, includeCanceled, deletedParticipants, state, order);
System.out.println(result);
} catch (ApiException e) {
//...
}A session may be updated by e.g. changing the start and end times, or setting name for the session
SessionUpdateRequest update = new SessionUpdateRequest()
.startTime(DateTime.now().plusDays(1).plusHours(1))
.endTime(DateTime.now().plusDays(1).plusHours(2))
.sessionName("Fun time with coviu");
Session s2 = api.updateSession(s.getSessionId(), update);A session may also be canceled, meaning it will no longer take place, no new participants can be added or removed, no updates can be applied. This operation can not be undone.
api.deleteSession(s.getSessionId());Coviu uses OAuth2 for controlling access to resources. The coviu java sdk takes care of recovering, using, and refreshing access tokens. There are two use cases for access the coviu api. Firstly you may wish to access the api on behalf of the owner of the client credentials, that is to say follow the flow for the client credentials grant outlined in https://tools.ietf.org/html/rfc6749#section-4.4. In this situation, you only need to supply the sdk with your credentials. Your account may incur charges for sessions held.
ApiClient c = new ApiClient();
// Null for the `authorization` parameter will result in the sdk
// attempting to recover an authorization for the owner of the key and secret.
c.setCredentials(key, secret, null);The second approach follows the flow for OAuth2 authorization code grant https://tools.ietf.org/html/rfc6749#section-4.1. Once an authorization code has been obtained for a user, it may be used to obtained an authorization for that user. This approach wil incur no charges to you, but may result in charges for the user, depending on their account type.
See instructions on setting up your account for allowing the oauth2 authorization code grant.
ApiClient c = new ApiClient();
// Initially we need to act as ourselves.
c.setCredentials(key, secret, null);
// Use the authorization code to obtain an authorization for the user
String authorization = c.useAuthorizationCode("auth code ...");
// Start to use this authorization
c.setAuthorization(authorization);
// Or create a new Client
ApiClient c2 = new ApiClient();
c.setCredentials(key, secret, authorization);
// Create a session for that user.
SessionApi api = new SessionApi(c);
Session session = api.createSession(scr);Regardless of which approach you take, you'll want to detect when your access token has been refreshed, and store that for next time.
ApiClient c = new ApiClient();
c.setAuthorizationObserver(new ApiClient.AuthorizationObserver(){
public void observe(String authorization) {
// Store this authorization for later.
}
});It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.