TelnyxCall Capacitor Plugin

A Capacitor plugin for integrating Telnyx voice calling functionality into your mobile application. This plugin enables your app to receive incoming calls using Telnyx's communication services.

Installation

npm install telnyx-call
npx cap sync

iOS Setup

1. Install CocoaPods Dependencies

After adding the plugin to your project, you need to install the CocoaPods dependencies:

cd ios
pod install

2. Configure iOS Capabilities

Open your Xcode project and enable the following capabilities:

a. Background Modes

• Voice over IP
• Audio, AirPlay, and Picture in Picture
• Remote notifications

b. Push Notifications

• Enable Push Notifications capability

c. Update Info.plist

Add the following entries to your Info.plist:

<!-- Microphone permission -->
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is required for voice calls</string>

<!-- Background modes -->
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
    <string>voip</string>
    <string>remote-notification</string>
</array>

3. Configure VoIP Push Notifications

To receive calls when your app is in the background or closed, you need to:

1. Generate a VoIP Services Certificate in the Apple Developer Portal
2. Upload the certificate to the Telnyx Portal
3. Configure your SIP Connection to use push notifications

For detailed instructions, see the Telnyx Push Notifications Documentation.

Usage

Initialize the Plugin

Initialize the plugin with your Telnyx credentials when your app starts:

import { Plugins } from '@capacitor/core';
const { TelnyxCall } = Plugins;

// Initialize on app startup with credentials
async function initializeTelnyx(credentials: { username: string; password: string }) {
  try {
    await TelnyxCall.initialize({ 
      username: credentials.username,
      password: credentials.password,
      // Optional push token if available
      pushDeviceToken: localStorage.getItem('pushToken') || undefined
    });
    console.log('Telnyx SDK initialized successfully');
  } catch (error) {
    console.error('Failed to initialize Telnyx SDK', error);
  }
}

Listen for Events

Login State Changes

TelnyxCall.addListener('loginStateChanged', (state: any) => {
  console.log('Login state changed:', state.state);
  
  if (state.state === 'loggedIn') {
    console.log('Successfully logged in to Telnyx');
  } else if (state.state === 'loginFailed') {
    console.error('Login failed:', state.error);
  }
});

Incoming Calls

TelnyxCall.addListener('incomingCall', (call: any) => {
  console.log('Incoming call from', call.callerNumber);
  // Store callId for answering/rejecting
  this.currentCallId = call.callId;
  
  // The CallKit UI will be shown automatically on iOS
  // You can also show a custom UI in your app if desired
});

Call State Changes

TelnyxCall.addListener('callStateChanged', (state: any) => {
  console.log('Call state changed to', state.state);
  
  switch(state.state) {
    case 'connected':
      // Call is connected - update UI
      break;
    case 'disconnected':
      // Call ended - clean up UI
      this.currentCallId = null;
      break;
  }
});

Push Token Updates

TelnyxCall.addListener('pushTokenUpdated', (data: any) => {
  console.log('Push token updated:', data.token);
  localStorage.setItem('pushToken', data.token);
});

Handle Calls

Answer a Call

async function answerCall() {
  if (this.currentCallId) {
    await TelnyxCall.answerCall({ callId: this.currentCallId });
  }
}

Reject a Call

async function rejectCall() {
  if (this.currentCallId) {
    await TelnyxCall.rejectCall({ callId: this.currentCallId });
    this.currentCallId = null;
  }
}

Control Mute State

// Mute the call
async function muteCall() {
  await TelnyxCall.muteCall({ mute: true });
}

// Unmute the call
async function unmuteCall() {
  await TelnyxCall.muteCall({ mute: false });
}

Control Speaker State

// Enable speaker
async function enableSpeaker() {
  await TelnyxCall.setSpeaker({ speakerOn: true });
}

// Disable speaker
async function disableSpeaker() {
  await TelnyxCall.setSpeaker({ speakerOn: false });
}

For detailed information on integrating mute and speaker functionality, see the Mute and Speaker Integration Guide.

API Reference

Methods

initialize(options)

Initialize the Telnyx SDK with credentials.

interface InitializeOptions {
  username: string;
  password: string;
  pushDeviceToken?: string;
  logLevel?: string; // 'verbose', 'debug', 'info', 'warning', 'error', 'none'
}

answerCall(options)

Answer an incoming call.

interface AnswerCallOptions {
  callId: string;
}

rejectCall(options)

Reject an incoming call.

interface RejectCallOptions {
  callId: string;
}

muteCall(options)

Mute or unmute the current call.

interface MuteCallOptions {
  mute: boolean;
}

setSpeaker(options)

Enable or disable the speakerphone.

interface SetSpeakerOptions {
  speakerOn: boolean;
}

Events

loginStateChanged

Emitted when the login state changes.

interface LoginStateChangeEvent {
  state: 'loggedIn' | 'loginFailed' | 'loggedOut';
  error?: string;
}

incomingCall

Emitted when there's an incoming call.

interface IncomingCallEvent {
  callId: string;
  callerNumber: string;
  callerName?: string;
}

callStateChanged

Emitted when a call's state changes.

interface CallStateChangeEvent {
  callId: string;
  state: 'ringing' | 'connecting' | 'connected' | 'disconnected' | 'failed';
  errorMessage?: string;
}

muteStateChanged

Emitted when the mute state of a call changes.

interface MuteStateChangeEvent {
  isMuted: boolean;
}

speakerStateChanged

Emitted when the speaker state changes.

interface SpeakerStateChangeEvent {
  isSpeakerOn: boolean;
}

pushTokenUpdated

Emitted when the VoIP push token is updated.

interface PushTokenUpdatedEvent {
  token: string;
}

Troubleshooting

Push Notifications Not Working

• Ensure you've configured the VoIP push certificate correctly
• Verify the certificate is uploaded to the Telnyx Portal
• Check that your SIP Connection is configured to use push notifications
• Make sure your app has the necessary background modes enabled

Call Audio Issues

• Ensure microphone permissions are granted
• Check that the audio session is properly configured
• Verify that the app has the necessary background modes enabled

Debugging Push Notifications

For testing push notifications:

• Use a real device (not simulator)
• Have the app in background
• Make sure your Telnyx account is correctly configured for push

License

MIT