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

CODEBLOCK0

CODEBLOCK1

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):

CODEBLOCK2

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:

CODEBLOCK3

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:

CODEBLOCK4

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

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:

CODEBLOCK5

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. 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:

CODEBLOCK6

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

failReason	Tell the user	Next step
INLINECODE22	"No one picked up."	Offer to try again. Ask if there's a better time.
INLINECODE23

"The line was busy." | Offer to retry in a moment. | | call_rejected | "The call was declined." | They may screen unknown numbers. Suggest the user call directly, or try bridge mode. | | invalid_number | "That number doesn't seem to be valid." | Ask to double-check. Don't retry. | | unreachable | "That number appears to be out of service." | Ask to verify the number. Don't retry. | | dial_failed | — | Retry once silently. If it fails again, tell the user. | | network_error | — | Retry once silently. If it fails again, tell the user. |

---

Errors on POST /call

Out of free minutes (quota_exceeded, 429)

CODEBLOCK7

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

Code	What to do
INLINECODE35 (400)	Must be US/Canada +1. Ask user to correct it.
INLINECODE37 (400)

to and task are both required. | | dial_failed (502) | Retry after a few seconds. |

---

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. 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

CODEBLOCK8

---

Balance & Limits

New users get 20 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. 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.