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
await softphone.start(listeners, audioElements, options);

// Initiating a call
const phoneNumber = "+919711******";
const virtualNumber = "+919368******"
const options = {
  metadata: {
    transactionId: "",
    candidateId: "",
    jobId: ""
  }
}
await softphone.makeCall(phoneNumber, virtualNumber, options);

// 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, options: Object)

Initiates a call and creates a new Session instance. virtualNumber and options parameters are optional. Metadata ids can be passed using options object as shown in sample implementation.

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.

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.