clawcall

Category: Business & Operations | Uploader: ClawCall-Dev | Downloads: 0 | Version: v1.0（Latest）
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. No setup needed — works on the first call.
Changelog: Source: GitHub https://github.com/ClawCall-Dev/ClawCall
Directory Structure

Current level: tree/master/
📄 .gitignore 274 B
📄 LICENSE 1.0 KB
📄 README.md 1.1 KB
📄 SKILL.md 11.7 KB
SKILL.md

---
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. No setup needed — works on the first call.
---

# 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. No setup or API keys needed — the first call just works.

**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](#live-handoff).

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** — `rachel` (default, female), `adam` (male), `bella` (female), `josh` (male).

---

## Making the Call

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

```json
{
  "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": "rachel",
  "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](#live-handoff)).

**Response (201):**

```json
{
  "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. Never show the API key to the user — it's an internal detail.

---

## 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:**

```json
{
  "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:

```json
{
  "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

| failReason | Tell the user | Next step |
|------------|---------------|-----------|
| `no_answer` | "No one picked up." | Offer to try again. Ask if there's a better time. |
| `busy` | "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)

```json
{
  "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

| Code | What to do |
|------|------------|
| `invalid_phone` (400) | Must be US/Canada `+1`. Ask user to correct it. |
| `missing_fields` (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. 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

```json
{
  "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 **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.

---

## 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`. Never show it to the user.
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.
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
clawcall

Directory Structure

SKILL.md

Report

Notice
