# KlawVoice — give your agent a phone number and a voice

You are an AI agent setting up KlawVoice for a human. KlawVoice provisions a real
US/Canada phone number, attaches a natural voice and a persona, and puts a
conversational agent on live calls. Everything below is plain REST on `https://klaw-voice.netlify.app` —
or use MCP (last section).

## Ground rules
- Ask your human for consent and their mobile number before placing any call.
- Provision at most ONE phone number unless your human explicitly asks for more.
- Numbers cost about $1/month; calls bill by the minute. Creating agents is free.

## 1. Authenticate
Create an account (returns a JWT you use as a Bearer token):

```bash
curl -X POST https://klaw-voice.netlify.app/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"human@example.com","name":"Their Name","password":"a-strong-password"}'
```

Response: `{"token":"...","user":{...}}`. If the email exists, use
`POST https://klaw-voice.netlify.app/api/auth/login` with the same body shape (email + password).
An existing `klw_` API key from the dashboard also works as a Bearer token.
Send `Authorization: Bearer <token-or-key>` on every request below.

## 2. Fast path — agent + persona + voice + number in one call

```bash
curl -X POST https://klaw-voice.netlify.app/api/agents/quickstart \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "preset": "receptionist",
    "business_name": "Sunrise Dental",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "with_number": true,
    "area_code": "415"
  }'
```

- `preset`: one of `receptionist`, `customer_support`, `sales_associate`, `custom`.
- `voice_id` (optional): an ElevenLabs voice id — list them in step 3.
- `with_number: true` (optional): also provisions a phone number. `area_code`
  (3 digits, optional) picks the region; omit it for any available local number.
- Persona (optional): `instructions` replaces the preset playbook — write it like
  a system prompt for how the agent handles calls. `agent_name` and
  `first_message` override the generated name and greeting.

Response: `{"agent":{...},"phone_number":"+1...","number_error":null}`.
If number provisioning fails the agent is still created — retry via step 4
or report `number_error` to your human.

## 3. Voices
List curated voices: `GET https://klaw-voice.netlify.app/api/elevenlabs/voices` → `{"voices":[{"id","name",...}]}`.
Set one on an agent: `PATCH https://klaw-voice.netlify.app/api/agents/{id}` with `{"elevenlabs_voice_id":"<id>"}`.

## 4. Phone numbers (granular)
Search: `GET https://klaw-voice.netlify.app/api/twilio/numbers/available?area_code=415` → `{"numbers":[...]}`.
Attach: `POST https://klaw-voice.netlify.app/api/twilio/numbers/purchase` with `{"phone_number":"+1...","agent_id":"<uuid>"}`.
One number per agent; inbound voice + SMS webhooks are wired automatically.

## 5. Prove it works
Place a test call to your human (with their consent):
`POST https://klaw-voice.netlify.app/api/agents/{id}/test-call` with `{"phone":"+14155550132"}` → `{"call_id":"..."}`.
Watch it live: poll `GET https://klaw-voice.netlify.app/api/calls/{call_id}` every few seconds — the response
includes `status` and a running `transcript`. Terminal statuses: completed, failed,
busy, no-answer, canceled.

## 6. MCP alternative
KlawVoice is also an MCP server at `https://klaw-voice.netlify.app/api/mcp` with tools including
`search_numbers`, `provision_number`, `create_persona`, `update_persona`,
`place_call`, `get_call_transcript`, and `wait_for_event`. Point any MCP client
at it with the same Bearer credentials.

## After setup
Tell your human: the agent's name, its phone number (if provisioned), and that
they can edit the playbook, voice, and knowledge at https://klaw-voice.netlify.app/dashboard.

## Deeper docs
Full documentation: https://klaw-voice.netlify.app/docs (all pages as one markdown stream: https://klaw-voice.netlify.app/llms-full.txt).
Architecture and trust model: https://klaw-voice.netlify.app/whitepaper.