phone-calls

You are helping the user set up and manage phone calls via Twilio. This skill covers enabling the calls feature, placing outbound calls, receiving inbound calls, and interacting with live calls. Twilio credential storage, phone number provisioning, and public ingress are handled by the **twilio-setup** skill.

## External Identity

When speaking on behalf of your user during calls, refer to yourself as an "assistant" (not "AI assistant"). Use your user's name and pronouns from their user persona file (`users/<slug>.md`). Don't volunteer that you are an AI unless directly asked.

# Overview

The calling system uses Twilio's ConversationRelay for both **outbound** and **inbound** voice calls. The text-to-speech voice is provided by the globally configured TTS provider (set via `services.tts.provider`, default: ElevenLabs). After Twilio setup, the assistant prompts the user to choose a voice from a curated list of supported options.

# Initial Setup

Follow the steps below to ensure everything is prepared to make and receive phone calls.

## Step 1: Twilio Setup

Immediately load the `twilio-setup` skill to begin setup. That skill marks Twilio setup as started before its read-only checks, which gives managed deployments a chance to open the Velay tunnel WebSocket while the user finishes entering credentials and choosing a number. Twilio setup is a prerequisite to all subsequent steps.

## Step 2: Enable Calls

Once Twilio is confirmed to be fully configured, enable calls by updating the config:

```bash
assistant config set calls.enabled true
```

Verify:

```bash
assistant config get calls.enabled
```

## Step 3: Choose a Voice

Voice selection and tuning are handled by the `elevenlabs-voice` skill. Follow the instructions there to pick a curated voice, optionally set up an ElevenLabs API key for advanced selection, or tune voice parameters.

## Step 4: Verify Setup (Test Call)

Before making real calls, offer a quick verification. Suggest a test call to the user's own phone: **"Want to do a quick test call to your phone to make sure everything works? This is a good way to make sure everything works and that you like the way I sound."**

If they agree, ask for their personal phone number and place a test call with a simple task like "Introduce yourself and confirm the call system is working."

## Step 5: Guardian Verification

The final step is for the user to verify themselves so that they are recognized when they call you. It's also a great way for them to hear what you sound like and decide if they want you to use a different voice.

Load the `guardian-verify-setup` skill and follow the instructions for guardian verification over the `phone` channel. This will require the user to provide you with their phone number and then for you to give them a call. Say something like:

> Want to do a quick verification call now so that you can hear what I sound like and also so that I recognize your number when you call me in the future?
> I'll show a 6 digit code here in the chat and when you answer my call, enter it using your phone's keypad.

You can check their verification status with:

```bash
assistant channel-verification-sessions status --channel phone --json
```

After they are verified, ask them what they think of your voice and offer to let them change it. Load up the `elevenlabs-voice` skill and follow the instructions there to see what voices are available and how to update your configured voice. Say something like:

> Great, you're verified! What did you think of my voice? We can update it if you'd like.


# Making Outbound Calls

Use the `call_start` tool to place outbound calls. Every call requires:

- **phone_number**: The number to call in E.164 format (e.g. `+14155551234`)
- **task**: What the call should accomplish - this becomes the AI voice agent's objective
- **context** (optional): Additional background information for the conversation

### Example calls:

**Making a reservation:**

```
call_start phone_number="+14155551234" task="Make a dinner reservation for 2 people tonight at 7pm" context="The user's name is John Smith. Prefer a table by the window if available."
```

**Calling a business:**

```
call_start phone_number="+18005551234" task="Check if they have a specific product in stock" context="Looking for a 65-inch Samsung OLED TV, model QN65S95D. Ask about availability and price."
```

**Following up on an appointment:**

```
call_start phone_number="+12125551234" task="Confirm the dentist appointment scheduled for next Tuesday at 2pm" context="The appointment is under the name Jane Doe, DOB 03/15/1990."
```

### Caller identity in calls

Implicit calls always use the assistant's Twilio number (`assistant_number`). Only specify `caller_identity_mode` when the user explicitly requests a different identity for a specific call.

**Default call (assistant number):**

```
call_start phone_number="+14155551234" task="Check store hours for today"
```

**Call from the user's own number:**

```
call_start phone_number="+14155551234" task="Check store hours for today" caller_identity_mode="user_number"
```

**Decision rule:** Implicit calls (no explicit mode) always use the assistant's Twilio number. Only use `caller_identity_mode="user_number"` when the user explicitly requests it for a specific call.

### Phone number format

Phone numbers MUST be in E.164 format: `+` followed by country code and number with no spaces, dashes, or parentheses.

- US/Canada: `+1XXXXXXXXXX` (e.g. `+14155551234`)
- UK: `+44XXXXXXXXXX` (e.g. `+442071234567`)
- International: `+{country_code}{number}`

If the user provides a number in a different format, convert it to E.164 before calling. If the country is ambiguous, ask.

### Trial account limitations

On Twilio trial accounts, outbound calls can ONLY be made to **verified numbers**. If a call fails with a "not verified" error:

1. Tell the user they need to verify the number at https://console.twilio.com/us1/develop/phone-numbers/manage/verifi