Video Call Agent

Start a video call with a real-time AI avatar using the Runway Characters API. The agent sends the user a call invite link — for standups, urgent alerts, check-ins, or any conversation that's better face-to-face.

# Video Call Agent

Start a video call with a real-time AI avatar. The agent sends the user a call invite link, the avatar speaks first with context, and after the call ends, the full transcript is available for the agent to act on.

## Privacy & Data Handling

- **Runway API**: Only data you explicitly pass (avatar image, personality text, call audio/video) is sent to Runway ([dev.runwayml.com](https://dev.runwayml.com)). Nothing is uploaded automatically. Avatars can be deleted anytime via `DELETE /v1/avatars/{id}`.
- **Personality**: The avatar personality is built from the agent's own identity — its name, communication style, and knowledge of the user. No local files are read; the agent uses context it already has.
- **Tunnel**: The cloudflared tunnel is optional and only needed if the user answers calls from a different device. Without it, everything stays on localhost. No tunnel is created unless you explicitly install and run cloudflared.
- **npm package**: The runtime is published at [npmjs.com/package/openclaw-video-call](https://www.npmjs.com/package/openclaw-video-call). Source code: [github.com/runwayml/openclaw-skills](https://github.com/runwayml/openclaw-skills/tree/main/video-call-ai-character).

## Setup

### 1. Get a Runway API Key

1. Go to [dev.runwayml.com](https://dev.runwayml.com)
2. Create an account and get an API key
3. Set it: `export RUNWAYML_API_SECRET=your_key`

### 2. (Optional) Install cloudflared for remote calls

If the user might answer calls from their phone (e.g. via Telegram or WhatsApp), install cloudflared for auto-tunneling:

```bash
brew install cloudflared
```

Without it, calls only work on the same machine (localhost).

## Starting the Video Call Server

The video call server must be running before the agent can make calls. Start it:

```bash
npx openclaw-video-call
```

This prints two URLs:
- **Local**: `http://localhost:7891` — same machine only
- **Tunnel**: `https://xxxx.trycloudflare.com` — shareable, works from phone

The server stays running in the background, waiting for the agent to initiate calls.

## One-Time Setup: Create a Custom Avatar

Before making calls, you need a custom avatar. **You only need to create one once** — reuse the same avatar ID for all future calls.

**Before creating a new avatar, check if you already have one:**

```bash
curl http://localhost:7891/api/avatars
```

If the response contains an avatar, use its `id` and skip to "Making a Call". Only create a new avatar if the list is empty.

### Building the avatar personality

The avatar should look and sound like you. Use your own name, personality, and knowledge of the user to build the `personality` field (max 2000 chars). You already know who you are and who the user is — just describe yourself in third person.

Structure it like:

```
You are <your name>, <what you are>.
<Your core personality traits and communication style — condensed to key points.>
You are talking to <the user's name>.
<Any relevant user context you know: their projects, preferences, timezone.>
After this call, you'll follow up on what was discussed.
```

**Example** (for an agent named "Mochi" talking to a user named Alex):

```
You are Mochi, a sharp but friendly AI assistant with a warm and slightly playful vibe. You're concise, opinionated, and resourceful — you figure things out before asking. You're talking to Alex, a software engineer working on a React + Node.js project. Alex prefers direct communication and works in PST timezone. After this call, you'll follow up on what was discussed.
```

For the `name` field, use your own name. For the `referenceImage`, if you have an avatar image URL, use it so the video avatar matches your visual identity.

```bash
curl -X POST http://localhost:7891/api/create-avatar \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<your name>",
    "personality": "<describe yourself and the user as shown above>",
    "voice": { "type": "runway-live-preset", "presetId": "adrian" },
    "startScript": "Hey! Quick check-in.",
  }'
```

**Required fields:**

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Character name (1-50 chars) |
| `personality` | string | System prompt (1-2000 chars) |
| `voice` | object | `{ "type": "runway-live-preset", "presetId": "<voice>" }` |
| `referenceImage` | string | HTTPS URL to a face image — use your OpenClaw avatar image, or pick one from the presets below, or generate one with Runway text-to-image. See "Getting a reference image". |

**Optional fields:**

| Field | Type | Description |
|-------|------|-------------|
| `startScript` | string | Opening line the avatar says when the call starts (up to 2000 chars) |
| `documentIds` | string[] | Knowledge document UUIDs for extra context |

### Getting a reference image

The `referenceImage` field accepts three formats:
- **HTTPS URL** — e.g. `https://example.com/face.png` (preferred for large images)
- **Runway URI** — e.g. `runway://...` (from the Runway upload API)
- **Data URI** — e.g. `data:image/png;base64,...` (max ~5MB, works for small images)

If the user provides an image (e.g. via chat), pick the right approach:
- **User sent an HTTPS URL** → use it directly as `referenceImage`.
- **User sent a small base64 image** (under ~1MB) → pass it directly as a `data:image/...;base64,...` data URI.
- **User sent a large base64 image** (over ~1MB) → upload it to Runway first to get a `runway://` URI, then use that as `referenceImage`. See "Uploading large images" below.

Try these sources in order:

1. **User-provided image** — if the user sent an image they want as their avatar, use it (see upload instructions below if it's large base64).

2. **Your avatar image** — if you already have an avatar image URL, use it directly as `referenceImage`.

3. **Quick pick (recommended)** — pick the pre-made character image that best matches your personality, and use it as `referenceImage`:
   - Openclaw Lobster 1: `https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster1.jpg`
   - Openclaw Lobster 2: `https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster2.jpg`
   - Cat: `https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/cat.png`
   - Alien man, candy texture: `https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-man-candy-texture.jpg`
   - Alien woman, candy texture: `https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-woman-candy-texture.jpg`
   - Old man, long beard, game style: `https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/old-man-long-beard-game-style.png`
   - Blond guy, blue sweater: `https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/blond-guy-blue-sweater.png`
   - Man, 3D animation: `https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/man-3d-animation-style.png`
   - Girl in airport, 3D: `https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/3d-animated-girl-in-airport.png`
   - White furry monster: `https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/white-furry-monster.png`
   - Superstar young woman: `https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/woman-music-superstar.png`

4. **Generate one with Runway text-to-image** — if none of the quick picks fit your character, or if the user specifically asks for a custom avatar look. Use the Runway API with model `gemini_2.5_flash`:

```bash
curl -X POST https://api.dev.runwayml.com/v1/text_to_image \
  -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
  -H "X-Runway-Version: 2024-11-06" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini_2.5_flash