@capgo/capacitor-stream-call

Add video and audio calls to your Capacitor app with the Stream Video SDK, including incoming call handling and native call screens on iOS and Android.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-stream-call in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-stream-call to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Sessions: login() and logout() with a Stream user token.
• Calls: call(), acceptCall(), rejectCall() and endCall(), with callEvent and incomingCall listeners.
• Media controls: setMicrophoneEnabled(), setCameraEnabled(), switchCamera() and setSpeaker().
• Call info: getCallStatus(), getCallInfo() and getCurrentUser().
• Dynamic API key: setDynamicStreamVideoApikey() stores a Stream API key that native uses the next time it creates the client.
• Platforms: iOS, Android and Web. Web uses the Stream video client.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/streamcall/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-stream-call` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-stream-call
npx cap sync

Configuration

iOS Setup

1. API Key Configuration

Add your Stream Video API key to ios/App/App/Info.plist:

<dict>
  <key>CAPACITOR_STREAM_VIDEO_APIKEY</key>
  <string>your_api_key_here</string>
  <!-- other keys -->
</dict>

2. Localization (Optional)

To support multiple languages:

1. Add localization files to your Xcode project:

   • /App/App/en.lproj/Localizable.strings
   • /App/App/en.lproj/Localizable.stringsdict

2. Add translations in Localizable.strings:

"stream.video.call.incoming" = "Incoming call from %@";
"stream.video.call.accept" = "Accept";
"stream.video.call.reject" = "Reject";
"stream.video.call.hangup" = "Hang up";
"stream.video.call.joining" = "Joining...";
"stream.video.call.reconnecting" = "Reconnecting...";

3. Configure localization in your AppDelegate.swift:

import StreamVideo

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Appearance.localizationProvider = { key, table in
            Bundle.main.localizedString(forKey: key, value: nil, table: table)
        }
        return true
    }
}

Android Setup

1. API Key Configuration

Add your Stream Video API key to android/app/src/main/res/values/strings.xml:

<string name="CAPACITOR_STREAM_VIDEO_APIKEY">your_api_key_here</string>

2. MainActivity Configuration

Modify your MainActivity.java to handle incoming calls:

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  
  // Enable activity to show over lock screen
  if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O_MR1) {
    setShowWhenLocked(true);
    setTurnScreenOn(true);
  } else {
    getWindow().addFlags(android.view.WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED | android.view.WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON);
  }
}

3. Application Class Configuration

Create or modify your Application class to initialize the plugin:

import ee.forgr.capacitor.streamcall.StreamCallPlugin;

@Override
public void onCreate() {
  super.onCreate();
  
  // Initialize Firebase
  com.google.firebase.FirebaseApp.initializeApp(this);
  
  // Pre-initialize StreamCall plugin
  try {
    StreamCallPlugin.preLoadInit(this, this);
  } catch (Exception e) {
    Log.e("App", "Failed to pre-initialize StreamVideo Plugin", e);
  }
}

Note: If you don't have an Application class, you need to create one and reference it in your AndroidManifest.xml with android:name=".YourApplicationClass".

4. Localization (Optional)

Add string resources for different languages:

Default (values/strings.xml):

<resources>
    <string name="stream_video_call_incoming">Incoming call from %1$s</string>
    <string name="stream_video_call_accept">Accept</string>
    <string name="stream_video_call_reject">Reject</string>
    <string name="stream_video_call_hangup">Hang up</string>
    <string name="stream_video_call_joining">Joining...</string>
    <string name="stream_video_call_reconnecting">Reconnecting...</string>
</resources>

French (values-fr/strings.xml):

<resources>
    <string name="stream_video_call_incoming">Appel entrant de %1$s</string>
    <string name="stream_video_call_accept">Accepter</string>
    <string name="stream_video_call_reject">Refuser</string>
    <string name="stream_video_call_hangup">Raccrocher</string>
    <string name="stream_video_call_joining">Connexion...</string>
    <string name="stream_video_call_reconnecting">Reconnexion...</string>
</resources>

Displaying Caller Information

When receiving incoming calls, you can access caller information including name, user ID, and profile image. This information is automatically extracted from the call data and passed through the event system.

Getting Caller Information

The caller information is available in two ways:

1. Through Call Events

The callEvent listener provides caller information for incoming calls:

StreamCall.addListener('callEvent', (event) => {
  if (event.state === 'ringing' && event.caller) {
    console.log('Incoming call from:', event.caller.name || event.caller.userId);
    console.log('Caller image:', event.caller.imageURL);
    // Update your UI to show caller information
    showIncomingCallUI(event.caller);
  }
});

2. Through Incoming Call Events (Android lock-screen)

The incomingCall listener also includes caller information:

StreamCall.addListener('incomingCall', (payload) => {
  if (payload.caller) {
    console.log('Lock-screen call from:', payload.caller.name || payload.caller.userId);
    // Update your lock-screen UI
    updateLockScreenUI(payload.caller);
  }
});

Caller Information Structure

interface CallMember {
  userId: string;      // User ID (always present)
  name?: string;       // Display name (optional)
  imageURL?: string;   // Profile image URL (optional)
  role?: string;       // User role (optional)
}

Example Implementation

Here's how to implement a proper incoming call screen with caller information:

export class CallService {
  private callerInfo: CallMember | null = null;

  constructor() {
    this.setupCallListeners();
  }

  private setupCallListeners() {
    StreamCall.addListener('callEvent', (event) => {
      if (event.state === 'ringing') {
        this.callerInfo = event.caller || null;
        this.showIncomingCallScreen();
      } else if (event.state === 'joined' || event.state === 'left') {
        this.callerInfo = null;
        this.hideIncomingCallScreen();
      }
    });

    // Android lock-screen support
    if (Capacitor.getPlatform() === 'android') {
      StreamCall.addListener('incomingCall', (payload) => {
        this.callerInfo = payload.caller || null;
        this.showLockScreenIncomingCall();
      });
    }
  }

  private showIncomingCallScreen() {
    const callerName = this.callerInfo?.name || 'Unknown Caller';
    const callerImage = this.callerInfo?.imageURL || 'default-avatar.png';
    
    // Update your UI components
    document.getElementById('caller-name').textContent = callerName;
    document.getElementById('caller-image').src = callerImage;
    document.getElementById('incoming-call-screen').style.display = 'block';
  }
}

API

• login(...)
• logout()
• call(...)
• endCall()
• joinCall(...)
• setMicrophoneEnabled(...)
• setCameraEnabled(...)
• addListener('callEvent', ...)
• addListener('incomingCall', ...)
• removeAllListeners()
• enableBluetooth()
• acceptCall()
• rejectCall()
• isCameraEnabled()
• getCallStatus()
• getRingingCall()
• toggleViews()
• setSpeaker(...)
• switchCamera(...)
• getCallInfo(...)
• setDynamicStreamVideoApikey(...)
• getDynamicStreamVideoApikey()
• getCurrentUser()
• getPluginVersion()
• Interfaces
• Type Aliases
• Enums

login(...)

login(options: LoginOptions) => Promise<SuccessResponse>

Login to Stream Video service

Returns: Promise<SuccessResponse>

logout()

logout() => Promise<SuccessResponse>

Logout from Stream Video service

Returns: Promise<SuccessResponse>

call(...)

call(options: CallOptions) => Promise<SuccessResponse>

Initiate a call to another user

Returns: Promise<SuccessResponse>

endCall()

endCall() => Promise<SuccessResponse>

End the current call

Returns: Promise<SuccessResponse>

joinCall(...)

joinCall(options: { callId: string; callType: string; }) => Promise<SuccessResponse>

Join an existing call

Returns: Promise<SuccessResponse>

setMicrophoneEnabled(...)

setMicrophoneEnabled(options: { enabled: boolean; }) => Promise<SuccessResponse>

Enable or disable microphone

Returns: Promise<SuccessResponse>

setCameraEnabled(...)

setCameraEnabled(options: { enabled: boolean; }) => Promise<SuccessResponse>

Enable or disable camera

Returns: Promise<SuccessResponse>

addListener('callEvent', ...)

addListener(eventName: 'callEvent', listenerFunc: (event: CallEvent) => void) => Promise<{ remove: () => Promise<void>; }>

Add listener for call events

Returns: Promise<{ remove: () => Promise<void>; }>

addListener('incomingCall', ...)

addListener(eventName: 'incomingCall', listenerFunc: (event: IncomingCallPayload) => void) => Promise<{ remove: () => Promise<void>; }>

Listen for lock-screen incoming call (Android only). Fired when the app is shown by full-screen intent before user interaction.

Returns: Promise<{ remove: () => Promise<void>; }>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all event listeners

enableBluetooth()

enableBluetooth() => Promise<SuccessResponse>

Enable bluetooth audio

Returns: Promise<SuccessResponse>

acceptCall()

acceptCall() => Promise<SuccessResponse>

Accept an incoming call

Returns: Promise<SuccessResponse>

rejectCall()

rejectCall() => Promise<SuccessResponse>

Reject an incoming call

Returns: Promise<SuccessResponse>

isCameraEnabled()

isCameraEnabled() => Promise<CameraEnabledResponse>

Check if camera is enabled

Returns: Promise<CameraEnabledResponse>

getCallStatus()

getCallStatus() => Promise<CallEvent>

Get the current call status

Returns: Promise<CallEvent>

getRingingCall()

getRingingCall() => Promise<CallEvent>

Get the current ringing call

Returns: Promise<CallEvent>

toggleViews()

toggleViews() => Promise<{ newLayout: StreamCallLayout; }>

Cycle through the available video layouts

Returns: Promise<{ newLayout: StreamCallLayout; }>

setSpeaker(...)

setSpeaker(options: { name: string; }) => Promise<SuccessResponse>

Set speakerphone on

Returns: Promise<SuccessResponse>

switchCamera(...)

switchCamera(options: { camera: 'front' | 'back'; }) => Promise<SuccessResponse>

Switch camera

Returns: Promise<SuccessResponse>

getCallInfo(...)

getCallInfo(options: { callId: string; }) => Promise<CallEvent>

Get detailed information about an active call including caller details

Returns: Promise<CallEvent>

setDynamicStreamVideoApikey(...)

setDynamicStreamVideoApikey(options: { apiKey: string; }) => Promise<SuccessResponse>

Set a dynamic Stream Video API key that overrides the static one

Returns: Promise<SuccessResponse>

getDynamicStreamVideoApikey()

getDynamicStreamVideoApikey() => Promise<DynamicApiKeyResponse>

Get the currently set dynamic Stream Video API key

Returns: Promise<DynamicApiKeyResponse>

getCurrentUser()

getCurrentUser() => Promise<CurrentUserResponse>

Get the current user's information

Returns: Promise<CurrentUserResponse>

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version

Returns: Promise<{ version: string; }>

Interfaces

SuccessResponse

LoginOptions

PushNotificationsConfig

CallOptions

CallEvent

CallState

CallState is the current state of the call as seen by an SFU.

Participant

those who are online in the call

Timestamp

A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one.

All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a 24-hour linear smear.

The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from RFC 3339 date strings.

Examples

Example 1: Compute Timestamp from POSIX time().

<a href="#timestamp">Timestamp</a> timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);

Example 2: Compute Timestamp from POSIX gettimeofday().

struct timeval tv;
gettimeofday(&tv, NULL);

<a href="#timestamp">Timestamp</a> timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);

Example 3: Compute Timestamp from Win32 GetSystemTimeAsFileTime().

FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;

// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
<a href="#timestamp">Timestamp</a> timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));

Example 4: Compute Timestamp from Java System.currentTimeMillis().

long millis = System.currentTimeMillis();

<a href="#timestamp">Timestamp</a> timestamp = <a href="#timestamp">Timestamp</a>.newBuilder().setSeconds(millis / 1000)
    .setNanos((int) ((millis % 1000) * 1000000)).build();

Example 5: Compute Timestamp from Java Instant.now().

Instant now = Instant.now();

<a href="#timestamp">Timestamp</a> timestamp =
    <a href="#timestamp">Timestamp</a>.newBuilder().setSeconds(now.getEpochSecond())
        .setNanos(now.getNano()).build();

Example 6: Compute Timestamp from current time in Python.

timestamp = <a href="#timestamp">Timestamp</a>()
timestamp.GetCurrentTime()

JSON Mapping

In JSON format, the Timestamp type is encoded as a string in the RFC 3339 format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset).

For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017.

In JavaScript, one can convert a Date object to this format using the standard toISOString() method. In Python, a standard datetime.datetime object can be converted to this format using strftime with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's ISODateTimeFormat.dateTime() to obtain a formatter capable of generating timestamps in this format.

Struct

Struct represents a structured data value, consisting of fields which map to dynamically typed values. In some languages, Struct might be supported by a native representation. For example, in scripting languages like JS a struct is represented as an object. The details of that representation are described together with the proto support for the language.

The JSON representation for Struct is JSON object.

Value

Value represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values. A producer of value is expected to set one of these variants. Absence of any variant indicates an error.

The JSON representation for Value is JSON value.

ListValue

ListValue is a wrapper around a repeated field of values.

The JSON representation for ListValue is JSON array.

ParticipantCount

Pin

CallMember

IncomingCallPayload

CameraEnabledResponse

DynamicApiKeyResponse

CurrentUserResponse

Type Aliases

CallType

'default' | 'audio' | 'audio_room' | 'livestream' | 'development'

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

CallState

'idle' | 'ringing' | 'joining' | 'reconnecting' | 'joined' | 'leaving' | 'left' | 'created' | 'session_started' | 'rejected' | 'participant_counts' | 'missed' | 'accepted' | 'ended' | 'camera_enabled' | 'camera_disabled' | 'speaker_enabled' | 'speaker_disabled' | 'microphone_enabled' | 'microphone_disabled' | 'outgoing_call_ended' | 'unknown'

StreamCallLayout

'grid' | 'spotlight' | 'dynamic' | 'fullScreen' | 'fullscreen'

Enums

TrackType

ConnectionQuality

NullValue