# AX Voice-as-a-Service — Agent Skill

You now have access to AX Voice, a platform that lets you make phone calls on behalf of your owner. AX handles the real-time voice conversation — you just tell it what to accomplish.

## How It Works

1. **You are the brain** — you decide what needs to happen ("book a table," "call this lead," "follow up on an invoice")
2. **AX is the voice** — it makes the actual phone call, handles the conversation naturally at human speed, and reports back the outcome

## Getting Started

### Step 1: Register

Create your account:

```
POST https://axvoice.app/v1/voice/agents/register
Content-Type: application/json

{
  "name": "Your Agent Name",
  "email": "owner@example.com",
  "platform": "your-platform",
  "webhook_url": "https://your-server.com/ax-webhook"
}
```

This returns your `api_key` (starts with `ax_live_`) and an `onboarding_url`.

**IMPORTANT:** Your account starts in PENDING state. You must send the `onboarding_url` to your owner so they can:
- Confirm their email address
- Add a payment method ($10/month, includes ~50 minutes of talk time)

Once they complete signup, your account becomes ACTIVE.

### Step 2: Set Your Voice

Configure how you sound on calls:

```
POST https://axvoice.app/v1/voice/agents/me/voice
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "gender": "female",
  "accent": "en-US",
  "tone": "professional",
  "name": "Sarah",
  "persona": "A helpful and professional assistant.",
  "introduction": "Hi, I'm Sarah calling on behalf of my client.",
  "inbound_opening_line": "Hi, my name is Sarah. I am an AI agent calling on behalf of my client.",
  "language_primary": "en",
  "speed": 1.0
}
```

Options: gender (male/female), accent (en-US, en-AU, en-GB, en-SG, en-IN), tone (professional, casual, warm, authoritative).

### Step 3: Connect Twilio (Bring Your Own Number)

Your owner needs a Twilio account for phone calls. Tell them to:
1. Create a Twilio account at https://www.twilio.com/try-twilio
2. Find their Account SID and Auth Token at https://console.twilio.com (under "Account Info")
3. Provide these to you so you can connect them

Save the Twilio credentials:

```
POST https://axvoice.app/v1/voice/agents/me/twilio
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "auth_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

### Step 4: Choose a Twilio Number

List phone numbers already in the owner's Twilio account:

```
GET https://axvoice.app/v1/voice/agents/me/twilio/numbers
Authorization: Bearer YOUR_API_KEY
```

Select one number for AX Voice to use:

```
POST https://axvoice.app/v1/voice/agents/me/twilio/numbers
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "phone_number": "+14155551234"
}
```

If the list is empty, the owner should add/buy a number in Twilio first, then call the list endpoint again to refresh.

### Step 5: Verify Account Is Ready (Always check this before asking setup questions)

Before making a call, check Twilio status:

```
GET https://axvoice.app/v1/voice/agents/me/twilio
Authorization: Bearer YOUR_API_KEY
```

If this returns `configured: true` and a `phone_number`, Twilio is already set up and you should proceed to make the call.

Example response:
```json
{
  "configured": true,
  "phone_number": "+14155551234",
  "account_sid_preview": "AC123456...",
  "account_status": "active",
  "balance": "27.45",
  "balance_currency": "USD",
  "status_error": null
}
```

### Step 6: Make Calls

#### Using a Template (recommended)

```
POST https://axvoice.app/v1/voice/calls/outbound
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "template_id": "tmpl_restaurant_booking",
  "fields": {
    "venue_name": "Nobu Singapore",
    "phone_number": "+6512345678",
    "date": "2026-02-15",
    "time": "19:00",
    "party_size": 2,
    "booking_name": "Bradley",
    "fallback_times": ["19:30", "20:00"]
  }
}
```

#### Using a Custom Task

```
POST https://axvoice.app/v1/voice/calls/outbound
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "custom": {
    "phone_number": "+6598765432",
    "contact_name": "Dr. Chen",
    "objective": "Confirm whether lab results are ready for collection",
    "context": "Results were supposed to be ready by Friday.",
    "questions": ["Are the results ready?", "What are collection hours?"],
    "guardrails": ["Do not discuss actual medical results"],
    "success_criteria": "Confirm if results are ready and get collection details"
  }
}
```

### Step 7: Get Results

Check call status:

```
GET https://axvoice.app/v1/voice/calls/{call_id}
Authorization: Bearer YOUR_API_KEY
```

The response includes:
- `status`: queued, dialing, connected, completed, failed, no_answer
- `outcome`: { success, summary, structured_result, action_items }
- `recording_url`: MP3 recording of the call
- `duration_seconds`: how long the call lasted

If you provided a `webhook_url` during registration, results are also delivered via webhook automatically.

## Available Templates

Get the list:
```
GET https://axvoice.app/v1/voice/templates
```

| Template | Use Case |
|----------|----------|
| `tmpl_restaurant_booking` | Book a table at a restaurant |
| `tmpl_lead_qualification` | Qualify a sales lead |
| `tmpl_appointment_scheduling` | Schedule a meeting |
| `tmpl_vendor_followup` | Follow up on an order/invoice |
| `tmpl_general_inquiry` | Ask questions or collect information |
| `tmpl_feedback_collection` | Collect customer feedback |

## Pricing

- **$10/month** platform fee (includes $10 / ~50 minutes of talk time)
- **$0.20/minute** for usage beyond included minutes

## Key Points

- Your account must be ACTIVE to make calls (owner must complete signup)
- Always call `GET /v1/voice/agents/me/twilio` before asking the owner to reconnect Twilio
- Phone numbers in E.164 format (e.g., +6512345678)
- Calls are queued and processed automatically
- Results delivered via API polling or webhook
- All calls are recorded — recordings available for 30 days