Javascript Client¶

The Sift object is the entry point into the Sift VOIP library. It is available as a global when you include the Sift javascript file.

Callbacks¶

Sift.onAuthenticated¶

type:	`Function()`

Callback function that is invoked when authentication is successful. After calling Sift.authenticate on the Sift object with a valid token, the State will change to “authenticated” and this function will be called.

Sift.onAuthenticated = function() {
    console.log("authentication succeeded");

    // it is safe to call connect at this point.
    Sift.connect();
}

Sift.onIncomingCall¶

type:	`Function()`

Callback function for handling inbound calls. The client should call either Sift.answer or Sift.decline to handle the incoming call.

The answer or decline function need not be called before the function exits, but the caller will continue to hear a ringback tone until answer or decline is called. Only one of the two functions should be called in response to a single onIncomingCall request.

Sift.onIncomingCall = function() {
    if (confirm("Answer incoming call?")) {
        Sift.answer();
    } else {
        Sift.decline();
    }
}

Sift.onConnected¶

type:	`Function()`

Called when a voice connection is successfully established. This can happen as the result of a call to Sift.connect or Sift.answer.

Sift.onConnected = function() {
    console.log("Connection established!");
}
Sift.connect();

Sift.onRemotePartyHungUp¶

type:	`Function()`

Called when a connection is terminated due to the remote end ending the call. This can happen when the routine handling the connection reaches a HangUp command.

Sift.onRemotePartyHungUp = function() {
    console.log("Remote party hung up!");
}
Sift.connect();

Sift.onError¶

type:	`Function(String error)`

Called when an error occurs that prevents a connection from being established. error is a string error code. Can be any of the values defined in Error Strings.

Functions¶

Sift.authenticate¶

type:	`Function(String token)`

Initialize the global Sift object. Must be called before any other function. token is a string generated by your server which encodes the authorization and permissions information for this client instance. If the client is allowed to receive calls, token will contain the WebRTC name to use when calling this client. If the client is allowed to make outgoing calls, then token will contain the Application that will handle the incoming calls. It is an error to call the authenticate function a second time unless you call the Sift.reset function first.

Sift.onAuthenticated = function() {
    // Ready to connect here.
}
Sift.authenticate(my_token);

Sift.connect¶

type:	`Function(Anything data)`

Initiate a new outbound VOIP connection.

When called, the current Sift state will switch to connecting. If required, the browser will show a prompt to the user requesting microphone access. If access is denied, the Sift.onError callback is called with the parameter “mic-permission-denied” and the current state returns to authenticated.

If the token string that you passed to Sift.authenticate does not allow outbound calls, the connection will fail and the Sift.onError callback will be called.

Throws an exception if the current state is not authenticated.

Once the connection is established, the Application encoded in the authentication token will receive the new call and dictate the call flow.

The data parameter can be any JSON-serializable type. It will be attached to the Connection object associated with the call in the REST API, and consequently is available to the Incoming Connection Callback for the Application. It is therefore useful as a way to communicate client state with the server and determine how the call should be handled.

Sift.onConnected = function() {
    // Display some connected UI
}
Sift.onError = function(error) {
    if (error === Sift.Error.NO_MIC) {
        alert("Please plug in a mic to connect!");
    } else if (error === Sift.Error.MIC_PERMISSION_DENIED) {
        alert("You must allow mic access to connect!");
    } else if (error === Sift.Error.OUTGOING_NOT_PERMITTED) {
        alert("This client cannot make outgoing calls!");
    }
}
Sift.connect({
    greeting: 'hello',
    otherParameters: params
});

Sift.answer¶

type:	`Function()`

Answer an incoming call. If the current state is not ringing has no effect, otherwise, changes the current state to connecting. The browser will immediately prompt the user to allow microphone access if they have not already done so.

Sift.decline¶

type:	`Function()`

Decline an incoming call. If the current state is not ringing has no effect. Changes the current Sift.state back to ready.

Sift.mute¶

type:	`Function()`

Mute the microphone.

Sift.unmute¶

type:	`Function()`

Unmute the microphone.

Sift.hangUp¶

type:	`Function()`

Terminate the active connection. Has no effect if the connection is not in the connected state.

Sift.reset¶

type:	`Function()`

Resets the Sift object to the uninitialized state. You can then call init again with a different token. Terminates any active calls.

Sift.state¶

type:	`Function()`
returns:	String

Returns the current state as a string.

State Strings¶

The following strings may be returned by Sift.state. They are also listed in the object Sift.State.

State	Description
uninitialized	The initial state of the Sift object before `authenticate` is called.
authenticating	Sift received a call to Sift.authenticate and is waiting for the server to respond to the request.
authenticated	The initialization was successful and the server has authorized the client token. Ready to make or receive calls.
ringing	The client is receiving an inbound call. Client should call Sift.answer or Sift.decline
connecting	Currently establishing a voice connection, due to a call to `answer` or `connect`. Will be in this state while the browser asks the user for microphone access.
connected	The client is connected and sending and receiving audio data.

Error Strings¶

The following strings may be passed as the first parameter to the Sift.onError callback. They are also listed in the object Sift.Error.

Error	Description
unknown	An unknown error occurred.
lost-internet	The Internet connection was lost. The client has returned to the `uninitialized` state and cannot initate or receive calls.
no-mic	A call could not be connected because the user does not have a microphone.
mic-permission-denied	A call could not be connected because the user denied access to the microphone.
authentication-failed	A previous call to Sift.authenticate was unsuccessful because the authentication token was not valid.
outgoing-not-permitted	A call to Sift.connect was unsuccessful because the authentication token was not initialized with the “outgoing” capability.