Requirements

Step 1: Prepare the Workspace

The easiest way to integrate the Webex Teams iOS SDK into your app is to add it to your project with CocoaPods. Follow these steps to create a new Xcode workspace that will use CocoaPods to install the SDK.

Using Terminal, navigate to the SparkDemoApp directory and install the Webex Teams iOS SDK (specified in the Podfile):

pod install

After installation is complete, CocoaPods will create a new SparkDemoApp.xcworkspace file for the project. From now on, open and use this file instead of the original Xcode project file, otherwise you will face issues with Framework dependencies.

Importing the Webex Teams SDK

If you are creating a new app, import the Webex Teams SDK library by adding the following line to your ViewController.swift file:

If you are adding the Webex Teams SDK to an already functional app, you can simply import the library in your Swift files to start using the SDK.

Keep reading for details about how to use the Webex Teams SDK with your application, starting with authenticating the user, then moving on to creating rooms and sending messages.

Step 2: App Integration and OAuth 2

You must first register a Webex Teams Integration before your application can use Webex Teams on behalf of a user. Once registration is complete, you will get a Client ID and Client Secret for use with the app. These can be used to generate a token with the proper scopes, but luckily the iOS SDK has a method which will perform this step for you:

Teams are quite useful if you want to create a set of rooms for only certain members of the team. Teams also have an independent membership management interface for inviting/deleting/listing users and adding a moderator to the team room.

The calls can be made to Webex Teams users/devices, Telepresence systems, SIP devices, and regular telephones. If the user calls a telephone system such as an IVR, the SDK also supports DTMF transport so users can navigate IVR menus. iOS users can also view the content shared from any Telepresence system. It is a fully-integrated collaboration SDK.

Complete Demo App

A complete demo application is available to see the complete functionality of the SDK.

Incoming Call Notification Guide

The iOS SDK provides the ability to make and receive calls via Webex Teams. If your iOS app is running in the foreground on the user's device, the iOS SDK provides the phone.onIncoming callback to allow your app to handle new incoming calls. However, to alert users of incoming calls while your app is in the background or not running, you will need to use Webex Teams Webhooks and the Apple Push Notification service (APNs). Webhook events generated for new calls will be sent to your service for processing before using APNs to notify the user of the new call.

This guide will provide more detail about handling incoming calls while your app is in the background or not running. See the Phone SDK API reference for more details about handling incoming calls while your app is in the foreground.

Note

The webhook resource described in this guide is currently in beta. It is limited to 1:1 calls and may change in the future. If you're interested in using this webhook for your iOS app, please contact the Webex Developer Support team to add your account to the beta program.

Getting Started

Before we get started, please review the following:

You should be familiar with Webex Teams Webhooks, including how to create them and how to handle their payloads. For more detailed information about Webhooks, please see the Webhooks Explained guide.

An external server or service is required to receive the events from Webex Teams and to send remote notifications to APNs.

Your service will need to process and store iOS device tokens for use with APNs.

To generate iOS notifications for incoming calls, a webhook will be used to generate an event when an incoming call is received for a particular user. This event will be sent to your service as an HTTP POST of JSON data. This JSON data will include information about the new call.

When a user enables notifications in your app, your service should keep track of the user's Webex Teams personId and their unique device token from APNs. Both of these pieces of information will be needed to process the webhook and generate the notification. When a webhook event is received by your service, it will use this information to determine which device to notify via APNs.

When permission has been granted, a unique identifier will be generated for this particular installation of your app. This token will be needed for remote notifications via APNs. If registration is successful, the app calls your app delegate object's application(_:didRegisterForRemoteNotificationsWithDeviceToken:) method. Use this method to send the personId of the Webex Teams user and the unique token to your service. Both of these values will be needed to process webhook events and generate notifications.

Creating Webhooks

You can create a new webhook for the user to notify your service of new calls with the iOS SDK. Configure the webhook to use your server as the targetUrl. To limit this webhook to only incoming calls, use the new callMembership webhook resource and look for created events. The callMembership webhook resource currently only supports call notifications for 1:1 spaces. A specific filter will limit results to notification events (status=notified) for the authenticated user (personId=me).

Once the notification is received and processed by the device, your app can then respond to the incoming call and prompt the user to accept or deny the call.

Example Push Notification Server

We've put together a simple Java application which can be deployed to Heroku to listen for Webex Teams webhook events, process registrations for user devices, and generate push notifications to those devices. Check out the project on GitHub for more details.

Troubleshooting the iOS SDK

If you're having trouble with the iOS SDK, here's some more information to help troubleshoot the issue.

SDK Requirements

Review the following SDK requirements to make sure you're using the correct minimum versions of macOS, Xcode, etc.: