Dialer Widget

Prerequisites

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

Setup Guide

Example Workflow

For a complete working example, see the Dialer Widget Workflow.

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

Caution

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

Parameter	Type	Description
access_token	string	OAuth access token
user_email	string	FreJun account email

Initiate call

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

Parameters for data Object

Parameter	Type	Description
user_email	string	Email id of user’s FreJun account (same as the one used for authorization)
candidate_number	string	Receiver’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)	string	Receiver’s name to be displayed in the call details screen
virtual_number (optional)	string	Virtual number with which call is to be initiated Example: (+91XXXXXXXXX)
access_token	string	OAuth access token
transaction_id (optional)	string	Custom Metadata
job_id (optional)	string	Custom Metadata
candidate_id (optional)	string	Custom 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.

Parameter	Type	Description
eventName	string	Identifier of the event
detail	string	Present 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>