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

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

Overage: $0.05/min beyond included minutes (Pro/Team only).