Start a Voice Call

The Agora Voice SDK makes it easy to embed real-time voice interaction into iOS apps. It enables you to develop rapidly and easily to enhance your social, work, education and IoT apps.

This page shows the minimum code you need to add Voice Call into your app by using the Agora Voice SDK for iOS.

Understand the tech

The following figure shows the workflow of a voice call implemented by the Agora SDK.

As shown in the figure, the workflow for adding Voice Call in your project is as follows:

1. Retrieve a token
   A token is the credential that authenticates a user when your app client joins a channel. In a test or production environment, your app client retrieves tokens from a server in your security infrastructure.

2. Join a channel
   Call joinChannel to create and join a channel. App clients that pass the same channel name join the same channel.

3. Publish and subscribe to audio in the channel
   After joining a channel, the app client automatically publishes and subscribes to audio in the channel.

For an app client to join an RTC channel, you need the following information:

• The App ID: A randomly generated string provided by Agora for identifying your app. You can get the App ID from Agora Console.
• The user ID: The unique identifier of a user. You need to specify the user ID yourself, and ensure that it is unique in the channel.
• A token: In a test or production environment, your app client retrieves tokens from a server in your security infrastructure. For this page, you use a temporary token with a validity period of 24 hours that you retrieve from Agora Console.
• The channel name: A string that identifies the channel for the voice call.

Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

• Xcode 9.0 or later.
• An iOS device running iOS 9.0 or later.
• A valid Agora account.
• A valid Agora project with an App ID and a temporary token. For details, see Get Started with Agora.
• A computer with access to the internet. If your network has a firewall, follow the instructions in Firewall Requirements.

Project setup

In Xcode, follow the steps to create the environment necessary to add Voice Call into your app.

1. Create a new iOS app and configure the following settings:
   • Product Name: Any name you like.
   • Team: If you have added a team, choose it from the pop-up menu. If not, you can see the Add account button. Click it, input your Apple ID, and click Next to add your team.
   • Organization Identifier: The identifier of your organization. If you do not belong to an organization, use any identifier you like.
   • Interface: Choose Storyboard.
   • Language: Choose Swift.

2. Integrate the Voice SDK into your project:

   Go to File > Swift Packages > Add Package Dependencies..., and paste the following URL:

     https://github.com/AgoraIO/AgoraAudio_iOS

   In Choose Package Options, specify the Voice SDK version you want to use. You need to fill in x.y.z for version x.y.z and x.y.z-r.a for version x.y.z.a. For example, fill in 3.5.0 for version 3.5.0 and 3.5.0-r.2 for version 3.5.0.2.

3. Enable automatic signing for your project.
4. Set the deployment target for your app:
   1. In the project editor, choose your target and click General.
   2. In the Deployment Info settings, choose the operating system version for your iOS app from the dropdown menu.

5. Add permissions for microphone usage.
   In the Project navigator, open the info.plist file of your project and add the property "Privacy - Microphone Usage Description".

Implement a client for Voice Call

This section shows how to use the Agora Voice SDK to implement Voice Call in your app step by step.

Implement the Voice Call logic

When your app opens, you create an RtcEngine instance, join a channel, and publish the local audio. When another user joins the channel, your app catches the join event and subscribes to the remote audio.

The following figure shows the API call sequence of implementing Voice Call.

To implement this logic, take the following steps:

1. Import the Agora kit and add the agoraKit variable.

   Modify your ViewController.swift as follows:

    import UIKit
    // Add this line to import the Agora kit
    import AgoraRtcKit
   
    class ViewController: UIViewController {
   
        // Add this line to add the agoraKit variable
        var agoraKit: AgoraRtcEngineKit?
   
        override func viewDidLoad() {
            super.viewDidLoad()
        }
   
    }

2. Initialize the app and join the channel.

   Call the core methods to initialize the app and join a channel. In this example app, this functionality is encapsulated in the initializeAndJoinChannel function.

   In ViewController.swift, add the following lines after the viewDidLoad function, and fill in your App ID, temporary token, and channel name:

    func initializeAndJoinChannel() {
        // Pass in your App ID here
        agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId: "Your App ID", delegate: self)
   
        // Join the channel with a token. Pass in your token and channel name here
        agoraKit?.joinChannel(byToken: "Your token", channelId: "Channel name", info: nil, uid: 0, joinSuccess: { (channel, uid, elapsed) in
        })
    }

3. Add the callback that is triggered when a remote user joins the channel.
   In ViewController.swift, add the following lines after the ViewController class:

    extension ViewController: AgoraRtcEngineDelegate {
        func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int) {
        }       
    }

Start and stop your app

Now you have created the Voice Call functionality, add the functionality of starting and stopping the app. In this implementation, a voice call starts when the user opens your app. The call ends when the user closes your app.

To implement the functionality of starting and stopping the app:

1. When the view is loaded, call initializeAndJoinChannel to join a voice call channel.

   In ViewController.swift, add the initializeAndJoinChannel function inside the viewDidLoad function:

    override func viewDidLoad() {
        super.viewDidLoad()
        // Add this line
        initializeAndJoinChannel()
    }

