# RingCentral VoIP Caller

A web-based JavaScript application that enables VoIP calling using RingCentral's WebRTC technology. This application provides a clean, responsive interface for making calls with OAuth authentication and comprehensive call management features.

## Features

- **OAuth Authentication**: Secure login with RingCentral popup authentication
- **WebRTC Calling**: High-quality VoIP calls using RingCentral's WebRTC SDK
- **Call Management**: Make calls, hang up, mute/unmute, volume control
- **Call Timer**: Real-time call duration tracking
- **Call History**: Local storage of recent calls with timestamps and duration
- **Device Selection**: Choose microphone and speaker devices
- **Responsive Design**: Works on desktop and mobile browsers
- **Real-time Status**: Visual feedback for call states and connection status

## Prerequisites

1. **RingCentral Developer Account**: Create an account at [developers.ringcentral.com](https://developers.ringcentral.com)
2. **HTTPS Hosting**: Required for WebRTC functionality
3. **Modern Browser**: Chrome, Firefox, Safari, or Edge with WebRTC support

## Setup Instructions

### 1. Create RingCentral App

1. Go to [RingCentral Developer Console](https://developers.ringcentral.com)
2. Create a new app with these settings:
   - **Platform Type**: Browser-based
   - **Permissions**: 
     - VoIP Calling
     - Read Accounts
     - Read Presence
     - Read Call Log
   - **OAuth Redirect URI**: Your domain (e.g., `https://yourdomain.com` or `https://localhost:8080` for local testing)

### 2. Configure the Application

1. Open `config.js` in your text editor
2. Replace the placeholder values with your RingCentral app credentials:

```javascript
const CONFIG = {
    clientId: 'YOUR_CLIENT_ID_HERE',        // Replace with your Client ID
    clientSecret: 'YOUR_CLIENT_SECRET_HERE', // Replace with your Client Secret
    server: 'https://platform.devtest.ringcentral.com', // Use sandbox for testing
    // ... other settings
};
```

**Environment Options:**
- **Sandbox (Testing)**: `https://platform.devtest.ringcentral.com`
- **Production**: `https://platform.ringcentral.com`

### 3. Host the Application

The application must be served over HTTPS for WebRTC to work. Here are several hosting options:

#### Option A: Local Development with HTTPS

Using Python (if you have Python installed):
```bash
# Python 3
python -m http.server 8080 --bind 127.0.0.1

# Then use a tool like ngrok for HTTPS
npx ngrok http 8080
```

Using Node.js (if you have Node.js installed):
```bash
npx http-server -p 8080 -a 127.0.0.1
# Then use ngrok for HTTPS
npx ngrok http 8080
```

#### Option B: Deploy to Web Hosting

Upload all files to any web hosting service that supports HTTPS:
- GitHub Pages
- Netlify
- Vercel
- Your own web server

### 4. Update OAuth Redirect URI

Make sure your RingCentral app's OAuth Redirect URI matches your hosting URL:
- Local development: `https://your-ngrok-url.ngrok.io`
- Production: `https://yourdomain.com`

## File Structure

```
ringcentral-voip-caller/
├── index.html          # Main HTML file
├── styles.css          # CSS styling
├── config.js           # Configuration file (update with your credentials)
├── app.js              # Main application logic
└── README.md           # This file
```

## Usage

1. **Open the Application**: Navigate to your hosted URL in a web browser
2. **Login**: Click "Login to RingCentral" and authenticate with your RingCentral account
3. **Make Calls**: Enter a phone number and click the call button
4. **Call Controls**: Use mute, volume, and hang up controls during calls
5. **View History**: Check recent calls in the call history section

## Configuration Options

### Environment Settings

```javascript
// Sandbox (for testing)
server: 'https://platform.devtest.ringcentral.com'

// Production (for live calls)
server: 'https://platform.ringcentral.com'
```

### WebRTC Settings

```javascript
webrtc: {
    audio: {
        echoCancellation: true,
        noiseSuppression: true,
        autoGainControl: true
    }
}
```

### Application Settings

```javascript
app: {
    callTimeout: 30,        // Call timeout in seconds
    maxCallHistory: 50      // Maximum call history items
}
```

## Browser Compatibility

- **Chrome**: Full support
- **Firefox**: Full support
- **Safari**: Full support (iOS 11+)
- **Edge**: Full support

## Security Considerations

- **HTTPS Required**: WebRTC requires secure connections
- **Token Storage**: Access tokens are stored in localStorage
- **CORS**: Ensure your domain is properly configured in RingCentral app settings
- **Permissions**: Only request necessary RingCentral permissions

## Troubleshooting

### Common Issues

1. **"Configuration Error"**
   - Check that `config.js` has valid credentials
   - Ensure clientId and clientSecret are not placeholder values

2. **"RingCentral SDK failed to load"**
   - **Most Common Issue**: This happens when the CDN is blocked or internet connection is poor
   - **Solutions**:
     - Check your internet connection
     - Try refreshing the page
     - Host the application on HTTPS (required for WebRTC)
     - Check if your firewall/antivirus is blocking CDN requests
     - Try using a different network or VPN
     - Download the SDK files locally (see Local SDK Setup below)

3. **"Login failed"**
   - Verify OAuth Redirect URI matches your hosting URL exactly
   - Check that your RingCentral app has correct permissions
   - Ensure you're using HTTPS

4. **"WebPhone initialization failed"**
   - Confirm your RingCentral account has VoIP calling enabled
   - Check browser console for detailed error messages
   - Verify you're using a supported browser

5. **"Call failed"**
   - Ensure microphone permissions are granted
   - Check that the phone number format is correct (include country code)
   - Verify your RingCentral account has calling credits/plan

### Local SDK Setup (Alternative to CDN)

If the CDN is consistently failing to load, you can download the SDK files locally:

1. **Download RingCentral SDK**:
   ```bash
   curl -o ringcentral.js https://unpkg.com/@ringcentral/sdk@4.5.0/build/ringcentral.js
   ```

2. **Download RingCentral WebPhone SDK**:
   ```bash
   curl -o ringcentral-web-phone.js https://unpkg.com/ringcentral-web-phone@0.8.6/build/ringcentral-web-phone.js
   ```

3. **Update index.html** to use local files:
   ```html
   <script src="ringcentral.js"></script>
   <script src="ringcentral-web-phone.js"></script>
   ```

### Browser Console

Open browser developer tools (F12) and check the Console tab for detailed error messages and debugging information.

### Network Issues

- Ensure your firewall allows WebRTC traffic
- Check that UDP ports are not blocked
- Verify STUN servers are accessible

## API Reference

### Main Class: RingCentralVoIPApp

#### Methods

- `login()`: Initiate OAuth login flow
- `logout()`: Log out and clear stored tokens
- `makeCall(phoneNumber)`: Initiate a call to the specified number
- `hangupCall()`: Terminate the current call
- `toggleMute()`: Toggle mute/unmute for current call
- `setVolume(value)`: Set call volume (0-100)

#### Events

The application handles various call states:
- `connecting`: Call is being initiated
- `progress`: Call is ringing
- `accepted`: Call has been answered
- `terminated`: Call has ended
- `failed`: Call failed to connect

## Development

### Adding Features

The application is built with a modular structure. Key areas for extension:

1. **Call Recording**: Add recording functionality using RingCentral APIs
2. **Contact Management**: Integrate with RingCentral contacts
3. **Call Analytics**: Add call quality metrics and reporting
4. **Multi-line Support**: Handle multiple simultaneous calls

### Code Structure

- **Authentication**: OAuth 2.0 flow with popup window
- **WebRTC**: RingCentral WebPhone SDK integration
- **UI Management**: Event-driven interface updates
- **State Management**: Local storage for call history and settings

## Support

For issues and questions:

1. Check the [RingCentral Developer Guide](https://developers.ringcentral.com/guide)
2. Review [WebRTC Documentation](https://developers.ringcentral.com/guide/voice/webrtc)
3. Visit [RingCentral Developer Community](https://community.ringcentral.com)

## License

This project is provided as-is for educational and development purposes. Please ensure compliance with RingCentral's terms of service and your local telecommunications regulations.

## Version History

- **v1.0.0**: Initial release with basic calling functionality
  - OAuth authentication
  - WebRTC calling
  - Call management controls
  - Call history tracking
  - Responsive design