Rate this page:


Voximplant push notifications for iOS are based on the Apple VoIP Push Notifications for calls and Apple Push Notifications for messaging. Using notifications, a device can be awakened up and an application can be started before a call or a message arrives. You can check our sample application with all the code needed to handle push notifications. Following tutorial explains that code and describes additional steps that should be performed to have a working push notifications solution for your mobile applications. Push notifications are available since iOS SDK version 1.1.0

Configure the iOS project

  • Open project in the XCode
  • Switch to the Project Navigator and click on the project
  • Go to the Capabilities tab at the top panel
  • Enable Push Notifications and following Background Modes: "Audio, AirPlay, and Picture in Picture", "Voice over IP" (if you need to handle calls), "Background fetch" and "Remote notifications"

Handle push notifications (VoIP)

Adding PushKit

Adding PushKit

  • Subscribe to push notifications at the application start:
Subscribing to push notifications

Subscribing to push notifications

  • Handle push credentials update and pass a new token to the SDK:
Handling push credentials update

Handling push credentials update

  • After a push notification is received, you have to pass dictionaryPayload to the SDK via the [VIClient handlePushNotification:] API. If the application is not connected to the Voximplant cloud, it should reconnect in order to handle an incoming call. It is strongly recommended to disable connectivity check when connecting after the push notification.
Passing dictionaryPayload to the SDK

Passing dictionaryPayload to the SDK

Handle push notifications (IM)

  • Handle push credentials update and pass a new token to the SDK:
Handling push credentials update

Handling push credentials update

  • After a push notification from the Voximplant cloud is received by an application, our SDK can return either with VIMessageEvent or nil. A dictionary retrieved from the push notification should be passed to the processPushNotification function.
Passing a dictionary to the SDK

Passing a dictionary to the SDK

Generate an Apple certificate

  1. Log in into the Apple developer website
  2. Click on the Certificates, ID's & Profiles
  3. Click on the "+" sign at the top-right corner
  4. Select the VoIP Services Certificate if you're going to handle calls notifications; despite this type of certificate is located in the Production section, it suits for both production and debug/sandbox builds. In case of messaging notifications, select Apple Push Notification service SSL either in Development or Production section. Click Continue
  5. Select the target application in the App ID and click Continue
  6. Follow on-screen instructions and download the voip_services.cer file
  7. Double-click the downloaded file and import it into the OSX Keychain of your Mac
  8. In the Keychain interface right-click imported certificate and export it as .p12 file with a password

Add certificates to the Voximplant cloud

  1. Log in into the Voximplant control panel
  2. Go to your application, then switch to the Push Certificates tab
  3. Click on the Add Certificate in the upper right corner
  4. In the Certificate for list select APPLE VOIP for calls or APPLE for messaging
  5. Click on the Choose File and upload the .p12 file
  6. Enter password you have used while generating a file from your Keychain interface
  7. Choose Production or Development version depending on your target. The Production version works only with release builds for TestFlight and AppStore. The Development version works with debug/sandbox builds (which are built from Xcode locally).
  8. Click on the Add button

Modify VoxEngine scenario

In order to allow the Voximplant cloud to send push notifications to applications, the JavaScript scenario that initiates a call should include a push notification helper:

Adding a push notification helper

Adding a push notification helper

This code will make VoxEngine manage timeouts automatically so they won't be configurable. VoxEngine will wait for the user login event for 20 seconds after a push notification was sent. If the user didn't logged in during this time, the call will be failed. If the user logged in, he will receive the incoming call event and have the same time to answer a call as for general call.

Push notifications are sent automatically

Just use the callUser method from the VoxEngine scenario and push notifications will be automatically sent to the app, so the application can wake up, connect to the Voximplant cloud, log in and accept the call.

Use tokens or keys for better security

Voximplant support 3 ways to log in from the SDK: with a password, a token or a one-time login key. Saving the password is not secure, so we would recommend to use the "token" or "key" approach.

The token is received from an event after the successful login, can be saved and used later instead of password. The "login key" approach allows to completely exclude password usage on the client side by offloading it to your backend. Please refer to this article for details.