2. When the user closes this app, clean up all the resources used by your app.

   In ViewController.swift, add viewDidDisappear after the initializeAndJoinChannel function.

    override func viewDidDisappear(_ animated: Bool) {
        super.viewDidDisappear(animated)
        agoraKit?.leaveChannel(nil)
        AgoraRtcEngineKit.destroy()
    }

Test your app

To test your app on a physical device, do the following:

1. Check whether you fill in your App ID, temporary token, and channel name in ViewController.swift.
2. Connect an iOS device to your computer.
3. In Xcode, choose the device from the scheme menu in the toolbar, and click the Run button.
4. On your device, launch the app and grant microphone access.
5. Ask a friend to join the voice call with you on the demo app. Your friend needs to enter the same App ID and channel name.
   When your friend joins the channel, you can hear each other.

Next steps

Generating a token by hand is not helpful in a production context. Authenticate Your Users with Tokens shows you how to start Voice Call with a token that you retrieve from your server.

See also

This section provides additional information for your reference:

Sample project

Agora provides an open source sample project Basic Audio Call on GitHub that implements one-to-one voice call and group voice call for your reference.

Other approaches to integrate the latest SDK

In addition to integrating the Agora Voice SDK for iOS through Swift Package, you can also import the SDK into your project through CocoaPods or by manually copying the SDK files.

Automatically integrate the SDK with CocoaPods

1. Install CocoaPods if you have not. See Getting Started with CocoaPods.
2. In Terminal, navigate to the root of your project folder, and run the pod init command to create a Podfile in the project folder.
3. Open the Podfile, and replace all contents with the following code. Remember to replace Your App with the target name of your project.

  # platform :ios, '9.0'
  target 'Your App' do
      pod 'AgoraAudio_iOS'
  end

4. In Terminal, run the pod install command to install the SDK. When the SDK is installed successfully, you can see Pod installation complete! in Terminal and an xcworkspace file in the project folder.
5. Open the xcworkspace file for any further steps.

Manually copy the SDK files

1. Go to SDK Downloads, download the latest version of the Agora Voice SDK, and extract the files from the downloaded SDK package.

2. From the libs folder of the downloaded SDK package, copy the files or subfolders you need to the root of your project folder.

3. In Xcode, link your target to the frameworks or libraries you have copied. Be sure to choose Embed & Sign from the pop-up menu in the Embed column.

   • Apple does not allow an app extension to contain any dynamic library. If you are integrating the Agora SDK to an app extension, choose Do Not Embed in the Embed column.
   • The Agora SDK uses libc++ (LLVM) by default. Contact support@agora.io if you want to use libstdc++ (GNU). The SDK provides FAT image libraries with multi-architecture support for both 32/64-bit audio emulators and 32/64-bit audio/video real devices.

Integrate earlier versions of the SDK

Choose one of the following methods to integrate a version of the Agora iOS SDK earlier than v3.2.0.

Method 1: Through CocoaPods

1. Ensure that you have installed CocoaPods before performing the following steps. See the installation guide in Getting Started with CocoaPods.

2. In Terminal, navigate to the project path, and run the pod init command to create a Podfile in the project folder.

4. Return to Terminal, and run the pod install command to install the Agora SDK. Once you successfully install the SDK, it shows Pod installation complete! in Terminal, and you can see an xcworkspace file in the project folder.

5. Open the generated xcworkspace file.

Method 2: Through your local storage

You need to use different integration methods to integrate different versions of the SDK. Click the following version categories to expand the corresponding integration steps.

Distribution consideration

If you integrate dynamic libraries under the path of ./libs/ALL_ARCHITECTURE in the SDK package, you need to remove the x86-64 architecture in the libraries before uploading the app to the App Store.

In Terminal, run the following command to remove the x86-64 architecture. Remember to replace ALL_ARCHITECTURE/AgoraRtcKit.framework/AgoraRtcKit with the path of the dynamic library in your project.

lipo -remove x86-64 ALL_ARCHITECTURE/AgoraRtcKit.framework/AgoraRtcKit -output ALL_ARCHITECTURE/AgoraRtcKit.framework/AgoraRtcKit

See more considerations in Preparing Your App for Distribution.

Objective-C code sample

To implement Voice Call in your app using Objective-C:

1.Replace the contents in the ViewController.h file with the following:

#import <UIKit/UIKit.h>
#import <AgoraRtcKit/AgoraRtcEngineKit.h>

    @interface ViewController : UIViewController <AgoraRtcEngineDelegate>
@property (strong, nonatomic) AgoraRtcEngineKit *agoraKit;

@end

2.Replace the contents in the ViewController.m file with the following:

#import "ViewController.h"
#import <UIKit/UIKit.h>

@interface ViewController ()

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    [self initializeAndJoinChannel];
}

- (void)initializeAndJoinChannel {
    // Pass in your App ID here
    self.agoraKit = [AgoraRtcEngineKit sharedEngineWithAppId:@"Your App ID" delegate:self];
    [self.agoraKit joinChannelByToken:@"Your token" channelId:@"Channel name" info:nil uid:0 joinSuccess:^(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed) {
    }];
}

- (void)rtcEngine:(AgoraRtcEngineKit *)engine didJoinedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed {

}

- (void)viewDidDisappear:(BOOL)animated {
    [super viewDidDisappear:animated];
    [self.agoraKit leaveChannel:nil];
    [AgoraRtcEngineKit destroy];
}

@end