> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.smallest.ai/atoms/developer-guide/integrate/llms.txt. > For full documentation content, see https://docs.smallest.ai/atoms/developer-guide/integrate/llms-full.txt. # Embedding a voice agent > Drop a Smallest Atoms voice agent into a web page, mobile app, or custom client. Integration guides per platform, plus ready-to-fork cookbooks. There are two paths to put a voice agent inside your product: 1. **Embed** a pre-built component. Drop a widget into the app you already ship and get a voice session behind a single call. 2. **Integrate** the Atoms WebSocket yourself. More code to own, full control over the UI and the audio session. The table below maps each platform to both paths. ## At a glance | Platform | Embed (widget) | Integrate (WebSocket) | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | **Web** | [`` script tag](#web) | [WebSocket SDK](/atoms/developer-guide/integrate/websocket-sdk) | | **React Native** | [`react_native_voice_widget`](https://github.com/smallest-inc/cookbook/tree/main/voice-agents/react_native_voice_widget) | [React Native guide](/atoms/developer-guide/integrate/mobile/react-native) | | **iOS (Swift)** | [`ios_swift_voice_widget`](https://github.com/smallest-inc/cookbook/tree/main/voice-agents/ios_swift_voice_widget) | [iOS Swift guide](/atoms/developer-guide/integrate/mobile/ios-swift) | | **Android (Kotlin)** | [`android_kotlin_voice_widget`](https://github.com/smallest-inc/cookbook/tree/main/voice-agents/android_kotlin_voice_widget) | [Android Kotlin guide](/atoms/developer-guide/integrate/mobile/android-kotlin) | | **Flutter** | [`flutter_voice_widget`](https://github.com/smallest-inc/cookbook/tree/main/voice-agents/flutter_voice_widget) | [Flutter guide](/atoms/developer-guide/integrate/mobile/flutter) | Every mobile widget follows the same pattern: a floating pill in the host app, a bottom sheet with a live voice session on tap, and a single public API that accepts an API key and an agent ID. The implementations are independent per platform, with no shared runtime, so each widget looks and behaves native. If you need full control of the screen instead of a drop-in component, the [reference apps](#reference-apps) show the same transport and audio code in a full-screen voice UI. ## Web Paste two lines into any HTML page: ```html ``` That renders a floating call bubble on the page. Clicking it opens a voice session with your agent. The component is a web-standard Custom Element and works in any framework (React, Vue, Svelte, plain HTML). Configure theme, position, and agent ID through HTML attributes. To customize the widget's appearance or placement, see the [Widget features reference](/atoms/atoms-platform/features/widget). ## React Native ```tsx import { AtomsWidget } from './widget/AtomsWidget'; ``` The [React Native widget cookbook](https://github.com/smallest-inc/cookbook/tree/main/voice-agents/react_native_voice_widget) ships an Expo app with the widget wired into a MyClinic receptionist host. It uses `react-native-audio-api` for mic capture and gapless playback, owns the WebSocket session, and exposes a mute button plus a live transcript. | Host with pill | Sheet open | | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | ![React Native host with Ask AI pill](https://files.buildwithfern.com/smallest-ai.docs.buildwithfern.com/710d046296e341c0bccb24795dcd0ff313ddb624338acaaaaeb73003ff54d4ae/products/atoms/pages/dev/integrate/images/widgets/rn-host.png) | ![React Native widget sheet listening](https://files.buildwithfern.com/smallest-ai.docs.buildwithfern.com/af2bb738f8983419f2ed90a2d6c051b9f31e2beb50c1a43971ab7d628a6e1c6c/products/atoms/pages/dev/integrate/images/widgets/rn-sheet.png) | For integrating the transport into an existing RN app without the widget wrapper, follow the [React Native integration guide](/atoms/developer-guide/integrate/mobile/react-native). ## iOS (Swift) ```swift import SwiftUI struct RootView: View { var body: some View { ZStack { YourHostScreen() AtomsWidget(apiKey: API_KEY, agentId: AGENT_ID, label: "Ask AI") } } } ``` The [iOS Swift widget cookbook](https://github.com/smallest-inc/cookbook/tree/main/voice-agents/ios_swift_voice_widget) is a SwiftUI component built on `URLSessionWebSocketTask` and `AVAudioEngine`, with no external dependencies. Xcode project is generated by `xcodegen` from `project.yml`, so you can audit the full build config at a glance. | Host with pill | Sheet open | | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | | ![iOS host with Ask AI pill](https://files.buildwithfern.com/smallest-ai.docs.buildwithfern.com/dce6a8162becc2681c9e9b8ab434fa0819b161857444b1d2c96e8181920d3a7a/products/atoms/pages/dev/integrate/images/widgets/ios-host.png) | ![iOS widget sheet speaking](https://files.buildwithfern.com/smallest-ai.docs.buildwithfern.com/1dc8a6d4e55ddffe834a5cd1df08c3e5a8b6e468495acb650395f00a41d46b46/products/atoms/pages/dev/integrate/images/widgets/ios-sheet.png) | For integrating into an existing app without the widget wrapper, see the [iOS Swift guide](/atoms/developer-guide/integrate/mobile/ios-swift). ## Android (Kotlin) ```kotlin import ai.smallest.atomswidget.AtomsWidget setContent { Box(Modifier.fillMaxSize()) { YourHostScreen() AtomsWidget(apiKey = API_KEY, agentId = AGENT_ID, label = "Ask AI") } } ``` The [Android Kotlin widget cookbook](https://github.com/smallest-inc/cookbook/tree/main/voice-agents/android_kotlin_voice_widget) is a Jetpack Compose composable that uses OkHttp's WebSocket client and platform `AudioRecord` / `AudioTrack`. Material 3 `ModalBottomSheet` manages the sheet. Gradle injects credentials via `BuildConfig`. | Host with pill | Sheet open | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | ![Android host with Ask AI pill](https://files.buildwithfern.com/smallest-ai.docs.buildwithfern.com/9cc3f7b425abecc9fe0befe93535c012c2fea6dc1dfb9c5cf291876c33a957ee/products/atoms/pages/dev/integrate/images/widgets/android-host.png) | ![Android widget sheet joined](https://files.buildwithfern.com/smallest-ai.docs.buildwithfern.com/35e0dac017c7fe19dd5f05e101469729fae0ed867d58ce96564afa2987251aa0/products/atoms/pages/dev/integrate/images/widgets/android-sheet.png) | For integrating into an existing app without the widget wrapper, see the [Android Kotlin guide](/atoms/developer-guide/integrate/mobile/android-kotlin). ## Flutter ```dart AtomsWidget(apiKey: API_KEY, agentId: AGENT_ID, label: 'Ask AI') ``` The [Flutter widget cookbook](https://github.com/smallest-inc/cookbook/tree/main/voice-agents/flutter_voice_widget) is a Material widget on top of `web_socket_channel`, the `record` package for PCM capture, and `flutter_pcm_sound` for playback. Credentials are injected via `--dart-define` at build time. | Host with pill | Sheet open | | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | ![Flutter host with Ask AI pill](https://files.buildwithfern.com/smallest-ai.docs.buildwithfern.com/5071ba6c82cfd75281fc39fb066504c84ded2cf671550a797800ae0e4bc60097/products/atoms/pages/dev/integrate/images/widgets/flutter-host.png) | ![Flutter widget sheet speaking](https://files.buildwithfern.com/smallest-ai.docs.buildwithfern.com/fbdd0d814f4b95285b0bd38fa33f479cb16088f5d487b23da8ba66220becd7af/products/atoms/pages/dev/integrate/images/widgets/flutter-sheet.png) | For integrating into an existing app without the widget wrapper, see the [Flutter guide](/atoms/developer-guide/integrate/mobile/flutter). ## Reference apps If the widget pattern is too constrained (for example, you want voice to own the whole screen, or you want to study the transport plumbing in isolation), the cookbook also ships full-screen reference apps per platform: * [React Native (Hearthside)](https://github.com/smallest-inc/cookbook/tree/main/voice-agents/react_native_voice_agent) * [iOS Swift](https://github.com/smallest-inc/cookbook/tree/main/voice-agents/ios_swift_voice_agent) * [Android Kotlin](https://github.com/smallest-inc/cookbook/tree/main/voice-agents/android_kotlin_voice_agent) * [Flutter](https://github.com/smallest-inc/cookbook/tree/main/voice-agents/flutter_voice_agent) Each is a runnable app with the same transport and audio code as the matching widget. Fork it, swap the agent ID, ship. The [`MOBILE_COOKBOOKS.md`](https://github.com/smallest-inc/cookbook/blob/main/voice-agents/MOBILE_COOKBOOKS.md) cross-reference in the cookbook repo covers validation checklists, shared debug patterns (transport counter, mute-for-loop-debugging, Android emulator mic toggle, iOS simulator audio caveat), and a "when to use which cookbook" matrix. ## Roadmap First-party SDK packages on npm, Swift Package Manager, Maven, and pub.dev are the next step. The transport, audio, and UI code in the widget cookbooks today becomes the SDK tomorrow. Until then, the cookbooks are the supported embed path. ## Reference * [Realtime Agent WebSocket API](/atoms/api-reference/api-reference/realtime-agent/realtime-agent). The protocol every client speaks. * [WebSocket SDK (web)](/atoms/developer-guide/integrate/websocket-sdk). The browser-side JS SDK. * [Widget features](/atoms/atoms-platform/features/widget). Web widget configuration options.