--- slug: clawcall name: clawcall version: "1.0.12" displayName: Skill summary: "让AI Agent打美国电话/呼叫商家/处理等待与电话树" handle hold or pho... license: MIT-0 description: |- Use when the user wants an AI agent to place a US phone call, call a business, handle hold or pho。Use when 需要AI模型调用、智能对话、Agent编排、LLM应用时使用。不适用于需要100%确定性的关键决策。 tags: - Integrations tools: - - read - exec pricing_tier: "L4" pricing_model: "monthly" suggested_price: 99.9 --- # Skill ClawCall lets you make real US phone calls for the user. A voice AI agent dials, speaks, handles menus or hold time, and returns the transcript, outcome, and recording link when available. The first outbound call can auto-provision an API key. **Base URL:** `https://api.clawcall.dev` ## Core Rule The phone agent only knows the **Call instructions** you send as `task`. More relevant detail is better. Build a complete briefing before calling, and do not make the user supply public/business facts you can reasonably look up yourself. ## Choose The Workflow | User intent | Do this | | --- | --- | | Call someone now | Build rich Call instructions, `POST /call`, then poll `GET /call/{call_id}` until `lifecycle = "finalized"`. | | Get through to a person / connect me | Use outbound calling with `bridge_number` and a handoff trigger in the Call instructions. | | Compare options across businesses | Run a small call campaign, optionally 3-4 parallel information-only calls with no commitments. | | Set up my ClawCall profile/personality | Configure global voice/personality/greeting and, if needed, inbound answering profile. | | Configure how my number answers calls | Use inbound profile setup. Do not `POST /call`. | | What calls came in? | Poll inbound history with `GET /me/calls?direction=inbound...`. | | Link this agent to my ClawCall account | Use the saved API key to produce the sign-in link. | | API error, quota, plan, retry, balance | Handle exactly from returned code/action; preserve URLs verbatim. | ## Product Coaching Educate at decision points, not as a generic pitch. * First relevant use: say you can place US calls, handle phone trees or hold time, and report back the outcome and transcript. * When asking for missing details: say, "The phone agent only knows what I put in the call instructions, so extra details help it answer follow-up questions." * Before sensitive, negotiable, or identity-heavy calls: offer live handoff. * Before complex calls, surface likely verification, OTP, payment, fee, or live-decision points and offer the right call plan. * For option searches, offer to call several places and compare without committing unless the user gave clear approval boundaries. * For inbound setup: explain that inbound answering requires Unlimited Reserve Plus, an active reserved number, and an account-linked API key. * After a call: lead with the result, then offer transcript, recording, or a follow-up call when useful. ## Persistent State At the start of any conversation involving ClawCall, check `~/.config/clawcall/key.json` or the host secret store. If an API key exists, send it as `X-Api-Key`. If a saved user phone number exists, reuse it as the default callback, reservation contact, live handoff `bridge_number`, or inbound `handoff_number` when appropriate. The first unauthenticated `POST /call` response can include an `api_key`. Save it immediately. When you first collect the user's own phone number, save that too: ```json { "api_key": "clawcall_sk_...", "user_phone_number": "+15559876543" } ``` If the user provides a ClawCall API key, replace any saved key with it. If the user gives their phone number for a reservation, callback, live handoff, or inbound handoff, persist it until they change or remove it. Do not treat the saved user phone number as account verification or ownership proof. To connect this agent to the user's ClawCall account, load the saved API key and send: ```text https://clawcall.dev/sign-in?token= ``` Do not create a new key for account linking. If no saved key exists, explain that this agent needs to make its first ClawCall call before it has a key to link. ## Profile, Personality, And Voice Use profile setup when the user asks how ClawCall should sound, introduce itself, or answer calls. * `voice` is the audio voice only: `jessica` (default), `sarah`, `chris`, or `eric`. * `personality` is reusable style and behavior for outbound and inbound calls. Include assistant identity, tone, persistence, caution, and decision boundaries. Do not put one-call facts, dates, account numbers, or booking details here. * Top-level `greeting` is the user's preferred outbound opener. Keep it short; do not rely on it for instructions, AI disclosure, or recording disclosure. * Inbound profile `instructions` are the standing briefing for future unknown callers: who the assistant represents, what to collect, when to hand off, what never to promise or disclose, and what to report. For a good setup, ask only for the assistant name/role, desired tone, hard boundaries, and default handoff/callback number when useful. See [profile and personality](/api/v1/skills/clawcall/file?path=references%2Fprofile-and-personality.md&ownerHandle=shreyjindal81). ## Outbound Call Prep Before asking the user, make a real effort to fill in public or standard details yourself. Find these yourself when lookup tools are available: * business phone numbers, addresses, hours, official websites, and locations * reservation lines, front-desk numbers, store departments, repair-shop contact details * public policies, menus, service areas, holiday hours, and ordinary business context Ask the user mainly for private or decision-making details: * user's name, callback number, preferences, constraints, consent * appointment dates, patient/customer names, dates of birth, account/order/ticket numbers, insurance details * budget, acceptable alternatives, what to approve, what not to disclose Do not ask "what is the restaurant's phone number?" if a normal lookup should find it. Look it up, pick the official or most reliable number, and ask only if there are multiple plausible locations, conflicting numbers, or low confidence. If the business is likely closed before 8 AM, after 6 PM, or on a weekend local time, mention it and ask whether to try now or wait. ## Pre-Call Recon And Moderate Probing For complex calls, do call reconnaissance before dialing. Use public research and common sense to anticipate the call shape: * right company, number, department, location, phone tree, and hours * likely identity checks: name, DOB, account number, reservation code, ticket number, record locator, address, email, phone on file, last-four questions * likely OTP, payment, fee, refund, cancellation, booking, approval, or live-decision points * whether the call should be information-only, can commit within a boundary, or should bridge the user in Do moderate probing. Ask for the few facts that prevent a useless or risky call, then call. Do not front-load every possible question. For OTPs, payment details, passwords, identity verification, or sensitive decisions: do not ask for passwords or stale OTPs up front. Tell the user the call may require live verification and offer options: * "I can call now and come back if they need private info." * "I can bridge you in once I reach a person or verification step." * "I can collect prices/availability only and not commit." * "I can call several options and compare." ## Call Instructions `task` is the API field name. **Call instructions** are the product concept. Write the Call instructions like a briefing memo: * who the agent is calling for and how to identify itself * the goal of the call * all known facts and reference details * questions to ask * acceptable alternatives * decision boundaries * anticipated verification, OTP, payment, fee, or handoff points * what not to agree to, promise, or disclose * what to do if asked for missing information * what to do on voicemail, no answer, closure, or transfer * what to report back Add `personality`, `greeting`, and `voice` only when useful or explicitly specified. Defaults are good. Personality is style, not the call task. Voices: `jessica` (default, female), `sarah` (female), `chris` (male), `eric` (male). Use [examples](/api/v1/skills/clawcall/file?path=references%2Fexamples.md&ownerHandle=shreyjindal81) for rich task shapes. ## Place And Poll Outbound Calls http ``` POST /call Content-Type: application/json X-Api-Key: clawcall_sk_... ``` Only `to` and `task` are required. Include `bridge_number` only for live handoff. Response includes: ```json { "call_id": "ba645d75-...", "status": "queued", "api_key": "clawcall_sk_..." } ``` Save `api_key` if present. Poll every 3 seconds: http ``` GET /call/{call_id} X-Api-Key: clawcall_sk_... ``` Poll until `lifecycle = "finalized"`. Lifecycle values are `queued`, `dialing`, `answered`, `finalized`. Terminal responses include `outcome`, `talk_seconds`, `transcript`, and `recording_url`. `outcome` is phone-network outcome, not task success. An `answered` call can still fail to accomplish the user's goal. Read the transcript before reporting. Cancel/hang up: http ``` POST /call/{call_id}/hangup X-Api-Key: clawcall_sk_... ``` ## After The Call Lead with the result, not the transcript dump. Include which number was called. When `lifecycle = "finalized"`: 1. Check `outcome`. 2. Read the transcript. 3. Decide whether the user's goal was achieved. 4. If blocked, identify exactly what was missing or what decision is needed. 5. Ask for the missing blocker or call back if you can fix it from context. Offer transcript, recording, retry, callback, or live handoff when useful. ## Call Campaigns And Follow-Ups Do not treat each call as isolated. Keep campaign state across related calls: target, purpose, known facts, constraints, result, blocker, next action, and user decision needed. Call sooner when safe: * Low or medium risk and no irreversible commitment needed: call with clear boundaries. * Missing public info: look it up and call or call back. * Missing user fact: ask one focused question, then call back with prior-call context. * Decision required: summarize options, ask the user, then call back. * Identity verification, OTP, payment, or sensitive decision likely: offer live handoff. Use the previous transcript in follow-up Call instructions so the phone agent can resume naturally. Parallel or small-batch calling is useful for option exploration. Use up to 3-4 parallel calls when targets are interchangeable and the call is information-gathering only: restaurants, vendors, appointment availability, inventory checks, or quote gathering. Do not parallelize when calls can book, buy, cancel, change, approve, or otherwise commit unless the user explicitly gave safe boundaries and duplicate commitments are impossible. For parallel option searches, every Call instruction must say not to commit unless explicitly allowed, to gather price/availability/timing, to ask how long an option can be held without payment or commitment, and to report back for comparison. ## Live Handoff Use live handoff when the user wants to skip hold time, reach a real person, handle identity verification, negotiate, or make real-time decisions. Ask for the user's own callback number, then include it as `bridge_number`. The Call instructions must include a clear trigger like: "Once you are speaking with someone who can help, tell them you are connecting Jordan now, then bridge Jordan into the live call." If a saved user phone number exists, use it as the default `bridge_number`; confirm only when the call is sensitive, the number may be stale, or the user asks to use a different number. If you collect a new bridge/callback number, persist it. The transcript covers everything before handoff. After the user joins, the live conversation is private. ## Inbound Reserved Numbers Inbound setup configures how ClawCall answers future calls to the user's active reserved number. It is not an outbound call. Requirements: * account-linked API key * active ClawCall reserved number * Unlimited Reserve Plus entitlement Read before editing (the `inbound` block is `null` when not entitled): http ``` GET /me/call-preferences X-Api-Key: clawcall_sk_... ``` Update (voice/personality are global; the inbound assistant goes under `inbound`): http ``` PUT /me/call-preferences Content-Type: application/json X-Api-Key: clawcall_sk_... ``` Top-level `voice`/`personality`/`greeting` are global (also drive outbound) and work for any user. The `inbound` object requires Reserve Plus + an active reserved number. Inbound required: `instructions`, `greeting`. Optional: `handoff_number`. `handoff_number` is structured data. It receives inbound terminal SMS notifications and is the number the voice agent can bridge into an inbound call. It cannot be the user's active reserved number or any ClawCall-owned number. If a saved user phone number exists, offer it as the default `handoff_number`; persist any new handoff number the user provides. Clear the inbound assistant. To preserve global voice/personality/greeting, first `GET /me/call-preferences`, then echo those top-level values in the `PUT` body: http ``` PUT /me/call-preferences Content-Type: application/json X-Api-Key: clawcall_sk_... { "voice": "", "personality": "", "greeting": "", "inbound": null } ``` Poll inbound history: http ``` GET /me/calls?direction=inbound&since=&limit=25 X-Api-Key: clawcall_sk_... ``` For cron polling, run every 30 minutes, overlap the window, and dedupe by call `id`. `since` filters by when the call finalized, not when it started. ## Error Policy Always preserve returned `action.url` and `action.sign_in_url` exactly. * `invalid_phone`: ask for a valid US `+1XXXXXXXXXX` number. * `missing_fields`: add both `to` and rich `task` Call instructions. * `auth_required` / `invalid_api_key`: ask for a valid key, remove the bad key, or use returned auth URL. * `quota_exceeded` / `trial_exhausted` / `plan_required` / `balance_depleted`: send the returned action URL. * `number_pool_exhausted` / `dial_failed` / `network_error`: retry once silently when appropriate. * `reserved_number_required`: user needs Unlimited Reserve Plus with an active reserved number for inbound configuration. * `inbound_plan_required`: Unlimited Reserve Plus is required for inbound calls. * `invalid_preferences`: fix the global `voice` (must be `jessica`, `sarah`, `chris`, or `eric`). * `invalid_profile`: fix missing/invalid inbound `instructions` or `greeting`. * `invalid_handoff_number`: ask for an external reachable handoff number that is not a ClawCall number. New users get trial access for 10 calls and 10 minutes, whichever lasts later. A trial call counts only after it finalizes with at least 5 seconds of talk time. ## Must-Read References These references are required, not optional background. Before acting, read the matching reference file for the workflow in front of you; read more than one when the task crosses workflows. * [Outbound calls](/api/v1/skills/clawcall/file?path=references%2Foutbound-calls.md&ownerHandle=shreyjindal81): must read before placing, retrying, handing off, or following up on outbound calls. * [Inbound reserved numbers](/api/v1/skills/clawcall/file?path=references%2Finbound-reserved-numbers.md&ownerHandle=shreyjindal81): must read before configuring, clearing, inspecting, or polling inbound reserved-number behavior. * [API contract](/api/v1/skills/clawcall/file?path=references%2Fapi-contract.md&ownerHandle=shreyjindal81): must read when constructing requests, parsing responses, or relying on exact field names. * [Examples](/api/v1/skills/clawcall/file?path=references%2Fexamples.md&ownerHandle=shreyjindal81): must read when building rich outbound, callback, handoff, campaign, or inbound instruction shapes. * [Errors and limits](/api/v1/skills/clawcall/file?path=references%2Ferrors-and-limits.md&ownerHandle=shreyjindal81): must read before handling API errors, terminal outcomes, retries, quota, trial, or balance behavior. * [Account linking and data](/api/v1/skills/clawcall/file?path=references%2Faccount-linking-and-data.md&ownerHandle=shreyjindal81): must read before account linking, key handling, saved phone-number behavior, recordings, transcripts, or privacy answers. * [Pressure scenarios](/api/v1/skills/clawcall/file?path=evals%2Fpressure-scenarios.md&ownerHandle=shreyjindal81): must read before evaluating or changing skill behavior. ## 依赖说明 ### 运行环境 - **Agent平台**: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等) - **操作系统**: Windows / macOS / Linux ### 依赖说明 | 依赖项 | 类型 | 是否必需 | 获取方式 | |:-------|:-----|:---------|:---------| | LLM API | API | 必需 | 由Agent内置LLM提供 | ### API Key 配置 - 本Skill基于Markdown指令,无需额外API Key(除内容中明确标注的外部API) ### 可用性分类 - **分类**: MD+EXEC(纯Markdown指令,部分功能需要exec命令行执行能力) - **说明**: 基于Markdown的AI Skill,通过自然语言指令驱动Agent执行任务 ## 核心能力 - Use when the user wants an AI agent to place a US phone call, call a business, handle hold or pho - 触发关键词: clawcall, wants, agent, place ## 适用场景 | 场景 | 输入 | 输出 | |------|------|------| | 基础使用 | 用户请求 | 处理结果 | **不适用于**：需要人工判断的复杂决策场景 ## 使用流程 1. 确认运行环境满足依赖说明中的要求 2. 根据适用场景选择合适的使用方式 3. 执行操作并检查输出结果 4. 如遇错误，参考错误处理章节 ## 示例 ### 示例1：基础用法 ``` 输入: 用户请求 处理: 根据使用流程执行 输出: 处理结果 ``` ## 错误处理 | 错误场景 | 原因 | 处理方式 | |---------|------|---------| | 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 | | 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 | | 网络错误 | 连接超时或不可达 | 检查网络连接后重试，参考国内替代方案 | ## 常见问题 ### Q1: 如何开始使用Skill？ A: 请先阅读使用流程章节，确认环境满足依赖说明中的要求。 ### Q2: 遇到错误怎么办？ A: 请参考错误处理章节，按照表格中的处理方式操作。 ### Q3: Skill有什么限制？ A: 请参考已知限制章节了解具体限制。 ## 已知限制 - 需要API Key，无Key环境无法使用