# n8n-nodes-ringcentral

[![npm version](https://img.shields.io/npm/v/@joshuanode/n8n-nodes-ringcentral.svg)](https://www.npmjs.com/package/@joshuanode/n8n-nodes-ringcentral)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![n8n](https://img.shields.io/badge/n8n-community%20node-orange.svg)](https://n8n.io/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![GitHub](https://img.shields.io/badge/GitHub-repo-black.svg?logo=github)](https://github.com/ajoshuasmith/n8n-nodes-ringcentral)

This is an n8n community node that provides comprehensive integration with the RingCentral API. It lets you use RingCentral in your n8n workflows for SMS messaging, voice calls, fax, video meetings, team messaging, and more.

RingCentral is a leading cloud communications platform that provides voice, video, team messaging, and collaboration solutions for businesses.

[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.

[Installation](#installation)
[Operations](#operations)
[Credentials](#credentials)
[Compatibility](#compatibility)
[Usage](#usage)
[Resources](#resources)

## Installation

Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.

1. Go to **Settings > Community Nodes**.
2. Select **Install**.
3. Enter `n8n-nodes-ringcentral` in **Enter npm package name**.
4. Agree to the [risks](https://docs.n8n.io/integrations/community-nodes/risks/) of using community nodes: select **I understand the risks of installing unverified code from a public source**.
5. Select **Install**.

After installing the node, you can use it like any other node. n8n displays the node in search results in the **Nodes** panel.

## Operations

This node supports the following RingCentral resources and operations:

### Message (SMS)

- **Send** - Send an SMS message
- **Get** - Get a specific message
- **Get Many** - Retrieve multiple messages with filtering
- **Update** - Update message read status
- **Delete** - Delete a message

### Call Log

- **Get** - Get a specific call log record
- **Get Many** - Retrieve call logs (extension or account level)
- **Delete** - Delete call log records

### Call Queue

- **Get** - Get a call queue
- **Get Many** - List all call queues
- **Get Members** - Get call queue members
- **Assign Members** - Assign members to a call queue
- **Update** - Update call queue settings/call handling

### Answering Rule

- **Get** - Get an account answering rule
- **Update** - Update an account answering rule (for rule toggles/routing changes)

### IVR Menu

- **Get** - Get an IVR menu
- **Update** - Update IVR menu configuration/routing

### Contact

- **Create** - Create a personal contact
- **Get** - Get a contact
- **Get Many** - List all personal contacts
- **Update** - Update a contact
- **Delete** - Delete a contact
- **Search Directory** - Search company directory

### Extension (Users)

- **Create** - Create a new extension/user
- **Get** - Get extension details
- **Get Many** - List all extensions
- **Update** - Update extension information
- **Delete** - Delete an extension

### Fax

- **Send** - Send a fax with file attachments
- **Get** - Get a specific fax
- **Get Many** - Retrieve multiple faxes

### Meeting

- **Create** - Create a video meeting
- **Get** - Get meeting details
- **Get Many** - List all meetings
- **Update** - Update meeting settings
- **Delete** - Delete a meeting

### Presence

- **Get** - Get presence status
- **Update** - Update presence status (Available, Busy, Offline)

### Recording

- **Get** - Get recording metadata
- **Get Content** - Get recording content or download as binary
- **Get Many** - List all recordings from call log

### RingSense

- **Get Insights** - Get AI conversation insights (automatic notes, summaries, highlights, next steps) by call record ID or session ID
- **Get Many Insights** - Discover calls from Call Log by date range and fetch RingSense insights for each
- **Get Record** - Get a RingSense record by call record ID
- **Get Session** - Get a RingSense session by session ID

### Team Messaging

- **Post Message** - Post a message to a chat
- **Get Chats** - Retrieve all chats
- **Get Chat** - Get a specific chat

### Webhook

- **Create** - Create a webhook subscription
- **Get** - Get webhook details
- **Get Many** - List all webhooks
- **Update** - Update webhook settings
- **Delete** - Delete a webhook

### Analytics

- **Get Aggregated Data** - Get aggregated call analytics
- **Get Performance Data** - Get performance metrics

## Credentials

This node uses OAuth 2.0 authentication. To set up credentials:

1. Create a RingCentral developer account at [https://developers.ringcentral.com](https://developers.ringcentral.com)
2. Create a new app in the RingCentral Developer Portal
3. Configure your app with the following:
   - **Application Type**: Public
   - **Platform Type**: Server/Web
   - **OAuth Redirect URI**: Your n8n OAuth callback URL
   - **Permissions**: Select the scopes you need (ReadAccounts, SMS, ReadMessages, etc.)
4. Note your **Client ID** and **Client Secret**
5. In n8n, create new RingCentral OAuth2 credentials:
   - Select **Production** or **Sandbox** environment
   - Enter your **Client ID**
   - Enter your **Client Secret**
   - Configure the **Scope** (space-separated)
   - Connect and authorize

### Required Scopes

Different resources require different scopes. Configure your RingCentral app with the appropriate permissions:

| Resource       | Required Scopes                       |
| -------------- | ------------------------------------- |
| Message (SMS)  | `SMS`, `ReadMessages`, `EditMessages` |
| Call Log       | `ReadCallLog`                         |
| Call Queue     | `ReadAccounts`, `EditAccounts`        |
| Answering Rule | `ReadAccounts`, `EditAccounts`        |
| Contact        | `ReadContacts`, `Contacts`            |
| Extension      | `ReadAccounts`, `EditAccounts`        |
| Fax            | `Faxes`, `ReadMessages`               |
| IVR Menu       | `ReadAccounts`, `EditAccounts`        |
| Meeting        | `Meetings`                            |
| Presence       | `ReadPresence`, `EditPresence`        |
| Recording      | `ReadCallRecording`                   |
| RingSense      | RingSense / AI Conversation Expert API access and related OAuth scopes |
| Team Messaging | `TeamMessaging`, `Glip`               |
| Webhook        | `SubscriptionWebhook`                 |
| Analytics      | `Analytics`                           |

> **Note**: When using the Sandbox environment, some features may have limited functionality or test data.

### Common Issues

- **403 Permission Denied**: Missing required scope - check the table above
- **404 Not Found**: Resource ID doesn't exist or was deleted
- **429 Rate Limited**: Too many requests - node auto-retries with backoff
- **Empty Dropdowns**: Credentials may need reconnection
- **RingSense 403/404**: Account may be missing RingSense entitlement, AI scopes, or insights may not be generated yet (enable polling options)

## Compatibility

- Tested with n8n version 1.0.0+
- Compatible with RingCentral REST API v1.0

## Usage

### Sending an SMS

1. Add the RingCentral node to your workflow
2. Select **Message (SMS)** as the resource
3. Select **Send** as the operation
4. Configure:
   - **From Phone Number**: Your RingCentral phone number
   - **To Phone Number(s)**: Recipient number(s)
   - **Message Text**: Your message content

### Creating a Meeting

1. Add the RingCentral node to your workflow
2. Select **Meeting** as the resource
3. Select **Create** as the operation
4. Configure:
   - **Topic**: Meeting subject
   - **Meeting Type**: Instant, Scheduled, or Recurring
   - **Start Time**: When the meeting starts (for scheduled meetings)
   - **Duration**: Meeting length in minutes

### Getting Call Logs

1. Add the RingCentral node to your workflow
2. Select **Call Log** as the resource
3. Select **Get Many** as the operation
4. Configure filters:
   - **Scope**: Extension or Account level
   - **Date Range**: Filter by date

### Multi-Tenancy (Dynamic Authentication)

This node supports Multi-Tenancy by allowing you to inject Access Tokens dynamically instead of using saved credentials. This is ideal for managing multiple customers in a single workflow.

1. Set **Authentication Mode** to `Dynamic Access Token (Multi-Tenant)`.
2. Map your **Access Token** from an upstream node (e.g., from a database or HTTP Request).
3. Select the **Server Environment** (Production or Sandbox).

> **Note**: In Dynamic Mode, the node **cannot refresh tokens**. Your workflow must handle token refresh logic (e.g., using an HTTP Request node to `/restapi/oauth/token`) before passing the valid access token to this node.

## Resources

- [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
- [RingCentral API Documentation](https://developers.ringcentral.com/api-reference)
- [RingCentral Developer Guide](https://developers.ringcentral.com/guide)

## Development

To modify or extend this node:

```bash
# Install dependencies
npm install

# Build the node
npm run build

# Run n8n in development mode
npm run dev

# Lint code
npm run lint

# Format code
npm run format
```

## Contributing

Contributions are welcome! If you'd like to add features, fix bugs, or improve documentation:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

Please ensure your code passes linting (`npm run lint`) before submitting.

## License

[MIT](LICENSE.md)

## Support

For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/ajoshuasmith/n8n-nodes-ringcentral).