> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecrew.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# RingCentral Integration

> Connect Crew to RingCentral for enterprise telephony

# RingCentral Integration

RingCentral integration enables Crew to work with your existing RingCentral phone system. Use your current numbers, extensions, and call routing while adding AI capabilities.

## Overview

With RingCentral, Crew can:

* Handle inbound calls on RingCentral numbers
* Place outbound calls through RingCentral
* Send and receive SMS
* Integrate with RingCentral call queues
* Access RingCentral call recordings

## Prerequisites

Before connecting:

1. RingCentral Office or RingCentral MVP subscription
2. Admin access to RingCentral account
3. API access enabled on your account

## Setup

### Step 1: Create RingCentral App

<Steps>
  <Step title="Access Developer Portal">
    Go to [developers.ringcentral.com](https://developers.ringcentral.com)
  </Step>

  <Step title="Create New App">
    Click **Create App** and select **REST API App**
  </Step>

  <Step title="Configure App">
    Set auth type to **JWT** for server-to-server integration
  </Step>

  <Step title="Set Permissions">
    Enable required permissions (see below)
  </Step>

  <Step title="Get Credentials">
    Copy Client ID, Client Secret, and JWT token
  </Step>
</Steps>

### Required Permissions

| Permission             | Purpose                    |
| ---------------------- | -------------------------- |
| `ReadAccounts`         | Access account information |
| `ReadCallLog`          | View call history          |
| `RingOut`              | Place outbound calls       |
| `WebhookSubscriptions` | Receive real-time events   |
| `SMS`                  | Send and receive SMS       |
| `ReadMessages`         | Access message history     |

### Step 2: Connect to Crew

<Steps>
  <Step title="Open Crew Dashboard">
    Navigate to **Settings** → **Integrations**
  </Step>

  <Step title="Select RingCentral">
    Click **Connect** next to RingCentral
  </Step>

  <Step title="Enter Credentials">
    Paste your Client ID, Client Secret, and JWT
  </Step>

  <Step title="Authorize">
    Complete the OAuth flow to grant access
  </Step>
</Steps>

### Step 3: Configure Extensions

Map RingCentral extensions to Crew agents:

```json theme={null}
{
  "extension_mapping": [
    {
      "extension": "101",
      "agent_id": "agent_sarah",
      "type": "primary"
    },
    {
      "extension": "102",
      "agent_id": "agent_marcus",
      "type": "after_hours"
    }
  ]
}
```

## Call Handling

### Inbound Calls

Configure how RingCentral routes calls to Crew:

**Option 1: Direct Routing**
Forward calls directly to Crew agents:

```json theme={null}
{
  "routing": {
    "type": "direct",
    "extension": "101",
    "agent_id": "agent_sarah"
  }
}
```

**Option 2: Queue Integration**
Crew answers calls from RingCentral queues:

```json theme={null}
{
  "routing": {
    "type": "queue",
    "queue_id": "queue_support",
    "agent_id": "agent_sarah",
    "priority": 1
  }
}
```

### Outbound Calls

Place calls through RingCentral:

```bash theme={null}
curl -X POST https://api.usecrew.ai/v1/calls/outbound \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "to": "+14155559999",
    "agent_id": "agent_sarah",
    "provider": "ringcentral",
    "from_extension": "101"
  }'
```

### Call Transfers

Transfer to RingCentral extensions:

```json theme={null}
{
  "transfer": {
    "type": "warm",
    "destination": "ext:205",
    "provider": "ringcentral"
  }
}
```

## SMS Integration

### Inbound SMS

SMS messages route to Crew agents:

```json theme={null}
{
  "sms": {
    "enabled": true,
    "extension": "101",
    "agent_id": "agent_sms"
  }
}
```

### Outbound SMS

```bash theme={null}
curl -X POST https://api.usecrew.ai/v1/sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "to": "+14155559999",
    "from_extension": "101",
    "message": "Your appointment is confirmed.",
    "provider": "ringcentral"
  }'
```

## Presence and Availability

Sync agent availability with RingCentral presence:

```json theme={null}
{
  "presence_sync": {
    "enabled": true,
    "mapping": {
      "Available": "agent_active",
      "Busy": "agent_busy",
      "DoNotDisturb": "agent_offline"
    }
  }
}
```

## Call Recording

Access RingCentral call recordings:

```bash theme={null}
curl https://api.usecrew.ai/v1/calls/{call_id}/recording \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Note>
  Recording access depends on your RingCentral plan and recording settings.
</Note>

## Webhooks

RingCentral events are forwarded to Crew:

| Event               | Description                    |
| ------------------- | ------------------------------ |
| `telephony.session` | Call state changes             |
| `message-store`     | New SMS received               |
| `presence`          | Extension availability changes |

### Webhook Configuration

Crew automatically manages RingCentral webhook subscriptions. No manual configuration required.

## High Availability

For production deployments:

```json theme={null}
{
  "ringcentral": {
    "failover": {
      "enabled": true,
      "fallback_provider": "twilio",
      "fallback_number": "+14155550000"
    }
  }
}
```

## Limitations

| Feature        | Support         |
| -------------- | --------------- |
| Voice calls    | ✓ Full support  |
| SMS            | ✓ Full support  |
| Fax            | ✗ Not supported |
| Video          | ✗ Not supported |
| Team messaging | ✗ Not supported |

## Troubleshooting

### Authentication Errors

1. Verify JWT token hasn't expired
2. Check app permissions in RingCentral
3. Ensure production vs sandbox environment match
4. Regenerate JWT if needed

### Calls Not Routing

1. Verify extension is correctly mapped
2. Check RingCentral call handling rules
3. Ensure extension is active and available
4. Review RingCentral call logs

### SMS Failures

1. Verify SMS is enabled on extension
2. Check message content for blocked terms
3. Verify recipient number format
4. Review RingCentral message logs

## Best Practices

<AccordionGroup>
  <Accordion title="Use production environment">
    Always use RingCentral production (not sandbox) for live deployments.
  </Accordion>

  <Accordion title="Map extensions strategically">
    Create dedicated extensions for AI agents to avoid conflicts.
  </Accordion>

  <Accordion title="Configure failover">
    Set up Twilio as a backup in case of RingCentral issues.
  </Accordion>

  <Accordion title="Monitor rate limits">
    RingCentral has API rate limits; monitor usage in high-volume scenarios.
  </Accordion>
</AccordionGroup>

## Next Steps

* [Twilio Integration](/integrations/twilio) — Alternative telephony provider
* [SIP Integration](/integrations/sip) — Custom SIP trunking
* [Call Routing](/voice/call-routing) — Configure routing rules