Configuration

Last updated Aug 4, 2026

One configuration object drives the whole experience. The model is identical on iOS, Android, and Flutter — examples below are Swift; the other platforms use the same names.

Theming

One VoqalTheme drives every surface. Hairlines, text tiers, and fills are derived automatically so the assistant looks native in light or dark.

Theme.swift

config.theme = VoqalTheme(    accent: "#2d5bff",        // your brand color (hex)    accent2: "#5b8dff",       // optional gradient pair    appearance: .auto,        // .light · .dark · .auto (follows the phone)    font: nil,                // your app's font — one font for ALL text    radius: 20)               // base corner radius for cards & the sheet

Presentation style

The default .sheet slides up and is swipe-to-dismiss; .fullScreen takes the whole screen edge-to-edge and dismisses via the close button. This is a setup-time setting.

AppDelegate.swift

config.presentationStyle = .fullScreen   // default: .sheet

Header branding

Replace the default “Voqal” title and mark with your own. Leave both unset to fall back to the Voqal title and mark.

AppDelegate.swift

config.strings.chatHeaderTitle = "Rabbit"config.icons.chatHeaderIcon = UIImage(named: "RabbitLogo")

Action button

Optionally show an accent-colored button next to the voice wave that takes the user to a page in your app — a checkout screen, for example. The SDK renders the button; your app owns the route. Off by default.

AppDelegate.swift

// Enable the button (nil icon → a default shopping-bag glyph).config.actionButton = VoqalActionButton(icon: UIImage(named: "Cart"))// Navigate from your own view controller when it's tapped.func voqalDidTapActionButton() {    let checkout = CheckoutViewController()    getViewController().present(checkout, animated: true)}

When tapped, the SDK dismisses the assistant first unless you pass dismissOnTap: false, then calls you back.

Home screen

The greeting name, the “Try saying” suggestions, and whether the live data glance shows when the assistant opens.

AppDelegate.swift

config.home = VoqalHome(    userName: "Nour",    pinnedCTAs: ["What's my balance?", "Create a payment link"],    showAgentGlance: true)

Configuration reference

Property	Type	Default	Description
`requestId`	String	required	Environment routing — `prod-` or `stg-` prefix.
`apiKey`	String	required	Your Voqal API key (`pk_live_…`), sent as `X-Voqal-Key`.
`theme`	VoqalTheme	default	accent, accent2, appearance, font, radius.
`home`	VoqalHome	empty	userName, pinnedCTAs, showAgentGlance.
`presentationStyle`	PresentationStyle	`.sheet`	`.sheet` (slide-up) or `.fullScreen` (edge-to-edge).
`strings`	StringsConfiguration	“Voqal”	`chatHeaderTitle`— the assistant’s name in the header.
`icons`	IconConfiguration	accent orb	`chatHeaderIcon`, `voqalButtonIcon`.
`actionButton`	VoqalActionButton?	off	Optional in-app navigation button next to the voice wave.
`conversationTimeout`	TimeInterval	`7200`	How long a conversation resumes after close and reopen (seconds).
`agentURL`	URL?	baked in	Override the engine endpoint (rarely needed).

Fast first turn — call prewarm right after setup: it opens the engine connection in the background so the assistant is instant when opened.
Conversation memory — conversationTimeout (default 2h) controls how long a conversation resumes after the sheet is closed and reopened.