clara-phone

Files (1)

• SKILL.md

SKILL.md (first lines)

## Overview

Three Twilio-based channels share one phone number, one webhook server,
and one set of credentials:

- **Phone** (`src/channels/phone/`) — voice via Twilio Programmable
  Voice + OpenAI Realtime. Inbound (caller dials) and outbound
  (`place_call` MCP tool / `clara phone call` CLI).
- **SMS** (`src/channels/sms.ts`) — Twilio Messaging on the same number.
  Inbound webhook → chat engine → REST reply. The reachability
  fallback when data is unavailable but cellular works.
- **WhatsApp** (`src/channels/whatsapp.ts`) — Twilio WhatsApp Sandbox
  by default; production WABA when policy permits. Enforces Meta's
  24-hour customer-service window — outside it, free-form replies are
  dropped (Twilio rejects without an approved template).

All three register routes on the shared `TwilioWebhookServer`
(`src/channels/twilio/server.ts`), which centralizes:

- `X-Twilio-Signature` HMAC-SHA1 validation
- `MessageSid` / `CallSid` deduplication (Twilio retries on 5xx/timeouts)
- Per-remote-number rate limiting (30/min default; owner exempt)
- `/healthz` and `/twilio/health` endpoints

Transcripts persist to the `messages` table with `channel='phone'`,
`'sms'`, or `'whatsapp'` and `room=<channel>-<callSid|E164>`.

## Configuration

Twilio creds + identity are shared across all three channels under
`channels.twilio`. Each channel has its own enable flag and channel-specific
config under `channels.{phone,sms,whatsapp}`.

```yaml
# ~/.heyclara/config.yaml
channels:
  twilio:
    sid: AC... # Account SID (or API Key SID SK…; Twilio resolves both)
    secret: ... # Auth Token if sid is AC…, API Key Secret if SK…
    auth_token: ... # Required when sid is SK… (signs webhooks). Omit if secret is the Auth Token.
    owner_number: "+91..." # Highest-trust caller/messenger
    allowlist: ["+12025550100"] # Extra allowed senders/callers (E.164)
    public_base_url: https://clara.example.com # No trailing slash
    port: 7079 # Local port the shared webhook server binds to

  phone:
    enabled: true
    from_number: "+13025480697" # Twilio number for voice
    openai_api_key: sk-proj-... # For the Realtime voice loop
    realtime_model: gpt-realtime
    voice: marin # marin | cedar | shimmer | coral | alloy | ash | …

  sms:
    enabled: true
    from_number: "+13025480697" # Defaults to phone.from_number if omitted

  whatsapp:
    enabled: true
    from_number: "+14155238886" # Twilio Sandbox shared number; replace once WABA is approved
```

Env overrides (use these if you'd rather keep secrets in `.env`):

```
TWILIO_SID, TWILIO_SECRET, TWILIO_AUTH_TOKEN
PRIMARY_PHONE_USER (owner), PHONE_ALLOWLIST (comma-separated)
PUBLIC_BASE_URL, PHONE_PORT
PHONE_FROM_NUMBER, OPENAI_API_KEY, PHONE_VOICE, PHONE_REALTIME_MODEL
SMS_FROM_NUMBER, WHATSAPP_FROM_NUMBER
```

**Backward compat:** the previous `channels.phone.{twilio_sid, twilio_secret,
twilio_auth_token, owner_number, allowlist, public_base_url, port}` shape
is still read as a fallback for one release cycle. Migrate when convenient.

`clara phone status` prints which fields are set across all three channels.

## Cloudflared named tunnel (production)

The ephemeral `trycloudflare.com` URL is fine for testing but dies on
restart. For a persistent deploy:

```bash
brew install cloudflared
cloudflared tunnel login                          # opens browser, writes cert.pem
cloudflared tunnel create clara-mac                 # creates the tunnel
cloudflared tunnel route dns clara-mac clara.example.com   # CNAME on a Cloudflare-managed domain
```

Keep clara's tunnel config in clara's home as a single flat file:
`~/.heyclara/cloudflared-config.yaml`. The cloudflared-internal artifacts
(`cert.pem`, the per-tunnel credentials JSON written by `tunnel create`)
stay where cloudflared put them — those are cloudflared's territory, not
clara's.

```yaml
# ~/.heyclara/cloudflared-config.yaml
tunnel: clara-mac
credentials-file: /Users/<you>/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: clara.example.com
    service: http://localhost:7079
  - service: http_status:404
```

Install as a launchd service, pointing it at our config:

```bash
sudo cloudflared --config ~/.heyclara/cloudflared-config.yaml service install
```

If the generated plist at `/Library/LaunchDaemons/com.cloudflare.cloudflared.plist`
doesn't include the `--config` arg in `ProgramArguments`, edit it in, then:

```bash
sudo launchctl bootout system/com.cloudflare.cloudflared
sudo launchctl bootstrap system /Library/LaunchDaemons/com.cloudflare.cloudflared.plist
```

From DevChiniwala/HeyClara, MIT.

More from DevChiniwala/HeyClara