home / skills / openclaw / skills / openclaw-phone-receipt

openclaw-phone-receipt skill

safe

/skills/tuofangzhe/openclaw-phone-receipt

This skill manages outbound phone receipt notifications via ElevenLabs and Twilio, enabling timely callbacks after task completion or failure.

npx playbooks add skill openclaw/skills --skill openclaw-phone-receipt

Review the files below or copy the command above to add this skill to your agents.

Files (7)

SKILL.md

2.2 KB

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

Overview

This skill manages outbound phone receipt notifications using ElevenLabs and Twilio for task completion or failure alerts. It lets users enable or disable persistent phone-receipt behavior, trigger immediate test calls, and enforce delivery rules that prioritize phone calls for failures or urgent items. State is persisted so settings survive sessions.

How this skill works

The skill inspects incoming user commands and task outcomes, toggling a persisted phone-receipt policy stored in memory/phone-receipt-state.json. It honors explicit commands (phone-receipt=on/off), runs a trigger script for immediate test calls, and uses delivery logic: calls only for failures or user-marked urgent tasks; otherwise send Telegram text summaries. Call prerequisites (agent, phone IDs, and keys) must be configured in environment files.

When to use it

User requests a callback after a task completes or fails.
User wants to enable or disable persistent phone receipt behavior across sessions.
User asks to test or verify outbound call quality immediately.
User marks a task as urgent/high-priority and needs phone escalation.
You need automated failure alerts sent by phone rather than text.

Best practices

Enable phone-receipt only for important workflows to avoid unnecessary calls.
Keep ELEVENLABS and Twilio credentials in the designated environment file and verify required scopes and IDs before enabling calls.
Use test calls after configuration changes to confirm audio, number verification, and agent settings.
Persist state via the provided memory file so toggles survive restarts.
Prefer Telegram text receipts for routine successful tasks to reduce costs and call volume.

Example use cases

After a long-running data pipeline fails, trigger an immediate phone receipt to the on-call engineer.
User says “phone-receipt=on” to enable persistent phone alerts for subsequent high-priority tasks.
Run a test with the trigger_call.sh script after importing an ElevenLabs agent to verify outbound audio quality.
Disable phone receipts with phone-receipt=off to switch all non-urgent notifications to Telegram text summaries.
Mark a task urgent so the skill escalates the final status via telephone rather than a Telegram message.

FAQ

What environment values are required to make calls?

You must supply ELEVENLABS_AGENT_ID, ELEVENLABS_OUTBOUND_PHONE_ID, TO_NUMBER in .env.elevenlabs-call and an ELEVENLABS_API_KEY via env or file.

When will the skill place a phone call?

A call is placed only if a task fails or the user explicitly marks the task urgent; all other successful non-urgent tasks use Telegram text summaries.

What should I do if a call fails?

Check for an unverified target number (Twilio trial), ensure the convai_read scope and required agent/phone IDs are present, and review the concise root-cause message returned by the skill.