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
  },
}

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

// 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)

Registers the provided Audio elements and Listeners. (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.

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| login method called with INVALID or EXPIRED token| |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.| |UnknownException| Error thrown for unknown reason.|