Skill: tuofangzhe/openclaw-phone-receipt (version 1.0.1)

--- name: openclaw-phone-receipt description: Trigger and manage OpenClaw outbound phone receipts via ElevenLabs+Twilio for task completion/failure notifications. Use when user asks to call them after finishing/failing a task, asks to enable/disable fixed command toggles ("phone-receipt=on/off"), asks to test call quality, or asks to persist phone receipt behavior across sessions. --- # OpenClaw Phone Receipt Use this skill to manage phone callback notifications. ## Commands to honor - `phone-receipt=on` → enable phone receipt policy - `phone-receipt=off` → disable phone receipt policy State file: - `memory/phone-receipt-state.json` ## Default behavior 1. If user asks for callback on completion/failure, set `enabled=true`. 2. Default policy is now: - `policy.onComplete=false` - `policy.onFailure=true` - `policy.onUrgent=true` 3. Persist state to `memory/phone-receipt-state.json`. 4. For immediate test call, run `scripts/trigger_call.sh`. ## Delivery strategy (must follow) - Phone call only when: 1) task failed, OR 2) user explicitly marks task as urgent (e.g., “urgent/high-priority”). - All other non-urgent successful tasks: - send Telegram text summary only (no phone call). When phone is not required by policy, use message delivery (Telegram text) as default receipt path. ## Tools/scripts - Toggle state: - `python3 skills/openclaw-phone-receipt/scripts/set_phone_receipt_state.py on` - `python3 skills/openclaw-phone-receipt/scripts/set_phone_receipt_state.py off` - Trigger call now: - `bash skills/openclaw-phone-receipt/scripts/trigger_call.sh` ## Call prerequisites Requires `.env.elevenlabs-call` with: - `ELEVENLABS_AGENT_ID` - `ELEVENLABS_OUTBOUND_PHONE_ID` - `TO_NUMBER` `ELEVENLABS_API_KEY` can come from shell env or `.env.elevenlabs-call`. For full setup (Twilio purchase/verify, ElevenLabs import, key scopes, troubleshooting), read: - `references/setup.md` For ClawHub upload checklist (version/changelog/size requirements), read: - `references/publish-clawhub.md` ## Failure handling If call fails, return concise root cause and next action: - unverified target number (Twilio trial) - missing ConvAI scope (`convai_read`) - missing agent/phone ids

path: scripts/set_phone_receipt_state.py
content: #!/usr/bin/env python3
import json
import os
import sys
from datetime import datetime, timezone, timedelta

if len(sys.argv) != 2 or sys.argv[1] not in {"on", "off"}:
    print("Usage: set_phone_receipt_state.py on|off")
    sys.exit(2)

state = sys.argv[1] == "on"
root = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../../"))
path = os.path.join(root, "memory", "phone-receipt-state.json")
os.makedirs(os.path.dirname(path), exist_ok=True)

now = datetime.now(timezone(timedelta(hours=8))).isoformat(timespec="seconds")
obj = {
    "enabled": state,
    "updatedAt": now,
    "keywords": {"on": "phone-receipt=on", "off": "phone-receipt=off"},
    "policy": {"onComplete": False, "onFailure": True, "onUrgent": True},
}

with open(path, "w", encoding="utf-8") as f:
    json.dump(obj, f, ensure_ascii=False, indent=2)

print(f"[OK] phone receipt {'enabled' if state else 'disabled'}: {path}")


path: scripts/trigger_call.sh
content: #!/usr/bin/env bash
set -euo pipefail

# Standalone trigger script for OpenClaw Phone Receipt skill.
#
# Required env vars:
# - ELEVENLABS_API_KEY
# - ELEVENLABS_AGENT_ID
# - ELEVENLABS_OUTBOUND_PHONE_ID
# - TO_NUMBER (E.164, e.g. +639178688896)
#
# Optional:
# - ENV_FILE (default: workspace/.env.elevenlabs-call)

ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../" && pwd)"
ENV_FILE="${ENV_FILE:-$ROOT/.env.elevenlabs-call}"

if [[ -f "$ENV_FILE" ]]; then
  # shellcheck disable=SC1090
  set -a; source "$ENV_FILE"; set +a
fi

: "${[REDACTED_SECRET] ELEVENLABS_API_KEY}"
: "${ELEVENLABS_AGENT_ID:?Missing ELEVENLABS_AGENT_ID}"
: "${ELEVENLABS_OUTBOUND_PHONE_ID:?Missing ELEVENLABS_OUTBOUND_PHONE_ID}"
: "${TO_NUMBER:?Missing TO_NUMBER}"

payload=$(python3 - <<'PY'
import json, os
print(json.dumps({
  "agent_id": os.environ["ELEVENLABS_AGENT_ID"],
  "agent_phone_number_id": os.environ["ELEVENLABS_OUTBOUND_PHONE_ID"],
  "to_number": os.environ["TO_NUMBER"],
}))
PY
)

resp=$(curl -sS -X POST "https://api.elevenlabs.io/v1/convai/twilio/outbound-call" \
  -H "xi-[REDACTED_SECRET]" \
  -H "Content-Type: application/json" \
  -d "$payload")

