# workrr-phone

> Real US phone numbers for AI agents. Calls ring your agent's endpoint first; if it doesn't answer,
> the caller gets voicemail and you get two webhooks: the recording right away, the transcript when ready.
> Inbound only. No voice bot: your agent decides what to do with each call or voicemail.

Base URL: https://phone.workrr.ai
Auth: `Authorization: Bearer <api_key>`
MCP (Streamable HTTP): https://phone.workrr.ai/mcp with the same bearer key.

## Get started (an agent can do all of this itself)

1. POST /v1/signup {"agent_name": "...", "contact_email": "owner@example.com"}
   -> {api_key, claim_url}. Send claim_url to your human; they add a card and accept the terms
   (and can pick the first number there). The key works once the account is claimed.
   Poll GET /v1/account until status is "active".
2. POST /v1/lines {"name": "Support agent", "endpoint": "sip:agent@your-host", "webhook_url": "https://..."}
   -> returns webhook_secret once. endpoint is a SIP URI or +1 number rung first.
3. GET /v1/numbers/available?area_code=415 -> pick one, then
   POST /v1/numbers {"e164": "+14155550142", "line_id": "<line id>"}
   This charges the owner's card $8 immediately (402 payment_failed if declined) and $8 monthly after.
4. Call the number. Missed calls go to voicemail.

## Pricing and limits

- $8 per number per month, charged when the number is ordered. No trial. DELETE /v1/numbers/{id} stops billing.
- Standard accounts hold 1 number; business-verified accounts up to 25 and toll-free.
- At most 3 number orders per account per 30 days (429 order_limit).
- One account per card; prepaid cards aren't accepted.
- Signups are rate limited per network (429 rate_limited).

## Endpoints

- GET  /v1/account
- GET  /v1/lines | POST /v1/lines | PATCH /v1/lines/{id}
    fields: name, endpoint, forward_to, ring_timeout_secs (5-60, default 20), after_hours ("voicemail"|"forward"),
    business_hours {"tz":"America/New_York","days":{"mon":[["09:00","17:00"]]}}, greeting_text,
    transcription_enabled (default true), webhook_url
- GET  /v1/numbers/available?kind=local&area_code=415
- GET  /v1/numbers | POST /v1/numbers | DELETE /v1/numbers/{id}
- PATCH /v1/numbers/{id} {"mode": "extensions", "extensions": {"101": "<line id>", "102": "<line id>"}}
    shared number: callers enter an extension
- GET  /v1/calls?limit=25&before=<iso>&line_id=
- GET  /v1/voicemails?limit=25&before=<iso>&line_id= | GET /v1/voicemails/{id} (includes a 24h signed audio_url)
- POST /v1/billing/portal -> {url}: a short-lived Stripe page where your human updates the card and sees invoices

Humans manage their accounts at https://phone.workrr.ai/account (email sign-in link): numbers, recent calls and voicemails,
"Manage billing" (Stripe), replace an agent's API key, release numbers.

## Webhooks

POST to the line's webhook_url, JSON body {id, type, created_at, data}.
- voicemail.received: voicemail_id, call_id, from, to, duration_secs, audio_url (signed, 24h), transcript_status
- voicemail.transcribed: voicemail_id, call_id, from, transcript
Verify header `Workrr-Signature: t=<unix>,v1=<hex>` where v1 = HMAC-SHA256(webhook_secret, "<t>.<raw body>").
Failed deliveries retry with backoff.

## MCP tools

get_account, search_numbers, order_number ($8 charge), release_number, list_numbers, list_lines, update_routing,
list_voicemails, get_voicemail, list_calls