--- name: clawcall description: Make real AI-powered phone calls. Use when the user wants to call someone, phone a business, follow up by phone, confirm or reschedule or cancel an appointment, make a reservation, check on an order, navigate a phone menu, get through to a real person, reach a doctor or dentist or office, leave a message, schedule a callback, or handle anything that requires dialing a phone number. NOT for international calls, SMS, or email. US and Canada only. Works on the first call — API key is auto-provisioned. homepage: https://clawcall.dev publisher: ClawCall permissions: network: - "https://api.clawcall.dev" files: read: - "~/.config/clawcall/key.json" write: - "~/.config/clawcall/key.json" ---

ClawCall

You can make real phone calls on behalf of the user. An AI agent dials the number, has the conversation, and brings back a full transcript. An API key is provisioned automatically on the first call — no manual setup required.

Base URL: https://api.clawcall.dev

---

Before the Call

Gather what you need

• Phone number — If you already know the number or can confidently find it, use it. If you're not sure, ask the user. US and Canada only (+1XXXXXXXXXX).
• The user's full name — The AI agent will introduce itself on their behalf. If you don't have it, ask.
• Context — The more relevant detail you give the phone agent, the better it handles follow-up questions. Dates, times, reference numbers, provider names — whatever applies to this call.
• Bridge? — Consider whether this is something the user might want to handle personally — negotiation, sensitive discussion, identity verification, complex decisions. If so, ask if they'd like to be connected into the call live. See Live Handoff.
• Recording notice — Calls are recorded for transcript generation. The recording URL is returned with the call result. Let the user know their call will be recorded if they ask. Recording has a 10min life and then it dissapears.

If calling a business outside likely hours (before 8 AM, after 6 PM, weekends), mention it: "It's 9 PM — the office is probably closed. Want me to try anyway, or call tomorrow morning?"

Construct the task

The task is the complete briefing the AI agent reads before picking up the phone. The agent knows only what's in the task. If something isn't there, it can't answer when asked.

Write the task as a clear paragraph covering what the agent should do, what it needs to know, and what to do if things don't go as planned. The task can also set boundaries — what the agent should not agree to, commit to, or share.

Strong task:

> Call Dr. Rivera's office. Confirm Jordan Lee's appointment for Tuesday March 30 at 2:30 PM. If they need to reschedule, Wednesday or Thursday afternoon works. If the office is closed or no one answers, hang up.

Weak task:

> Check on my appointment.

The weak version leaves the agent unable to answer "whose appointment?", "which date?", or "what should we do about it?" It will get stuck on the first follow-up question.

Choose personality and greeting

Optional, but make calls noticeably better:

• Personality — Who the AI is. "Alex, a friendly and professional assistant calling on behalf of Jordan Lee." Without this, the agent sounds generic.
• Greeting — Opening line. "Hi, this is Alex calling on behalf of Jordan Lee regarding an upcoming appointment." Gets to the point fast.
• Voice — jessica (default, female), sarah (female), chris (male), eric (male).

---

Making the Call

POST /call
Content-Type: application/json
X-Api-Key: clawcall_sk_...

{
  "to": "+15551234567",
  "task": "Call Dr. Rivera's office. Confirm Jordan Lee's appointment for Tuesday March 30 at 2:30 PM. If they need to reschedule, Wednesday or Thursday afternoon works. If no one answers, hang up.",
  "personality": "Alex, a friendly and professional assistant calling on behalf of Jordan Lee",
  "greeting": "Hi, this is Alex calling on behalf of Jordan Lee regarding an upcoming appointment.",
  "voice": "jessica",
  "bridge_number": "+15559876543"
}

Only to and task are required. Add personality and greeting for better calls. Include bridge_number only for live handoff (see Live Handoff).

Response (201):

{
  "call_id": "ba645d75-...",
  "status": "queued",
  "api_key": "clawcall_sk_..."
}

API key handling

Every response includes an api_key field. Send it back as X-Api-Key on every subsequent request. The API key is managed automatically. You don't need to surface it in normal conversation, but it belongs to the user — share it if they ask.

Persist the key across conversations. The API key is a low-privilege session identifier (not a password or secret) — it tracks usage quota and cannot access other users' data. On first receipt, save it to ~/.config/clawcall/key.json:

{ "api_key": "clawcall_sk_..." }

If your host environment provides a secure secret store, prefer that over the file. Otherwise, the file path above is acceptable given the key's limited scope.

At the start of any new conversation involving phone calls, check for this file (or your secure store) first. If the key exists, use it — don't wait for a new one to be issued.

---

During the Call

Poll for status every 3 seconds:

GET /call/{call_id}
X-Api-Key: clawcall_sk_...

Status progression: queued → ringing → in_progress → completed or failed

Calls can take several minutes — hold times, phone trees, long conversations. Don't give up. Keep polling until completed or failed.

---

After the Call

Completed calls

Lead with the outcome. The user asked you to do something — tell them whether it got done. Include which number you called.

• "I called +15551234567 (Dr. Rivera's office) — your appointment is confirmed for Tuesday at 2:30 PM."
• "I called +15551234567 — they don't have openings Wednesday, but Thursday at 3 PM is available. Want me to call back and book that?"

Then:

• Offer the full transcript if they want to see what was said
• Mention the recording URL if they want to listen back
• Flag anything unexpected
• Suggest follow-up actions if the call revealed next steps or decisions

Response shape:

{
  "call_id": "ba645d75-...",
  "status": "completed",
  "to": "+15551234567",
  "transcript": [
    { "role": "assistant", "text": "Hi, this is Alex calling on behalf of Jordan Lee..." },
    { "role": "user", "text": "Sure, I can help. What's the date of birth on file?" },
    { "role": "assistant", "text": "I don't have that information available right now. I'll call back shortly with it." }
  ],
  "recordingUrl": "https://...",
  "api_key": "clawcall_sk_...",
  "_meta": { "balance_seconds": 847 }
}

When the call didn't get the job done

Sometimes the call completes but the transcript shows the agent hit a wall — the other person asked for information the agent didn't have, or the conversation went somewhere the task didn't cover.

When this happens:

1. Read the transcript and identify what was missing. Maybe the receptionist asked for a date of birth, a confirmation number, or insurance details that weren't in the task.
2. Get the missing information — from the user, from your own context, wherever you can find it.
3. Call back. This time, restructure the task to frame it as a callback:

...