@frejun/softphone-web-sdk

Table of contents

• Overview
• Requirements
• Usage
• Softphone
• Session
• Event Listeners
• Logging & Error Handling

---

Overview

This SDK provides a SIP based Softphone to make/receive calls on the browser using FreJun.

Requirements

1. FreJun Account
2. OAuth 2.0 Access Token

Usage

import {Softphone} from "@frejun/softphone-web-sdk";

const softphone = new Softphone();

// Authenticating the softphone
const res = await softphone.login({
  type: "OAuth2.0",
  token: "<OAUTH_TOKEN>",
  email: "<USER_EMAIL>"
});

// Configuring Audio elements
const audioElements = {
  remote: document.getElementById("sip-remote-audio"),
  local: document.getElementById("sip-local-audio"),
}

// Configuring Listeners
const listeners = {
  onConnectionStateChange: (type, newState, attemptReconnection, error) => {
    // type : "UserAgentState" | "RegisterState"
    // if type is "UserAgentState", newState: "Started" | "Stopped"
    // if type is "RegisterState", newState: "Initial" | "Registered" | "Terminated" | "Unregistered"
  },
  
  onCallCreated: (type, details) => {
    // type: "Incoming" | "Outgoing"
    // details : Object {candidate: "+91936*******"}
  },

  onCallRinging: (type, details) => {
    // type: "Incoming" | "Outgoing"
    // details : Object {candidate: "+91936*******"}
    // show on call action buttons to user
  },

  onCallHangup: (type, details) => {
   // type: "Incoming" | "Outgoing"
   // details : Object {candidate: "+91936*******"}
   // show apt ui
  },
}

const options = {
  //End any ongoing call when user navigates away, default value is false
  endSessionOnNavigate: true,
  //Log out and end any ongoing call when user navigates away, default value is false
  logoutOnNavigate: true
}
//NOTE: Logout and termination of any ongoing call will always happen on page reload/refresh. This parameter is optional and is supported only on Chrome, Edge and Opera.

// Starting the Softphone
softphone.start(listeners, audioElements, options);

// Initiating a call
const phoneNumber = "+919711******";
const virtualNumber = "+919368******"
await softphone.makeCall(phoneNumber, virtualNumber);

// Ending a call
await softphone.getSession.end();

//Include HTML Elements
<audio controls id="sip-local-audio"></audio>
<audio autoPlay controls id="sip-remote-audio"></audio>

Softphone

The Softphone class provides the following methods.

login({type: String, token: String, email: String})

Authenticates the Softphone with FreJun. Value of type: "OAuth2.0".

start(listeners: Object, audioElements: Object, options: Object)

Registers the provided Audio elements, listeners and options. (Also prompts the user for mic permissions, if required.)

makeCall(phoneNumber: String, virtualNumber: String)

Initiates a call and creates a new Session instance. virtualNumber parameter is optional.

updateAccessToken(token: String)

Updates the OAuth access token, should be called on receiving an InvalidTokenException from methods other than login.

logout()

Handles data cleanup by dereferencing class variables.

reset()

Reconnects and re-registers the Softphone.

NOTE:

On disconnection, the softphone will automatically retry connecting to the server. If the attemptReconnection parameter of onConnectionStateChange listener is true, indicating that these (auto) reconnection attempts are exhausted, reset should be called to restore the calling service, based on the type as follows:

If type is UserAgentState, Softphone.reset(true) should be awaited.

If type is RegistererState, Softphone.reset() should be awaited.

Session

The Session object is accessed through Softphone.getSession and provides the following methods for managing the current session/call.

accept()

Accepts an incoming call.

end()

Rejects/Ends the call.

mute()

Mutes the call.

unmute()

Unmutes the call.

hold()

Puts the call on hold.

unhold()

Resumes the call if it was put on hold.

sendDTMF(signal: String)

Sends DTMF signal.

Event Listeners

The following listeners can be configured during Softphone initialization.

Listener	Required	Description
onConnectionStateChange	Yes	Called when the softphone's connection state or registration state changes.
onCallCreated	Yes	Called when a new session is created.
onCallRinging	Yes	Called when a session is connected.
onCallHangup	Yes	Called when a session is terminated.

Logging & Error Handling

The default logging level is debug. It is not customizable as of now.

Error classes

A complete list of Errors thrown by the SDK are described below.

Error	Reason
MissingParameterException	Method called without one or more required parameters.
InvalidValueException	Method called with invalid value for one or more parameters.
InvalidTokenException	The token which login method was called with is INVALID or has EXPIRED
UnauthorizedException	Method of Softphone or Session called when Softphone is not authenticated.
InvalidSessionTypeException	Session type is invalid for the method called.
InvalidSessionStateException	Session state is invalid for the method called.
PermissionDeniedException	User doesn't have the permission required to perform the action.
UnknownException	Error thrown for unknown reason.