python3 - <<'PY' "$resp"
import json, sys
raw = sys.argv[1]
try:
    data = json.loads(raw)
except Exception:
    print(raw)
    raise SystemExit(0)

cid = data.get("conversation_id") or data.get("conversationId")
if cid:
    print(f"[OK] outbound call initiated, conversation_id={cid}")
    raise SystemExit(0)

print(json.dumps(data, ensure_ascii=False, indent=2))
if data.get("success") is False or data.get("error") or data.get("detail"):
    raise SystemExit(1)
PY


path: references/setup.md
content: # OpenClaw Phone Receipt Setup (ElevenLabs + Twilio)

Use this guide to enable automatic phone callback receipts for OpenClaw.

## Required parameters

### Twilio
- `TWILIO_ACCOUNT_SID` (example: `AC...`)
- `TWILIO_AUTH_TOKEN`
- `TWILIO_PHONE_NUMBER` (example: `+1812...`)
- Optional: `TWILIO_PHONE_NUMBER_SID` (example: `PN...`)

### ElevenLabs Agents
- `ELEVENLABS_API_KEY` (must include ConvAI scope, at least `convai_read`)
- `ELEVENLABS_AGENT_ID` (example: `agent_...`)
- `ELEVENLABS_OUTBOUND_PHONE_ID` (example: `phnum_...`)
- `TO_NUMBER` (target number in E.164, example: `+639178688896`)

## End-to-end setup flow

### 1) Buy a voice-enabled number in Twilio
Twilio Console -> Phone Numbers -> Buy a number.

### 2) Verify your target number (Trial accounts)
Twilio Console -> Phone Numbers -> Verified Caller IDs.

If not verified, outbound calls fail with:
`The number ... is unverified. Trial accounts may only make calls to verified numbers.`

### 3) Import number into ElevenLabs
ElevenLabs -> Agents Platform -> Phone Numbers -> Import number -> From Twilio.

Fill:
- Label
- Twilio Number (`+1...`)
- Twilio Account SID (`AC...`)
- Twilio Auth Token

After import, copy the generated `Outbound Phone ID` (`phnum_...`).

### 4) Configure Agent
ElevenLabs -> Agents -> select your agent.

Recommended:
- Set First Message
- Select a Primary voice
- Ensure Text-only mode is disabled for voice calls
- Publish changes

### 5) Configure OpenClaw env file

```bash
cp /Users/huang/.openclaw/workspace/skills/openclaw-phone-receipt/references/env-example.txt \
   /Users/huang/.openclaw/workspace/.env.elevenlabs-call
```

Set:
- `ELEVENLABS_API_KEY`
- `ELEVENLABS_AGENT_ID`
- `ELEVENLABS_OUTBOUND_PHONE_ID`
- `TO_NUMBER`

### 6) Test outbound call

```bash
bash /Users/huang/.openclaw/workspace/skills/openclaw-phone-receipt/scripts/trigger_call.sh
```

Success example:
`[OK] outbound call initiated, conversation_id=conv_...`

## Common pitfalls

1. Number format must be E.164
- Wrong: `0063...`
- Correct: `+63...`

2. Twilio Trial number not verified
- Calls to unverified targets fail

3. Missing ElevenLabs key scope
- Missing `convai_read` causes API failure

4. Agent in Text-only mode
- Call connects but no voice output

5. Not publishing agent changes
- Agent edits only take effect after Publish

## Runtime policy (default)

- Call only when task fails or is marked urgent
- Normal successful tasks send Telegram text summary only
- Toggle commands: `phone-receipt=on` / `phone-receipt=off`


path: references/env-example.txt
content: # Copy to workspace/.env.elevenlabs-call

[REDACTED_SECRET]
ELEVENLABS_OUTBOUND_PHONE_ID=
TO_NUMBER=+639178688896


path: references/publish-clawhub.md
content: # 发布到 ClawHub（Upload 要求对照）

根据 `clawhub.ai`/ClawHub v1 规范，上传前检查：

1. **必须包含 `SKILL.md`**
   - 含 YAML frontmatter
   - 至少包含：`name`、`description`

2. **每次上传是一个新版本**
   - `version` 必须唯一（不能和历史版本重复）

3. **changelog 必填**
   - 建议写清新增/修复/破坏性变更

4. **单版本总大小 ≤ 50MB**
   - 本 skill 为纯文本脚本，远低于限制

5. **文本文件为主**
   - 该 skill 仅包含 `SKILL.md` + `scripts/` + `references/`

6. **需要 GitHub 登录上传**
   - 账号龄通常需 ≥ 7 天（平台风控规则）

## 本 skill 建议发布信息

- slug/name: `openclaw-phone-receipt`
- summary: 失败/紧急任务自动电话回执，普通成功仅 Telegram 文本
- tags: `openclaw`, `automation`, `phone`, `twilio`, `elevenlabs`, `telegram`

## changelog 模板（可直接粘贴）

- Added fixed toggle commands: `电话回执=开/关`
- Added failure/urgent-only phone strategy
- Added standalone outbound call script (`scripts/trigger_call.sh`)
- Added full setup/troubleshooting guide for Twilio + ElevenLabs


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