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

# Phone Calls

> Make and receive phone calls with your AI agent via Twilio

## Overview

Orova uses Twilio for phone call integration. Your agent can receive inbound calls and make outbound calls to any phone number.

## Inbound calls

<Steps>
  <Step title="Buy or import a phone number">
    Go to **Phone Numbers** in the dashboard. Search for a number or import your existing Twilio number.
  </Step>

  <Step title="Assign to an agent">
    Assign the number to your agent with **inbound** mode. Orova automatically configures the Twilio webhooks.
  </Step>

  <Step title="Call the number">
    When someone calls the number, Orova routes the call to your agent. The agent speaks the first message and begins the conversation.
  </Step>
</Steps>

### How inbound routing works

1. A call comes in to your Orova phone number
2. Orova routes it to the assigned agent
3. The agent speaks the first message and begins the conversation

## Outbound calls

### From the dashboard

In the **Contacts** page, select contacts and click **Call**. Choose the agent and phone number to use.

### From the API

```bash theme={null}
curl -X POST https://app.orova.ai/api/optimus/phone-call \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "AGENT_ID",
    "phoneNumber": "+1234567890",
    "phoneNumberId": "PHONE_NUMBER_ID",
    "contactName": "John Doe",
    "workspaceId": "WORKSPACE_ID"
  }'
```

### Outbound call flow

1. Orova initiates the call via Twilio
2. When the recipient answers, the agent speaks the first message
3. The real-time voice engine handles the conversation
4. Voicemail detection runs automatically — if voicemail is detected, the call ends

## Call end reasons

| Reason               | Description                                           |
| -------------------- | ----------------------------------------------------- |
| `user_hangup`        | The user ended the call                               |
| `agent_goodbye`      | The agent said goodbye via the end\_conversation tool |
| `user_idle_timeout`  | The user was silent too long                          |
| `voicemail_detected` | Voicemail was detected on outbound call               |
| `no_answer`          | The recipient didn't answer                           |
| `customer_busy`      | The recipient's line was busy                         |

## Recordings

When `recording_enabled` is set on the agent, calls are recorded automatically. Access recordings via the History page or the API.