Documentation

Get Started with Voqal

Complete integration guides for adding voice capabilities to your mobile apps

Integration

Open your Xcode project, navigate the File tab within the macOS bar, and click on "Add Packages".
In the URL field, enter: https://github.com/Voqal-AI/iOS-SDK and select VoqalSDK.
Set the dependency rule to "Exact Version" and specify the desired version (refer to the release notes on the github page for the latest stable version).
Click Next and wait for the package to finish fetching.

Setup

Step 1: Import VoqalSDK

Add the import statement in your AppDelegate file.

AppDelegate.swiftswift

import UIKit
import VoqalSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    // Your app delegate code
}

Step 2: Configure Fonts

Create a VoqalSDKFontConfiguration object. You can use custom fonts or default values.

Option 1: With Custom Fonts

// Configure custom fonts
let fontConfiguration = VoqalSDKFontConfiguration(
    headerFont: UIFont.systemFont(ofSize: 18, weight: .bold),
    messageFont: UIFont.systemFont(ofSize: 16, weight: .regular),
    primaryFont: UIFont.systemFont(ofSize: 16, weight: .semibold),
    secondaryFont: UIFont.systemFont(ofSize: 14, weight: .regular),
    chatInputFont: UIFont.systemFont(ofSize: 16, weight: .regular)
)

Option 2: Use Default Fonts

// Use default font configuration
let fontConfiguration = VoqalSDKFontConfiguration()

Step 3: Configure SDK

Create a VoqalSDKConfiguration with your app settings and the font configuration.

// Configure the SDK
let configuration = VoqalSDKConfiguration(
    requestId: "your_request_id",
    chatWelcomeMessage: "Welcome! How can I help you today?",
    voqalButtonIcon: UIImage(systemName: "mic.fill"),
    voqalButtonColor: .systemBlue,
    chatHeaderTitle: "Voqal Assistant",
    chatHeaderIcon: UIImage(systemName: "message.fill"),
    recordingButtonBackgroundColor: .systemRed,
    fontConfiguration: fontConfiguration,
    recordingInteractionMode: .tapToToggle  // or .holdWhilePressed
)

Step 4: Initialize SDK

Call the setup method with your configuration. This should be done in your AppDelegate's application(_:didFinishLaunchingWithOptions:) method.

AppDelegate.swiftswift

import UIKit
import VoqalSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication,
                    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Setup font configuration
        let fontConfiguration = VoqalSDKFontConfiguration()

        // Setup SDK configuration
        let configuration = VoqalSDKConfiguration(
            requestId: "your_request_id",
            chatWelcomeMessage: "Welcome! How can I help you today?",
            voqalButtonIcon: UIImage(systemName: "mic.fill"),
            voqalButtonColor: .systemBlue,
            chatHeaderTitle: "Voqal Assistant",
            chatHeaderIcon: UIImage(systemName: "message.fill"),
            recordingButtonBackgroundColor: .systemRed,
            fontConfiguration: fontConfiguration,
            recordingInteractionMode: .tapToToggle
        )

        // Initialize SDK
        VoqalSDKManager.shared.setup(configuration: configuration)

        return true
    }
}

Voqal Button

Step 1: Add VoqalButton to Your View

In your ViewController, add a VoqalButton to your view.

ViewController.swiftswift

import UIKit
import VoqalSDK

class ViewController: UIViewController {

    let voqalButton: VoqalButton = {
        let button = VoqalButton(type: .custom)
        button.translatesAutoresizingMaskIntoConstraints = false
        return button
    }()

    override func viewDidLoad() {
        super.viewDidLoad()

        // Add button to view
        view.addSubview(voqalButton)

        // Setup constraints
        NSLayoutConstraint.activate([
            voqalButton.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            voqalButton.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor, constant: -20),
            voqalButton.widthAnchor.constraint(equalToConstant: 60),
            voqalButton.heightAnchor.constraint(equalToConstant: 60)
        ])

        // Set delegate
        voqalButton.delegate = self
    }
}

Step 2: Implement VoqalButtonDelegate

Conform to the VoqalButtonDelegate protocol to handle button events.

ViewController.swiftswift

extension ViewController: VoqalButtonDelegate {

    func getToken() -> String {
        // Return your authentication token
        return "your_auth_token_here"
    }

    func getViewController() -> UIViewController {
        // Return the current view controller
        return self
    }

    func voqalButton(didUploadRecording result: String) {
        // Handle successful recording upload
        print("Recording uploaded successfully: \(result)")

        // Update your UI or process the result
        DispatchQueue.main.async {
            // Your success handling code here
        }
    }

    func voqalButton(didFailWith error: any Error) {
        // Handle error
        print("Recording failed with error: \(error.localizedDescription)")

        // Show error to user
        DispatchQueue.main.async {
            let alert = UIAlertController(
                title: "Error",
                message: error.localizedDescription,
                preferredStyle: .alert
            )
            alert.addAction(UIAlertAction(title: "OK", style: .default))
            self.present(alert, animated: true)
        }
    }
}

Complete Example

Here's a complete ViewController implementation with VoqalButton.

ViewController.swiftswift

import UIKit
import VoqalSDK

class ViewController: UIViewController {

    let voqalButton: VoqalButton = {
        let button = VoqalButton(type: .custom)
        button.translatesAutoresizingMaskIntoConstraints = false
        return button
    }()

    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .systemBackground

        // Add button to view
        view.addSubview(voqalButton)

        // Setup constraints
        NSLayoutConstraint.activate([
            voqalButton.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            voqalButton.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor, constant: -20),
            voqalButton.widthAnchor.constraint(equalToConstant: 60),
            voqalButton.heightAnchor.constraint(equalToConstant: 60)
        ])

        // Set delegate
        voqalButton.delegate = self
    }
}

extension ViewController: VoqalButtonDelegate {

    func getToken() -> String {
        return "your_auth_token_here"
    }

    func getViewController() -> UIViewController {
        return self
    }

    func voqalButton(didUploadRecording result: String) {
        print("Recording uploaded: \(result)")
        DispatchQueue.main.async {
            // Handle success
        }
    }

    func voqalButton(didFailWith error: any Error) {
        print("Error: \(error.localizedDescription)")
        DispatchQueue.main.async {
            // Handle error
        }
    }
}

Delegate Methods Reference

1
getToken() -> String
Returns your authentication token for API requests.
2
getViewController() -> UIViewController
Returns the current view controller used to present the chat interface.
3
voqalButton(didUploadRecording:)
Called when the recording is successfully uploaded and processed. The result string contains the response.
4
voqalButton(didFailWith:)
Called when an error occurs during recording or upload. Handle errors appropriately in your app.

Need Help?

If you run into any issues or have questions, feel free to reach out to our support team or check out our GitHub repository.

View on GitHub Get Started