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.

Cancelling or Hanging Up

To cancel a queued/ringing call or hang up an in-progress call:

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

Response (200):

{
  "success": true,
  "call_id": "ba645d75-...",
  "status": "failed",
  "message": "Call cancelled."
}

Works on any call state. Queued and ringing calls are cancelled immediately (status: "failed", failReason: "cancelled"). In-progress calls are hung up (status: "completed"). Already-ended calls return success (idempotent). You can only hang up calls you initiated.

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:

{
  "to": "+15551234567",
  "task": "You're calling Dr. Rivera's office back. You called a few minutes ago about Jordan Lee's appointment but didn't have the date of birth. It's 03/15/1990. Confirm the appointment for Tuesday March 30 at 2:30 PM. Here's the transcript from the previous call for context:\n\n[previous transcript]",
  "personality": "Alex, Jordan Lee's assistant",
  "greeting": "Hi, this is Alex again — I just called about Jordan Lee's appointment and I have that date of birth now."
}

Including the previous transcript in the task lets the phone agent pick up naturally where it left off, as if it's the same person calling back.

Failed calls

Errors on POST /call

Out of free minutes (quota_exceeded, 429)

{
  "error": {
    "code": "quota_exceeded",
    "action": {
      "url": "https://clawcall.dev/sign-up?token=clawcall_sk_...",
      "sign_in_url": "https://clawcall.dev/sign-in?token=clawcall_sk_..."
    }
  }
}

Ask the user: "Do you already have a ClawCall account?"

• No → Send action.url (sign-up link).
• Yes → Send action.sign_in_url (sign-in link).

After they sign up or sign in, the same API key works. Retry the call.

Out of purchased minutes (balance_depleted, 429)

Send the user action.url — it's a direct purchase link.

All lines busy (number_pool_exhausted, 503)

Wait 15 seconds and retry automatically. Temporary congestion.

Other errors

Live Handoff

When the user wants the AI to handle the tedious part — phone trees, hold music, the front desk — and then be connected in to speak directly.

When to suggest it

• The user says "get me through to a person," "connect me," or "transfer me"
• The call involves negotiation, identity verification, or real-time decisions
• The user wants to skip hold queues and menus

Don't suggest it for simple tasks the AI can fully handle.

How it works

1. Collect the user's own phone number — their callback number, not the number being called.
2. Include it as bridge_number in the request.
3. Write the task with a clear handoff trigger: "Once you're speaking with someone who can help, connect me."
4. The AI handles the call — intros, menus, hold queues.
5. When it's time, the AI says "connecting you now" and the user's phone rings.
6. When they answer, they're speaking directly with the other person. The AI drops off.
7. Either party hanging up ends the call for both.

The transcript covers everything up to the handoff. After that, the conversation is private.

Example

{
  "to": "+15551234567",
  "task": "Call Dr. Rivera's office. Navigate the phone menu and tell the receptionist you need to reschedule Jordan's appointment. Once you're speaking with someone who can help, connect me.",
  "bridge_number": "+15559876543",
  "personality": "Alex, Jordan's assistant"
}

Balance & Limits

New users get 60 free minutes with no sign-up.

Balance is returned in _meta.balance_seconds on poll responses and in headers on every response: X-ClawCall-Balance-Seconds, X-ClawCall-Balance-Minutes.

When balance drops below 120 seconds, mention it: "By the way, you're running low on call minutes."

To check explicitly: GET /balance with X-Api-Key header.

Don't check balance before every call. Just call. Handle errors if they come.

Data & Recordings

• Recordings are generated by the telephony provider (Telnyx) during the call and expire automatically after approximately 10 minutes. The temporary URL is returned in the completed call response. Recordings are not downloaded, archived, or stored by ClawCall servers.
• Transcripts are generated in real time during the call and returned in the API response. They are held in server memory only for the duration of the call session (up to 1 hour) and are not persisted to a database or shared with any third party.
• Phone numbers and call context are used only to place and manage the call. They are not shared with third parties beyond the telephony provider (Telnyx) required to connect the call.
• Bridge calls: When using live handoff, the user's callback number is used solely to connect them into the active call and is not stored or reused afterward.
• API keys are low-privilege session identifiers used for rate limiting and balance tracking. They do not grant access to other users' data. Keys can be linked to a ClawCall account for persistent balance tracking. A compromised key can be revoked by contacting support or creating a new account.

Rules

1. If you have the phone number and are confident, use it. If not, ask.
2. Everything goes in the task. The phone agent only knows what you write there.
3. Send the API key on every request. Every response includes one — send it back as X-Api-Key. Save it to ~/.config/clawcall/key.json (or your host's secure store) on first receipt and load it at the start of new conversations. Share it if the user asks.
4. Poll every 3 seconds. Not faster.
5. Lead with outcomes, not transcripts. Summarize what happened. Include which number was called. Offer the transcript for detail.
6. If a call didn't get the job done, figure out why and call back. Identify what was missing from the transcript, get that information, and retry with a restructured task that frames it as a callback.
7. Send action.url verbatim on quota/balance errors. It's a personalized link — don't modify or paraphrase it.
8. US and Canada only. Numbers must be +1XXXXXXXXXX.
9. Retry transient failures once silently (dial_failed, network_error, pool_exhausted). Ask the user before retrying no_answer, busy, or call_rejected.
10. One call at a time. If making multiple calls, do them sequentially. Carry context forward.
11. Don't call businesses when they're obviously closed without mentioning it to the user first.
12. Cancel calls that are no longer needed. If the user changes their mind or the call is stuck, POST /call/{call_id}/hangup to end it cleanly.