Labsco
runwayml logo

rw-integrate-character-embed

★ 55

by runwayml · part of runwayml/skills

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

🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#ai-video#git#maps#customer-support#memory
🧩 One of 7 skills in the runwayml/skills package — works on its own, and pairs well with its siblings.

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

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

by runwayml

Help users embed Runway Character avatar calls in React apps using the @runwayml/avatars-react SDK npx skills add https://github.com/runwayml/skills --skill rw-integrate-character-embed Download ZIPGitHub55

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.

Option A: Simple — AvatarCall Component

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

Copy & paste — that's it
'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

Copy & paste — that's it
'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:

Copy & paste — that's it
'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):

Copy & paste — that's it
'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)

Copy & paste — that's it
'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

Copy & paste — that's it
 {
 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

Copy & paste — that's it
import { useAvatarSession } from '@runwayml/avatars-react';

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

 return (

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

Copy & paste — that's it

 );
}

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