### Install and Run Project

Source: https://github.com/frejun-tech/integration-workflow-examples/blob/main/voip-dialer-widget/README.md

Install dependencies and run the development server. Create a .env file with your OAuth credentials.

```bash
npm install
npm run dev          # opens http://localhost:5173
```

```dotenv
VITE_CLIENT_ID="<your-client-id>"
VITE_CLIENT_SECRET="<your-client-secret>"
```

--------------------------------

### Initialize and Start Softphone Web SDK

Source: https://context7.com/frejun-tech/integration-workflow-examples/llms.txt

Initializes the Softphone SDK, logs in with OAuth, and starts the softphone with event listeners and audio elements. Ensure the necessary HTML audio elements are present.

```javascript
import { Softphone } from '@frejun/softphone-web-sdk';

let softphone = null;
let isMuted   = false;
let isOnHold  = false;

async function startSoftphone(accessToken, email) {
  softphone = new Softphone();

  // Authenticate the softphone session
  await softphone.login({ type: 'OAuth2.0', token: accessToken, email });

  const audioElements = {
    remote: document.getElementById('sip-remote-audio'),  // <audio> for far-end audio
    local:  document.getElementById('sip-local-audio'),   // <audio> for local mic monitor
  };

  const listeners = {
    onConnectionStateChange: (type, newState, attemptReconnection, error) => {
      console.log(`Connection [${type}]: ${newState}`);
      // type: 'UserAgentState' | 'RegistererState'
      // newState: 'Registered' | 'Stopped' | 'Terminated' | ...
      if (attemptReconnection) {
        softphone.reset(type === 'UserAgentState');
      }
    },

    onCallCreated: (type, details) => {
      // type: 'Outgoing' | 'Incoming'
      // details.candidate — remote phone number
      console.log(`Call created [${type}]:`, details.candidate);
    },

    onCallRinging: (type, details) => {
      console.log(`Ringing [${type}]:`, details.candidate);
    },

    onCallHangup: (type, details) => {
      console.log(`Call ended [${type}]:`, details.candidate);
      isMuted  = false;
      isOnHold = false;
    },
  };

  await softphone.start(listeners, audioElements);
  console.log('Softphone registered — ready to call');
}

// Example: start softphone after OAuth, then dial
await startSoftphone(accessToken, 'agent@example.com');
```

--------------------------------

### OAuth Authentication with @frejun/oauth

Source: https://context7.com/frejun-tech/integration-workflow-examples/llms.txt

Handles the OAuth 2.0 popup flow, token acquisition, and automatic token refresh. Must complete before invoking any calling API or SDK method. Configure with `VITE_CLIENT_ID` and `VITE_CLIENT_SECRET` in a `.env` file.

```javascript
import { FrejunOAuth } from '@frejun/oauth';

// .env: VITE_CLIENT_ID="..." VITE_CLIENT_SECRET="..."
const oauth = new FrejunOAuth({
  clientId: import.meta.env.VITE_CLIENT_ID,
  clientSecret: import.meta.env.VITE_CLIENT_SECRET,
});

let accessToken = null;
let userEmail   = null;

// Fires once with auth-code metadata (includes the user's email)
oauth.on('authCode', (data) => {
  userEmail = data.email;
});

// Fires after the token exchange completes
oauth.on('tokens', (data) => {
  accessToken = data.access_token;
  console.log('Authenticated:', userEmail);
  // Enable call controls here
});

// Fires when the SDK automatically refreshes an expiring token
oauth.on('tokensRefreshed', (data) => {
  accessToken = data.access_token;
  console.log('Token refreshed');
});

oauth.on('error', (err) => {
  console.error('Auth error:', err.message);
});

// Trigger authentication via popup (e.g. from a button click)
document.getElementById('btn-auth').addEventListener('click', () => {
  oauth.openAuthPopup();
});
```

--------------------------------

### OAuth Authentication - @frejun/oauth

Source: https://context7.com/frejun-tech/integration-workflow-examples/llms.txt

Handles the OAuth 2.0 popup flow, token acquisition, and automatic token refresh. Emits 'authCode', 'tokens', 'tokensRefreshed', and 'error' events. Must complete before any calling API or SDK method is invoked.

```APIDOC
## OAuth Authentication - `@frejun/oauth`

### Description
Handles the OAuth 2.0 popup flow, token acquisition, and automatic token refresh. Emits `authCode`, `tokens`, `tokensRefreshed`, and `error` events. Must complete before any calling API or SDK method is invoked.

### Usage
```js
import { FrejunOAuth } from '@frejun/oauth';

