clawcall

# ClawCall — Phone Calls for Your Agent

ClawCall gives you a real phone number connected directly to this agent.
Users can call you, you can call them back when tasks finish, run scheduled
briefings, and place calls to third parties on the user's behalf.

---

## Setup (First Time Only)

If `CLAWCALL_API_KEY` is not set, run registration:

1. Ask the user: "What email should I use for your ClawCall account?"
2. Ask the user: "What's your personal phone number? (I'll call you on this)"
3. Call:

```
POST https://api.clawcall.online/api/v1/register
Content-Type: application/json

{
  "email": "<user email>",
  "agent_webhook_url": "<your public URL>",
  "agent_name": "<optional name>",
  "phone_number": "<user's E.164 phone, e.g. +14155550100>"
}
```

4. Store the returned `api_key` as `CLAWCALL_API_KEY`.
5. Tell the user their agent number and that setup is complete.

**Example success response:**
```json
{
  "ok": true,
  "api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "phone_number": "+14155550192",
  "tier": "free",
  "message": "Setup complete! Your agent number is +14155550192."
}
```

---

## Receiving an Inbound Call

ClawCall will forward the caller's speech to your webhook as:

```
POST {your_webhook_url}/clawcall/message
{
  "call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "message": "What's the weather like today?"
}
```

Your webhook must respond with:

```json
{
  "response": "It's currently 72°F and sunny.",
  "end_call": false
}
```

Set `"end_call": true` to hang up after speaking your response.

**Important:** Respond within 25 seconds. For tasks taking longer,
respond quickly with an intermediate message like:
`"On it, give me a second."` — ClawCall will keep the line active.

---

## Calling the User Back (Task Completion)

When you finish a background task the user asked you to report on:

```
POST https://api.clawcall.online/api/v1/calls/outbound/callback
Authorization: Bearer {CLAWCALL_API_KEY}
Content-Type: application/json

{
  "messa...