# Cordova VoIP Calls

Pushwoosh supports VoIP-style call notifications for iOS and Android using the `pushwoosh-cordova-plugin`. This enables native VoIP call functionality, including incoming call UI and call control events.

## 1. Add the Pushwoosh Cordova plugin with VoIP enabled

Install the plugin with the VoIP flag enabled:

```sh
cordova plugin add pushwoosh-cordova-plugin --variable PW_VOIP_IOS_ENABLED=true --variable PW_VOIP_ANDROID_ENABLED=true
```

This will configure the plugin to support VoIP functionality on iOS.

## 2. Add the PushwooshVoIP CocoaPod dependency

Make sure the `PushwooshVoIP` pod is included automatically via the plugin. If needed, manually verify in your `Podfile`:

```ruby
pod 'PushwooshVoIP'
```

> This pod is required to support PushKit-based VoIP notifications and system-level call handling.

## 3. Enable VoIP background mode in Xcode

Open your project in Xcode and follow these steps:

1. Go to **Signing & Capabilities**.
2. Add **Background Modes** capability.
3. Check the **Voice over IP** option.

This allows your app to receive incoming VoIP pushes while in the background.

## 4. Configure VoIP app code (if using both VoIP and regular pushes)

If your app uses both standard and VoIP pushes, you must explicitly set the VoIP application code before VoIP initialization:

```javascript
pushwoosh.setVoipAppCode("XXXXX-XXXXX");
```

Replace `"XXXXX-XXXXX"` with the Pushwoosh App Code assigned to your VoIP-enabled application in the Pushwoosh Control Panel.
<Aside type="caution" title="Important">
- Tokens for VoIP pushes will be registered under the VoIP App Code, while regular push tokens will be registered under the primary App Code.

- This method should be called **before** calling the `registerDevice()` method.
</Aside> 


## 5. Request call permission on Android

On Android, you require to request to grant a permission to receive calls from a user. To do that, call the `requestCallPermission()` method. This should be done before registering a device.

```javascript
pushwoosh.requestCallPermission();
```


## 6. Initialize VoIP parameters

Call the following method to initialize VoIP functionality:

```javascript
PushNotification.prototype.initializeVoIPParameters = function(supportsVideo, ringtoneSound, handleTypes, success, error) {
    if (typeof handleTypes === "function") {
        error = ringtoneSound;
        success = supportsVideo;
        handleTypes = undefined;
        ringtoneSound = undefined;
        supportsVideo = undefined;
    }

    exec(success, error, "PushNotification", "initializeVoIPParameters", [
        !!supportsVideo,
        ringtoneSound || "",
        handleTypes != null ? Number(handleTypes) : 1
    ]);
};
```

### Parameters

- `supportsVideo` – `true` or `false` depending on whether your app supports video calls
- `ringtoneSound` – custom ringtone file name (e.g. `"incoming.caf"`), or empty string for default
- `handleTypes` – numeric bitmask for call handle types (`1` for phone number, `2` for email, etc.)

## 7. Available VoIP callbacks and methods

The Cordova plugin supports the following VoIP-related methods and events:

- `answer` – called when a user answers an incoming call
- `endCall` – called when a user ends the current call
- `hangup` – called when a call is hung up
- `reject` – called when an incoming call is rejected
- `muted` – toggle mute status, iOS-only
- `held` – toggle hold status, iOS-only
- `voipPushPayload` – returns push payload for the incoming VoIP call
- `incomingCallSuccess` – called when system call UI is successfully shown, iOS-only
- `incomingCallFailure` – called when system call UI fails to show, iOS-only
- `speakerOn` – turn speaker on
- `speakerOff` – turn speaker off
- `playDTMF` – play DTMF tone during a call, iOS-only

These can be hooked using Cordova’s `PushNotification` object, allowing you to control and respond to VoIP call state changes.


## Related links

- [Pushwoosh Cordova SDK Overview](/developer/pushwoosh-sdk/cross-platform-frameworks/cordova/)
- [VoIP Push Notifications on iOS (Apple Docs)](https://developer.apple.com/documentation/pushkit)