// .env: VITE_CLIENT_ID="..." VITE_CLIENT_SECRET="..."
const oauth = new FrejunOAuth({
  clientId: import.meta.env.VITE_CLIENT_ID,
  clientSecret: import.meta.env.VITE_CLIENT_SECRET,
});

let accessToken = null;
let userEmail   = null;

// Fires once with auth-code metadata (includes the user's email)
oauth.on('authCode', (data) => {
  userEmail = data.email;
});

// Fires after the token exchange completes
oauth.on('tokens', (data) => {
  accessToken = data.access_token;
  console.log('Authenticated:', userEmail);
  // Enable call controls here
});

// Fires when the SDK automatically refreshes an expiring token
oauth.on('tokensRefreshed', (data) => {
  accessToken = data.access_token;
  console.log('Token refreshed');
});

oauth.on('error', (err) => {
  console.error('Auth error:', err.message);
});

// Trigger authentication via popup (e.g. from a button click)
document.getElementById('btn-auth').addEventListener('click', () => {
  oauth.openAuthPopup();
});
```
```

--------------------------------

### Network Calling - POST /integrations/create-call/

Source: https://context7.com/frejun-tech/integration-workflow-examples/llms.txt

Initiates a 2-legged network call: FreJun first calls the agent, then bridges them to the destination number. No softphone or browser audio session is required on the caller's end.

```APIDOC
## Network Calling - `POST /integrations/create-call/`

### Description
Initiates a 2-legged network call: FreJun first calls the agent, then bridges them to the destination number. No softphone or browser audio session is required on the caller's end.

### Method
POST

### Endpoint
`https://api.frejun.com/api/v1/integrations/create-call/`

### Parameters
#### Request Body
- **user_email** (string) - Required - The email address of the agent to call.
- **candidate_number** (string) - Required - The destination number in E.164 format (e.g., "+919876543210").
- **candidate_name** (string) - Optional - The name of the candidate.

### Request Example
```js
const API_BASE = 'https://api.frejun.com/api/v1';

async function initiateNetworkCall({
  accessToken,
  userEmail,
  candidateNumber,
  candidateName,
}) {
  if (!userEmail || !candidateNumber) {
    throw new Error('user_email and candidate_number are required');
  }

  const res = await fetch(`${API_BASE}/integrations/create-call/`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      user_email: userEmail,
      candidate_number: candidateNumber,
      ...(candidateName && { candidate_name: candidateName }),
    }),
  });

  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);

  const data = await res.json();
  console.log('Network call response:', JSON.stringify(data, null, 2));
  // FreJun will now ring the agent's phone and bridge to candidateNumber
  return data;
}

// Usage
await initiateNetworkCall({
  accessToken,
  userEmail: 'agent@example.com',
  candidateNumber: '+919876543210',
  candidateName: 'Jane Doe', // optional
});
```

### Response
#### Success Response (200)
- **data** (object) - Contains details about the initiated call.
```

--------------------------------

### Initiate Network Call via REST API

Source: https://context7.com/frejun-tech/integration-workflow-examples/llms.txt

Initiates a 2-legged network call where FreJun calls the agent and bridges them to the destination number. No softphone or browser audio session is required. Requires `accessToken`, `userEmail`, and `candidateNumber`.

```javascript
const API_BASE = 'https://api.frejun.com/api/v1';

async function initiateNetworkCall({ accessToken, userEmail, candidateNumber, candidateName }) {
  if (!userEmail || !candidateNumber) {
    throw new Error('user_email and candidate_number are required');
  }

  const res = await fetch(`${API_BASE}/integrations/create-call/`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      user_email: userEmail,
      candidate_number: candidateNumber,              // E.164, e.g. "+919876543210"
      ...(candidateName && { candidate_name: candidateName }),
    }),
  });

  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);

  const data = await res.json();
  console.log('Network call response:', JSON.stringify(data, null, 2));
  // FreJun will now ring the agent's phone and bridge to candidateNumber
  return data;
}

// Usage
await initiateNetworkCall({
  accessToken,
  userEmail:       'agent@example.com',
  candidateNumber: '+919876543210',
  candidateName:   'Jane Doe',          // optional
});
```

--------------------------------

### Initiate VoIP Call

Source: https://context7.com/frejun-tech/integration-workflow-examples/llms.txt

This function initiates a VoIP call by first resolving the agent's ID from their email and then triggering the call to the specified destination number. Optional parameters for candidate name and virtual number can be included.

```APIDOC
## POST /integrations/call-to-voip/

