clawcall-phone

---

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": "",
  "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 - CLAWCALL_PHONE_MODEL_MODE=gateway - 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:

{
  "ok": true,
  "call_sid": "CA...",
  "message": "What's the weather today?"
}

Response when no call is waiting (timeout):

{ "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] | A scheduled call fired — deliver the briefing | | [THIRD PARTY CALL] | Opening turn of an autonomous third-party call | | [THIRD PARTY SAYS]: | 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": "", "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": "",
  "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).