> ## 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.

# Inbound Calls

> Configure how Crew handles incoming phone calls

# Inbound Calls

Inbound calls are phone calls initiated by external parties to your Crew-managed phone numbers. This guide covers configuration, handling logic, and optimization.

## How Inbound Calls Work

```
Caller dials your number
        ↓
Telephony provider (Twilio/RingCentral) receives call
        ↓
Webhook triggers Crew
        ↓
Crew routes to assigned agent
        ↓
Agent answers and begins conversation
        ↓
Conversation follows pathway logic
        ↓
Call ends or transfers
```

## Phone Number Configuration

### Assigning Numbers to Agents

Each phone number can be assigned to one or more agents:

```json theme={null}
{
  "phone_number": "+14155551234",
  "primary_agent": "agent_sarah",
  "fallback_agent": "agent_marcus",
  "business_hours_agent": "agent_sarah",
  "after_hours_agent": "agent_marcus"
}
```

### Number Sources

| Source      | Description                            | Setup                                                |
| ----------- | -------------------------------------- | ---------------------------------------------------- |
| Twilio      | Provision new numbers or port existing | [Twilio Integration](/integrations/twilio)           |
| RingCentral | Use existing RingCentral numbers       | [RingCentral Integration](/integrations/ringcentral) |
| SIP         | Connect via SIP trunking               | [SIP Integration](/integrations/sip)                 |

## Call Handling Flow

### Pre-Call Processing

Before the agent speaks, Crew processes:

1. **Caller ID lookup** — Identify known callers
2. **Business hours check** — Route to appropriate agent
3. **Blocklist check** — Filter blocked numbers
4. **Queue management** — Handle concurrent call limits

### Caller Identification

Match incoming numbers to known contacts:

```json theme={null}
{
  "caller_lookup": {
    "enabled": true,
    "sources": ["crm", "appointment_history"],
    "match_fields": ["phone", "mobile"]
  }
}
```

When a known caller is identified:

```javascript theme={null}
// Agent can personalize the greeting
"Hi {{caller.firstName}}, thanks for calling back. 
 I see you have an appointment scheduled for tomorrow."
```

### Business Hours Routing

Configure different behavior based on time:

```json theme={null}
{
  "routing": {
    "business_hours": {
      "agent": "agent_sarah",
      "greeting": "Thank you for calling Acme Medical, how can I help you?"
    },
    "after_hours": {
      "agent": "agent_marcus",
      "greeting": "Thank you for calling after hours. I can help with scheduling or take a message."
    },
    "holidays": {
      "agent": "agent_voicemail",
      "greeting": "We're closed for the holiday. Please leave a message."
    }
  }
}
```

## Concurrent Call Handling

Crew can handle multiple simultaneous calls:

| Plan         | Concurrent Calls |
| ------------ | ---------------- |
| Starter      | 5                |
| Professional | 25               |
| Enterprise   | Custom           |

### Queue Behavior

When at capacity:

```json theme={null}
{
  "queue_settings": {
    "max_wait_time": 60,
    "wait_message": "All agents are currently assisting other callers. Please hold.",
    "overflow_action": "voicemail"
  }
}
```

## Call Quality Settings

### Latency Optimization

Crew is optimized for sub-second response times:

| Setting                 | Description                         | Default     |
| ----------------------- | ----------------------------------- | ----------- |
| `response_speed`        | Balance between speed and quality   | `balanced`  |
| `interruption_handling` | How to handle caller interruptions  | `immediate` |
| `silence_threshold`     | Seconds before checking for hang-up | `3`         |

### Audio Quality

```json theme={null}
{
  "audio_settings": {
    "codec": "opus",
    "sample_rate": 16000,
    "noise_reduction": true,
    "echo_cancellation": true
  }
}
```

## Call Events

Crew emits events throughout the call lifecycle:

| Event                   | Trigger                | Data                             |
| ----------------------- | ---------------------- | -------------------------------- |
| `call.started`          | Call is answered       | caller\_id, agent\_id, timestamp |
| `call.intent_detected`  | User intent identified | intent, confidence               |
| `call.action_triggered` | Action node executed   | action\_type, result             |
| `call.transferred`      | Call routed to human   | destination, transfer\_type      |
| `call.ended`            | Call completed         | duration, disposition            |

### Webhook Configuration

```json theme={null}
{
  "webhooks": {
    "call.started": "https://yourapp.com/hooks/call-started",
    "call.ended": "https://yourapp.com/hooks/call-ended"
  }
}
```

## Call Recording

<Note>
  Recording laws vary by jurisdiction. Ensure compliance with local regulations.
</Note>

```json theme={null}
{
  "recording": {
    "enabled": true,
    "format": "mp3",
    "retention_days": 90,
    "consent_prompt": "This call may be recorded for quality assurance."
  }
}
```

## Transcription

Real-time transcription is available for all calls:

```json theme={null}
{
  "transcription": {
    "enabled": true,
    "language": "en-US",
    "punctuation": true,
    "speaker_labels": true
  }
}
```

Access transcripts via:

* Dashboard call logs
* API: `GET /v1/calls/{call_id}/transcript`
* Webhooks: `call.ended` includes transcript

## Error Handling

### Connection Failures

If a call fails to connect:

1. Retry connection (up to 3 attempts)
2. Log error for debugging
3. If persistent, route to fallback

### Agent Failures

If the agent encounters an error mid-call:

```json theme={null}
{
  "error_handling": {
    "agent_error": {
      "action": "apologize_and_transfer",
      "message": "I apologize, I'm experiencing a technical issue. Let me connect you with someone who can help.",
      "fallback": "+14155559999"
    }
  }
}
```

## Analytics

Track inbound call performance:

| Metric                  | Description                       |
| ----------------------- | --------------------------------- |
| **Call Volume**         | Total inbound calls over time     |
| **Answer Rate**         | Percentage answered vs. abandoned |
| **Average Handle Time** | Mean call duration                |
| **Resolution Rate**     | Calls resolved without transfer   |
| **Peak Hours**          | Busiest times for staffing        |

## Best Practices

* **Test your numbers** — Call your own numbers regularly to verify behavior
* **Monitor answer rates** — High abandonment indicates issues
* **Optimize greetings** — Keep initial greetings under 5 seconds
* **Handle silence** — Configure appropriate silence detection
* **Log everything** — Enable full logging for troubleshooting

## Next Steps

* [Outbound Calls](/voice/outbound-calls) — Initiate calls programmatically
* [Call Routing](/voice/call-routing) — Configure transfer rules
* [Live Transcription](/voice/live-transcription) — Real-time call transcripts