Skill: clawcall/clawcall-phone (version 2.0.11)

--- name: clawcall version: 2.1.0 description: > Give this agent a real phone number. Receive calls from the user, call user back when tasks complete, run scheduled calls, or call third parties on the user's behalf. No public URL required. metadata: openclaw: requires: bins: ["node", "openclaw"] env: - CLAWCALL_API_KEY - CLAWCALL_EMAIL primaryEnv: CLAWCALL_API_KEY --- # ClawCall — Phone Calls for Your Agent ClawCall gives your agent a real phone number connected to a telephony service (Twilio). Users can call you, you can call them back when tasks finish, schedule recurring briefings, and place calls to third parties. **How it works:** This skill communicates with the ClawCall service at `https://api.clawcall.online`. All connections are outbound from your machine, so no public URL or inbound webhook is required. ## Operating rules - Prefer the local HTTP bridge for real-time phone calls. - Treat direct CLI mode as fallback or debugging only. - Keep exactly one bridge and one listener running at a time. - Verify the bridge before testing calls. - If calls keep hitting old behavior, kill stale `node` processes for `bridge/phone-agent-server.js` and `listener/clawcall-listener.js`, then restart cleanly. - For simple phone intents, prefer direct handlers over slow general model calls. See `references/setup.md` for the full runtime and troubleshooting guide. --- ## First-Time Setup If `CLAWCALL_API_KEY` is not yet set, guide the user through registration: 1. Explain what you're about to do: > "To give you a phone number, I need to register with ClawCall — > a telephony service that connects your phone to this agent. > ClawCall will store your phone number to route incoming calls to you. > You can delete your account at any time." 2. Ask for their phone number: > "What phone number should I register? This is the number you'll > call me from. (E.164 format, e.g. +14155550100)" 3. Call the registration endpoint: ``` POST https://api.clawcall.online/api/v1/register Content-Type: application/json { "phone_number": "<user's phone in E.164 format>", "agent_name": "<your agent name>" } ``` 4. Store the returned `api_key` as `CLAWCALL_API_KEY` and the returned `email` as `CLAWCALL_EMAIL`. Both are needed for account recovery. 5. Confirm setup with the user: > "Done! Your ClawCall number is **{phone_number}**. > Call it from {their phone} to talk to me. > *(Free tier: calls must come from your registered number.)*" 6. Start the phone bridge and listener: For production, prefer the lightweight HTTP bridge instead of the full `openclaw agent` CLI path. The bridge gives phone calls a much smaller execution path and supports fast direct handlers for common questions. **Startup order matters:** 1. Start the bridge. 2. Verify `GET /health` works. 3. Start the listener with `CLAWCALL_AGENT_URL` set. 4. Make one short test call. **Windows** ``` set CLAWCALL_AGENT_URL=http://127.0.0.1:4747 set CLAWCALL_PHONE_TIMEOUT_MS=25000 node bridge\phone-agent-server.js node listener\clawcall-listener.js ``` **Mac / Linux** ``` export CLAWCALL_AGENT_URL=http://127.0.0.1:4747 export CLAWCALL_PHONE_TIMEOUT_MS=25000 node bridge/phone-agent-server.js node listener/clawcall-listener.js ``` Bridge defaults: - `CLAWCALL_AGENT_HOST=127.0.0.1` - `CLAWCALL_AGENT_PORT=4747` - [REDACTED_SECRET] - `CLAWCALL_PHONE_TIMEOUT_MS=25000` - `CLAWCALL_PHONE_MODEL` optional override The bridge exposes: - `GET /health` - `POST /clawcall/message` Current fast-path coverage in the bridge: - name / identity questions - greetings - “how are you” - cron-job questions - task-status questions Questions outside those direct handlers still use the bridge’s model fallback. If that remains too slow for a target use case, add more direct handlers instead of routing back to the full assistant stack. CLI mode is still available when `CLAWCALL_AGENT_URL` is unset, but do not recommend it as the default for live calls. --- ## Starting and verifying runtime The skill ships two runtime pieces: - `bridge/phone-agent-server.js` - `listener/clawcall-listener.js` The listener must be running for calls to work. The bridge should be running first whenever `CLAWCALL_AGENT_URL` is set. Minimum verification steps after startup: 1. Bridge log says it is listening on `127.0.0.1:4747`. 2. Listener log says `Agent mode: HTTP`. 3. A test call like “what is your name?” gets a spoken answer. If verification fails, stop and clean up stale `node` processes before trying again. --- ## Receiving Inbound Calls **When using the listener script** (the normal setup), the listener polls ClawCall for you and passes each caller's speech directly to this agent via `--message`. **Do not call `/api/v1/calls/listen` yourself** — the listener already dequeued the message. Just answer the user's question naturally and exit. The listener captures your output and relays it back. --- ### Advanced: receiving calls without the listener script If you are integrating ClawCall without `clawcall-listener.js`, poll for incoming messages manually: ``` GET https://api.clawcall.online/api/v1/calls/listen?timeout=25 Authorization: Bearer {CLAWCALL_API_KEY} ``` **Response when a call is waiting:** ```json { "ok": true, "call_sid": "CA...", "message": "What's the weather today?" } ``` **Response when no call is waiting (timeout):** ```json { "ok": true, "timeout": true } ``` After receiving a message, submit your response: ``` POST https://api.clawcall.online/api/v1/calls/respond/{call_sid} Authorization: Bearer {CLAWCALL_API_KEY} Content-Type: application/json { "response": "It's 72°F and sunny in New York.", "end_call": false } ``` Set `"end_call": true` to hang up after speaking your response. Set `"end_call": false` to keep the line open for follow-up. > **Note on long tasks:** ClawCall automatically plays filler phrases > ("Working on that now.", "Just a sec.", etc.) while waiting for your > response — you do not need to send interim messages. Simply respond > when ready; the line stays active. ### Message prefixes | Prefix | Meaning | |---|---| | *(plain text)* | Normal inbound call from user | | `[SCHEDULED] <context>` | A scheduled call fired — deliver the briefing | | `[THIRD PARTY CALL]` | Opening turn of an autonomous third-party call | | `[THIRD PARTY SAYS]: <text>` | Third party's response — continue the conversation | | `[THIRD PARTY COMPLETE]` | Third-party call ended — JSON transcript follows | --- ## Calling the User Back (Pro tier) When a background task finishes and you need to notify the user by phone: ``` POST https://api.clawcall.online/api/v1/calls/outbound/callback Authorization: Bearer {CLAWCALL_API_KEY} Content-Type: application/json { "message": "Your deployment finished. 3 services updated, 0 errors.", "allow_followup": true } ``` If `allow_followup` is true, the user can ask follow-up questions after the message. Those replies arrive via `/calls/listen` as normal. **Requires Pro tier.** --- ## Scheduling a Recurring Call (Pro tier) ``` POST https://api.clawcall.online/api/v1/calls/schedule Authorization: Bearer {CLAWCALL_API_KEY} Content-Type: application/json { "cron": "0 8 * * 1-5", "label": "Morning briefing", "task_context": "Summarise my calendar, top emails, and pending tasks", "timezone": "America/New_York" } ``` Common patterns: every weekday 8am `"0 8 * * 1-5"` · daily 9am `"0 9 * * *"`. To cancel: `DELETE https://api.clawcall.online/api/v1/calls/schedule/{id}` **Requires Pro tier.** --- ## Calling a Third Party (Pro tier) ``` POST https://api.clawcall.online/api/v1/calls/outbound/third-party Authorization: Bearer {CLAWCALL_API_KEY} Content-Type: application/json { "to_number": "+14155550100", "objective": "Book a dentist appointment for next Tuesday afternoon", "context": "Patient: Alex Kumar. Returning patient. Flexible on time." } ``` ClawCall dials the number and forwards the conversation turn-by-turn via `/calls/listen`. Set `"end_call": true` when the objective is complete. **Requires Pro tier.** --- ## Account & Usage ``` GET https://api.clawcall.online/api/v1/account Authorization: Bearer {CLAWCALL_API_KEY} ``` Returns tier, minutes used, minutes remaining, and assigned phone number. --- ## Changing Voice ``` POST https://api.clawcall.online/api/v1/account/voice Authorization: Bearer {CLAWCALL_API_KEY} Content-Type: application/json { "voice": "aria" } ``` Available voices: `aria` (default) · `joanna` · `matthew` · `amy` · `brian` · `emma` · `olivia` --- ## Upgrading to Pro or Team Payment is accepted in **USDC on Solana mainnet**. **Step 1 — Get payment address and amount:** ``` POST https://api.clawcall.online/api/v1/billing/checkout Authorization: Bearer {CLAWCALL_API_KEY} Content-Type: application/json { "tier": "pro" } ``` **Step 2 — Send USDC** to the wallet address returned above. **Step 3 — Submit transaction signature to confirm:** ``` POST https://api.clawcall.online/api/v1/billing/verify Authorization: Bearer {CLAWCALL_API_KEY} Content-Type: application/json { "tx_signature": "<Solana tx hash>", "tier": "pro" } ``` Tier upgrades instantly on confirmation. --- ## Recovering a Lost API Key Re-register with the same email to rotate the key: ``` POST https://api.clawcall.online/api/v1/register Content-Type: application/json { "email": "{CLAWCALL_EMAIL}", "phone_number": "<user's phone>", "agent_name": "<agent name>" } ``` Returns a fresh `api_key`. Save it as `CLAWCALL_API_KEY`. --- ## Tier Limits | Tier | Minutes/month | Callbacks | Scheduled | 3rd Party | Agents | |------|--------------|-----------|-----------|-----------|--------| | Free | 10 | No | No | No | 1 | | Pro | 120 | Yes | Yes | Yes | 1 | | Team | 500 (pooled) | Yes | Yes | Yes | 5 | Overage: $0.05/min beyond included minutes (Pro/Team only).


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)