### Description
Triggers a VoIP call to a specified destination number for a logged-in agent. The agent's ID is resolved from their email address before the call is initiated.

### Method
POST

### Endpoint
/integrations/call-to-voip/

### Parameters
#### Request Body
- **agent_id** (string) - Required - The ID of the agent initiating the call.
- **dstn_number** (string) - Required - The destination number for the call in E.164 format (e.g., "+14155550100").
- **candidate_name** (string) - Optional - The name of the candidate being called.
- **virtual_number** (string) - Optional - The virtual number to be used for the call.

### Request Example
```json
{
  "agent_id": "agent123",
  "dstn_number": "+14155550100",
  "candidate_name": "John Smith",
  "virtual_number": "+18005550199"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains information about the initiated call.

#### Response Example
```json
{
  "data": {
    "call_id": "call_abc123",
    "status": "initiated"
  }
}
```
```

--------------------------------

### Integrate Dialer Widget with `postMessage`

Source: https://context7.com/frejun-tech/integration-workflow-examples/llms.txt

Embed the Dialer Widget in an iframe and communicate using `postMessage`. Handles outbound messages for authorization and call control, and inbound messages for widget status and events.

```javascript
const DIALER_ORIGIN = 'https://dialer.frejun.com';
const DIALER_URL    = DIALER_ORIGIN + '/';

const iframe = document.getElementById('dialer-iframe');
let accessToken  = null;
let userEmail    = null;
let dialerLoaded = false;

// ── Outbound: authorize ────────────────────────────────────────────────────
function sendAuthorize() {
  iframe.contentWindow.postMessage(
    { eventName: 'authorize', data: { access_token: accessToken, user_email: userEmail } },
    { targetOrigin: DIALER_URL },
  );
}

// ── Outbound: initiate-call ────────────────────────────────────────────────
function sendInitiateCall(candidateNumber, options = {}) {
  if (!candidateNumber) throw new Error('candidate_number is required');

  iframe.contentWindow.postMessage(
    {
      eventName: 'initiate-call',
      data: {
        user_email:       userEmail,
        candidate_number: candidateNumber,       // E.164
        access_token:     accessToken,
        ...(options.candidateName  && { candidate_name:  options.candidateName }),
        ...(options.virtualNumber  && { virtual_number:  options.virtualNumber }),
        ...(options.transactionId  && { transaction_id:  options.transactionId }),
        ...(options.jobId          && { job_id:          options.jobId }),
        ...(options.candidateId    && { candidate_id:    options.candidateId }),
      },
    },
    { targetOrigin: DIALER_URL },
  );
}

// ── Outbound: end-call ─────────────────────────────────────────────────────
function sendEndCall() {
  iframe.contentWindow.postMessage({ eventName: 'end-call' }, { targetOrigin: DIALER_URL });
}

// ── Inbound message handler ────────────────────────────────────────────────
window.addEventListener('message', (event) => {
  if (event.origin !== DIALER_ORIGIN || !event.data) return;

  const { eventName, detail } = event.data;

  switch (eventName) {
    case 'ready':
      // Widget loaded — authorize immediately if token is available
      dialerLoaded = true;
      if (accessToken) sendAuthorize();
      break;

    case 'unauthorized':
      // detail: "missing required parameter: access_token" | "invalid/expired access_token"
      //         | "Subscription is Inactive"
      console.error('Dialer unauthorized:', detail);
      break;

    case 'incoming-call':
      // Show widget so the user can accept or reject
      document.getElementById('widget-wrapper').style.display = 'block';
      break;

    case 'close':
      // Hide widget — call saved, or initiation failed due to validation error
      document.getElementById('widget-wrapper').style.display = 'none';
      break;

    case 'height-change':
      // Resize wrapper to match dynamic iframe content height
      const h = parseInt(detail, 10);
      if (h > 0) {
        document.getElementById('widget-wrapper').style.height = h + 'px';
        iframe.style.height = h + 'px';
      }
      break;

    case 'call-ended':
      console.log('Call ended');
      break;

    case 'end-call-error':
      // detail: "no ongoing browser-based call" | "initiation in progress"
      console.warn('End-call error:', detail);
      break;
  }
});

// ── Load the widget (set src once, then show/hide the wrapper) ─────────────
function openWidget() {
  if (!iframe.src || iframe.src === 'about:blank') {
    iframe.src = DIALER_URL;
  }
  document.getElementById('widget-wrapper').style.display = 'block';
}

// Example usage after OAuth completes
openWidget();
sendInitiateCall('+919876543210', { candidateName: 'Jane Doe', virtualNumber: '+18005550199' });

```

