iOS Swift SDK

The Woes iOS SDK gives your customers a native live-chat experience in SwiftUI or UIKit. It uses the same public widget API as the web widget, so messages still route to the configured workspace or agent widget key and appear in the Woes Inbox.

What The SDK Does

Capability	Details
Native UI	Ships a SwiftUI `WoesLiveChatView` and UIKit `WoesLiveChatViewController`.
Widget routing	Uses a workspace key (`trovw_...`) or agent key (`trovw_agent_...`).
Conversation continuity	Stores the conversation key and history secret per widget key.
AI and handoff	Sends messages through Woes so the selected AI agent or operator can reply.
Identity verification	Attaches server-generated HMAC email hashes or JWT proofs to message requests.
Surveys	Submits configured CSAT or NPS surveys through the public widget API.

Requirements

iOS 15 or later.
Swift 5.9 or later.
A Woes workspace or agent widget public key from Settings → Keys.

Install With Swift Package Manager

In Xcode, open File → Add Package Dependencies… and add the repository that contains Woes. Select the WoesLiveChat package under sdk/ios. For local testing, add the local package path:

/path/to/woes/sdk/ios

SwiftUI Quick Start

import SwiftUI
import WoesLiveChat

struct SupportScreen: View {
    var body: some View {
        WoesLiveChatView(
            configuration: WoesConfiguration(
                publicKey: "trovw_agent_xxx",
                title: "Acme Support",
                identity: WoesIdentity(
                    email: "ada@example.com",
                    name: "Ada Lovelace",
                    emailHash: "<server-generated-hmac>"
                ),
                customFields: [
                    "plan": .string("pro"),
                    "build": .number(42)
                ]
            )
        )
    }
}

Mount the view wherever you want the support experience to appear. The SDK loads widget configuration, restores any previous conversation for that public key, sends messages, and polls for AI or operator replies.

UIKit Quick Start

import UIKit
import WoesLiveChat

let controller = WoesLiveChatViewController(
    configuration: WoesConfiguration(
        publicKey: "trovw_agent_xxx",
        title: "Acme Support"
    )
)

present(controller, animated: true)

Identity Verification

If your workspace requires verified widget identity, generate the proof on your server and pass it to the SDK:

WoesIdentity(
    email: "ada@example.com",
    name: "Ada Lovelace",
    emailHash: "<server-generated-hmac>"
)

Do not compute HMACs or store widget identity secrets in your iOS app. Use your backend to generate either:

emailHash for HMAC email mode.
jwt for JWT identity mode.

A mobile identity endpoint should use the same server-side contract as the web widget: authenticate the app user, normalize email with trim().lowercased(), sign with the server-only WOES_WIDGET_IDENTITY_SECRET, and return a no-store response. If the user signs in or switches accounts, refresh the SDK identity and send the new proof before the next message. The current iOS SDK attaches identity proof to widget message requests. It does not call the web widget’s /api/widget/identity preflight route on its own. If identity verification is disabled, email, name, and company can still help operators recognize the customer, but verified identity is required for trusted account-specific context.

Custom Fields

Use customFields for safe, operator-visible context that should be attached to the next widget message:

WoesConfiguration(
    publicKey: "trovw_agent_xxx",
    customFields: [
        "plan": .string("enterprise"),
        "trial": .bool(false)
    ]
)

The widget API sanitizes these fields server-side and drops secret-like keys.

Headless Mode

Use WoesLiveChatViewModel or WoesAPIClient if you want to build a custom interface:

let configuration = WoesConfiguration(publicKey: "trovw_agent_xxx")
let viewModel = WoesLiveChatViewModel(configuration: configuration)

await viewModel.start()
await viewModel.send("How do I create an API key?")

API Boundaries

The SDK uses public widget routes, not the /api/v1 REST API:

GET /api/widget/config
GET /api/widget/messages
POST /api/widget/messages
POST /api/widget/presence
GET /api/widget/feedback
POST /api/widget/csat

The current SDK does not implement widget telemetry events, published updates, or update read-state routes. The SDK never uses REST API keys, Supabase credentials, workspace secrets, operator debug traces, or provider/model internals. Conversation history still depends on the per-widget-key conversationSecret.

​iOS Swift SDK

​What The SDK Does

​Requirements

​Install With Swift Package Manager

​SwiftUI Quick Start

​UIKit Quick Start

​Identity Verification

​Custom Fields

​Headless Mode

​API Boundaries

​Related Pages