Skip to main content

Dialer Widget

Prerequisites

  1. Active FreJun Account and Virtual Number
  2. OAuth 2.0 Access Token

Setup Guide

  1. Embed the Dialer Widget on your webpage while enabling microphone access

    <iframe src="https://dialer.frejun.com/" allow="microphone"></iframe>
  2. Upon the successful loading of the iframe, a ready message will be dispatched to the parent site. Subsequently, upon receipt of each ready message, an authorize message must be promptly dispatched to the iframe with the necessary details

  3. In the event of an unsuccessful authorization process, an unauthorized message will be relayed back to the parent site, signifying a failed authentication attempt. Conversely, upon successful authorization, the iframe will be ready to facilitate calls

  4. To initiate an outbound call, either:

    1. The parent site can dispatch an initiate-call message to the iframe. Following the reception of this message, the iframe will validate the request. Upon successful validation, the call will be initiated and then the in-call screen will be presented.
      or
    2. The user can directly enter the number to be dialed and select the virtual number with which the call should be made, in the dialer screen, and click on the Call button.
  5. For incoming calls, the iframe will send an incoming-call message to the parent site, prompting the appropriate handling on the parent site's end

warning

Call initiation will fail under following conditions:

  1. Invalid dialed number
  2. The provided virtual number, if included to initiate the call, is either invalid or notlinked with the user's account
  3. The country code in the dialed number is not supported

Outbound Messages (App to Dialer)

Authorization

{
eventName: 'authorize',
data: Object
}

Parameters for data Object

ParameterTypeDescription
access_tokenstringOAuth access token
user_emailstringFreJun account email

Initiate call

{
eventName: 'initiate-call',
data: Object
}

Parameters for data Object

ParameterTypeDescription
user_emailstringEmail id of user’s FreJun account (same as the one used for authorization)
candidate_numberstringReceiver’s number with country code (If not specified, defaults to country code of the virtual number with which call is being initiated) Example: (+91XXXXXXXXX)
candidate_name (optional)stringReceiver’s name to be displayed in the call details screen
virtual_number (optional)stringVirtual number with which call is to be initiated Example: (+91XXXXXXXXX)
access_tokenstringOAuth access token
transaction_id (optional)stringCustom Metadata
job_id (optional)stringCustom Metadata
candidate_id (optional)stringCustom Metadata

Inbound Messages (Dialer to App)

For important events, the Dialer Widget will emit JavaScript messages to your application.
Your application can listen to these messages and take appropriate actions.

Each message event will have a data attribute which will have the following schema.

ParameterTypeDescription
eventNamestringIdentifier of the event
detailstringPresent only when eventName is “unauthorized” or “height-change” or “end-call-error”

The eventName parameter will be one of:

ready

Sent each time the iframe loads, both on the initial load and upon subsequent page refreshes or reloads of the parent site.

close

Dispatched when the iframe is no longer necessary and can be hidden in the UI. This may occur:

  1. After saving call details.
  2. When a call cannot be initiated due to validation errors or unmet conditions, accompanied by a displayed error message.

incoming-call

Signifies an inbound call, prompting the parent site to make the iframe visible for the user to accept or reject the call.

unauthorized

Issued when the authorization process, initiated after receiving the authorize message, encounters a failure. The detail field in the event.data may contain one of the following values:

  1. missing required parameter: access_token
  2. missing required parameter: user_email
  3. invalid/expired access_token
  4. missing/invalid parameter: data
  5. Subscription is Inactive

height-change

Sent each time the height of the iframe changes. event.data.detail contains the height value in pixels, and can be used to make appropriate changes in UI by the parent site.

end-call-error

Sent when on receiving an “end-call” message, the attempt to end a call encounters a failure. The "detail" field in the event.data may contain one of the following values:

  1. Call can not be ended while initiation is in progress
  2. Received end-call message when there is no ongoing browser-based call

call-ended

Sent when a browser-based (incoming or outgoing) call ends or when an incoming call is rejected.

Sample Implementation

<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
</head>

<body>
<iframe id="frejun-dialer-iframe" height="600" width="370" src="https://dialer.frejun.com/"
allow="microphone"></iframe>
<button type="button" onclick="handleAuthorization()">Authorize</button>

<script>

const TARGET_ORIGIN = 'https://dialer.frejun.com';

// Dialer specific parameters
let dialerVisible = false;
let dialerLoaded = false;
let authRequired = false;
let oauthtoken = '<OAUTH_ACCESS_TOKEN>';

let email = '<FREJUN_EMAIL>';

// Adding message listener for communication with FreJun Dialer
window.addEventListener('message', handleMessageEvent);

// Message Triggers
function handleMessageEvent(event) {
console.log(event)
if (event.origin === TARGET_ORIGIN && event.data) {
const eventData = event.data;
if (eventData.eventName === 'incoming-call') {
// On incoming call trigger
dialerVisible = true;
} else if (eventData.eventName === 'ready') {
// On page load trigger
dialerLoaded = true;
authRequired = true;
} else if (eventData.eventName === 'close') {
// On close trigger
dialerVisible = false;
} else if (eventData.eventName === 'unauthorized') {
// On unauthorized trigger
authRequired = true;
}
}
}

// Authorization
function handleAuthorization() {
if (!dialerLoaded) return; // Returning when iframe is not loaded
const iframeElem = document.querySelector('#frejun-dialer-iframe');
const message = {
eventName: 'authorize',
data: {
access_token: oauthtoken,
user_email: email,
},
};

// Posting the authorize message to iframe
iframeElem.contentWindow.postMessage(message, {
targetOrigin: TARGET_ORIGIN +
'/'
})
authRequired = false;
}

</script>
</body>

</html>