--------------------------------

### Initiate VoIP Call with User ID Resolution

Source: https://context7.com/frejun-tech/integration-workflow-examples/llms.txt

This function resolves the agent's user ID from their email and then triggers a VoIP call to a specified destination number. Ensure the agent is registered on a softphone. The call lifecycle can be tracked using the call-status webhook.

```javascript
const API_BASE = 'https://api.frejun.com/api/v1';

async function initiateVoIPCall({ accessToken, emailId, dstnNumber, candidateName, virtualNumber }) {
  if (!emailId || !dstnNumber) {
    throw new Error('emailId and dstnNumber are required');
  }

  // Step 1 — Resolve user_id from email
  const userRes = await fetch(
    `${API_BASE}/integrations/user/?email=${encodeURIComponent(emailId)}`,
    { headers: { 'Authorization': `Bearer ${accessToken}` } },
  );
  if (!userRes.ok) throw new Error('Failed to retrieve user: ' + await userRes.text());

  const { data: userData } = await userRes.json();
  const agentId = userData.user_id;
  console.log('Resolved agent_id:', agentId);

  // Step 2 — Trigger the VoIP call
  const res = await fetch(`${API_BASE}/integrations/call-to-voip/`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agent_id: agentId,
      dstn_number: dstnNumber,                          // E.164, e.g. "+14155550100"
      ...(candidateName  && { candidate_name:  candidateName }),
      ...(virtualNumber  && { virtual_number:  virtualNumber }),
    }),
  });

  const data = await res.json();
  console.log('Call-to-VoIP response:', JSON.stringify(data, null, 2));
  // The softphone registered under emailId will now ring
  // Use the call-status webhook to track further lifecycle events
  return data;
}

// Usage
await initiateVoIPCall({
  accessToken,
  emailId:       'agent@example.com',
  dstnNumber:    '+14155550100',
  candidateName: 'John Smith',     // optional
  virtualNumber: '+18005550199',   // optional
});
```

--------------------------------

### Make Outbound Call with Softphone SDK

Source: https://context7.com/frejun-tech/integration-workflow-examples/llms.txt

Initiates an outbound call using the Softphone SDK. The `virtualNumber` parameter is optional and specifies the caller ID.

```javascript
// Make an outbound call
async function dial(destinationNumber, virtualNumber) {
  // virtualNumber is optional — omit or pass undefined to use default caller ID
  await softphone.makeCall(destinationNumber, virtualNumber);
}

// Example: start softphone after OAuth, then dial
await dial('+14155550100', '+18005550199');
```

--------------------------------

### Control Active Call with Softphone SDK

Source: https://context7.com/frejun-tech/integration-workflow-examples/llms.txt

Provides functions to manage an active call session, including accepting incoming calls, ending calls, toggling mute, and toggling hold. These functions require an active call.

```javascript
// Session controls (call must be active)
function acceptIncoming()  { softphone.getSession.accept(); }
function endCall()          { softphone.getSession.end(); }

function toggleMute() {
  if (isMuted) softphone.getSession.unmute();
  else         softphone.getSession.mute();
  isMuted = !isMuted;
}

function toggleHold() {
  if (isOnHold) softphone.getSession.unhold();
  else          softphone.getSession.hold();
  isOnHold = !isOnHold;
}
```

--------------------------------

### Update Access Token in Softphone SDK

Source: https://context7.com/frejun-tech/integration-workflow-examples/llms.txt

Updates the access token for the softphone session without needing to restart the SDK. This is useful for handling token refreshes.

```javascript
// Update token without restarting the softphone (on tokensRefreshed)
function refreshToken(newToken) {
  softphone.updateAccessToken(newToken);
}
```

--------------------------------

### Resolve User ID

Source: https://context7.com/frejun-tech/integration-workflow-examples/llms.txt

This endpoint resolves a user's ID based on their email address. It is used as a preliminary step before initiating a VoIP call to ensure the correct agent is identified.

```APIDOC
## GET /integrations/user/

### Description
Resolves a user's ID from their email address. This is typically used to identify the agent before initiating a call.

### Method
GET

### Endpoint
/integrations/user/

### Parameters
#### Query Parameters
- **email** (string) - Required - The email address of the user to resolve.

### Response
#### Success Response (200)
- **data** (object) - Contains user information, including the user ID.
  - **user_id** (string) - The unique identifier for the user.

#### Response Example
```json
{
  "data": {
    "user_id": "agent123",
    "email": "agent@example.com"
  }
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.