# Rw Integrate Character Embed

> Help users embed Runway Character avatar calls in React apps using the @runwayml/avatars-react SDK

- **Type:** Skill
- **Install:** `agentstack add skill-runwayml-skills-rw-integrate-character-embed`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [runwayml](https://agentstack.voostack.com/s/runwayml)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [runwayml](https://github.com/runwayml)
- **Source:** https://github.com/runwayml/skills/tree/main/skills/rw-integrate-character-embed

## Install

```sh
agentstack add skill-runwayml-skills-rw-integrate-character-embed
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Embed Characters in React (Avatars React SDK)

> **PREREQUISITES:**
> - `+rw-check-compatibility` — Project must have server-side capability (API key must never be exposed to the client)
> - `+rw-fetch-api-reference` — Load the latest API reference from https://docs.dev.runwayml.com/api/ before integrating
> - `+rw-integrate-characters` — Character (Avatar) must be created and session endpoint must exist
> - Project must use **React** (Next.js, Vite+React, Remix, etc.)
>
> **OPTIONAL:**
> - `+rw-integrate-documents` — Add knowledge base before embedding

Embed real-time avatar video calls in React applications using the `@runwayml/avatars-react` SDK.

## Installation

```bash
npm install @runwayml/avatars-react
```

This is a **client-side** package. The server-side `@runwayml/sdk` should already be installed from `+rw-integrate-characters`.

## Option A: Simple — `AvatarCall` Component

The fastest way to embed a character. Handles WebRTC connection and renders a default UI automatically.

```tsx
'use client';

import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

export default function CharacterPage() {
  return (
     console.log('Call ended')}
      onError={(error) => console.error('Error:', error)}
    />
  );
}
```

### `AvatarCall` Props

| Prop | Type | Description |
|------|------|-------------|
| `avatarId` | `string` | The Avatar UUID from the Developer Portal or API |
| `connectUrl` | `string` | Your server-side session endpoint (e.g., `/api/avatar/session`) |
| `onEnd` | `() => void` | Called when the call ends normally |
| `onError` | `(error: Error) => void` | Called on connection or runtime errors |

**For custom avatars** created in the Developer Portal, use the Avatar UUID as `avatarId`.

## Option B: Fully Custom — Hooks

For full control over the UI, use `AvatarSession` with hooks.

### Components & Hooks

| Export | Type | Description |
|--------|------|-------------|
| `AvatarSession` | Component | Provider that manages the WebRTC session |
| `AvatarVideo` | Component | Renders the avatar's video stream |
| `UserVideo` | Component | Renders the user's camera feed |
| `useAvatarSession` | Hook | Access session state: `state`, `sessionId`, `error`, `end()` |
| `useLocalMedia` | Hook | Control user's media: `isMicEnabled`, `toggleMic()` |

### Custom UI Example

```tsx
'use client';

import {
  AvatarSession,
  AvatarVideo,
  UserVideo,
  useAvatarSession,
  useLocalMedia,
} from '@runwayml/avatars-react';
import type { SessionCredentials } from '@runwayml/avatars-react';

function CallUI() {
  const { state, end } = useAvatarSession();
  const { isMicEnabled, toggleMic } = useLocalMedia();

  return (
    
      {/* Avatar video takes full screen */}
      

      {/* User's camera in a small overlay */}
      

      {/* Controls */}
      
        
          {isMicEnabled ? 'Mute' : 'Unmute'}
        
        End Call
      

      {/* Connection state */}
      {state === 'connecting' && (
        
          Connecting...
        
      )}
    
  );
}

export function CustomAvatar({ credentials }: { credentials: SessionCredentials }) {
  return (
    
      
    
  );
}
```

### Fetching Credentials for Custom UI

When using the hooks approach, you need to fetch credentials from your server endpoint and pass them to `AvatarSession`:

```tsx
'use client';

import { useState, useCallback } from 'react';
import type { SessionCredentials } from '@runwayml/avatars-react';
import { CustomAvatar } from './CustomAvatar';

export default function CharacterPage() {
  const [credentials, setCredentials] = useState(null);
  const [loading, setLoading] = useState(false);

  const startCall = useCallback(async () => {
    setLoading(true);
    try {
      const res = await fetch('/api/avatar/session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ avatarId: 'your-avatar-id-here' }),
      });
      const data = await res.json();
      setCredentials(data);
    } catch (error) {
      console.error('Failed to connect:', error);
    } finally {
      setLoading(false);
    }
  }, []);

  if (credentials) {
    return ;
  }

  return (
    
      {loading ? 'Connecting...' : 'Start Conversation'}
    
  );
}
```

## Integration Patterns

### Next.js App Router (Full Example)

**Server route** (`app/api/avatar/session/route.ts`):
See `+rw-integrate-characters` for the complete server-side session creation code.

**Client page** (`app/character/page.tsx`):

```tsx
'use client';

import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

const AVATAR_ID = process.env.NEXT_PUBLIC_AVATAR_ID || 'your-avatar-id';

export default function CharacterPage() {
  return (
    
       window.location.reload()}
        onError={(error) => {
          console.error('Avatar error:', error);
          alert('Connection failed. Please try again.');
        }}
      />
    
  );
}
```

### Conditional Rendering (Show/Hide)

```tsx
'use client';

import { useState } from 'react';
import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

export default function SupportPage() {
  const [showAvatar, setShowAvatar] = useState(false);

  return (
    
      Customer Support

      {!showAvatar ? (
         setShowAvatar(true)}>
          Talk to an Agent
        
      ) : (
         setShowAvatar(false)}
          onError={(error) => {
            console.error(error);
            setShowAvatar(false);
          }}
        />
      )}
    
  );
}
```

## Error Handling

### Verbose Error Logging

```tsx
 {
    console.error('Avatar error:', error);
    console.error('Error name:', error.name);
    console.error('Error message:', error.message);
    if (error.cause) {
      console.error('Cause:', error.cause);
    }
  }}
/>
```

### Debug Session State

```tsx
import { useAvatarSession } from '@runwayml/avatars-react';

function DebugPanel() {
  const { state, sessionId, error } = useAvatarSession();

  return (
    
      {JSON.stringify({ state, sessionId, error: error?.message }, null, 2)}
    
  );
}
```

## Browser Support

| Browser | Minimum Version |
|---------|-----------------|
| Chrome | 74+ |
| Firefox | 78+ |
| Safari | 14.1+ |
| Edge | 79+ |

Users must grant **microphone permissions** when prompted. **Camera permissions** are needed if user video is enabled.

## Tips

- **Always import the styles**: `import '@runwayml/avatars-react/styles.css'` when using `AvatarCall`
- **`'use client'` directive** is required in Next.js App Router for all components using the React SDK
- **Session max duration is 5 minutes** — handle the `onEnd` callback to show a reconnect option
- **Credentials are one-time use** — if connection fails, fetch new credentials (create a new session)
- For the full SDK source, examples, and issue tracking: [github.com/runwayml/avatars-sdk-react](https://github.com/runwayml/avatars-sdk-react)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [runwayml](https://github.com/runwayml)
- **Source:** [runwayml/skills](https://github.com/runwayml/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-runwayml-skills-rw-integrate-character-embed
- Seller: https://agentstack.voostack.com/s/runwayml
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.