Developer Docs - Mobile Docs - Voice Agent

C19.0M19.0

Provides a real-time, conversational voice assistant inside your mobile app. The block opens a live audio session with an AI provider, streams the microphone up, plays the assistant's spoken response back, and renders a running transcript on screen (if enabled). Use it to give people a hands-free way to ask questions about themselves, their family, their giving, upcoming events, or anything else you expose through an MCP agent.

What it does

Who uses it

The Voice Agent behaves the same way for everyone, but what a person can actually do through it depends on who they are, because every tool call the agent makes runs as the signed-in person.

Because access is decided per person at the tool layer, you can ship a single block to your whole congregation and trust that each person's conversation stays inside their own permissions.

Placement

For the best experience, give the block a full, distraction-free surface. Place it on a page or a cover sheet that has no navbar, so the transcript, pulse bar, and controls own the whole screen. A surrounding navigation chrome competes with the block's own bottom controls and breaks the sense of a dedicated, focused conversation. The block already manages its own Stop action and keeps the screen awake, so it does not need a host navbar to function.

Settings

Providers

The block supports two realtime providers and detects which one to use from the prefix of the configured API key:

The provider choice also sets the default voice (alloy for OpenAI, eve for xAI) and which voices the in-app settings sheet offers. If an administrator switches the API key from one provider to the other, any saved per-person voice that no longer matches the active provider is replaced with that provider's default on the next launch.

The block works with each provider's Realtime API only. OpenAI's GPT-Live is a separate product that is not compatible with that API, so the block does not support it.

Voice models

These recommendations reflect the models, pricing, and tool-calling behavior available as of October 2026. Realtime voice offerings change quickly, so check each provider's current lineup before committing to a model.

Choosing a model

The Model setting accepts either a specific version, such as grok-voice-3.0, or an alias, such as grok-voice-latest, that the provider points at its newest version.

Breakdown

gpt-realtime-2.1 (OpenAI), recommended

OpenAI's current realtime model, replacing gpt-realtime-2 at the same price. Use with a thorough system prompt. In our testing, gpt-realtime-2 scored 10/10 on tool calls with a prompt and 7/10 without. Interruptions feel the most natural of the options here, though background noise and speakerphone echo can still cut a reply short.

Pricing: $32 per 1M audio input tokens ($0.40 cached), $64 per 1M audio output tokens. About $0.50 to $1.00 per 5-minute session.

grok-voice-latest (xAI), currently Grok Voice 3.0

Tool calling is solid. Choose Grok when you want simple, predictable per-minute billing. Trade-off: interruptions rely on xAI's own detection and can feel less smooth than OpenAI, with brief overlap when someone breaks in. For pastoral conversations with frequent emotional interruptions, test it in a realistic setting first.

Pricing: Flat $0.08 per minute. About $0.40 per 5-minute session.

gpt-realtime-mini (OpenAI), not recommended

Failed about 60% of tool calls in testing (4/10 with or without a prompt), including wrong tools and wrong answers, not just refusals. OpenAI shuts this model down on January 20, 2027. Its replacement, gpt-realtime-2.1-mini, has not been tested with the block yet.

Official model references

Security

The block never hands the configured API key to the mobile client. On every session start the server mints a short-lived ephemeral token (5 minute TTL) against the provider's /realtime/client_secrets endpoint and returns only that token to the device. The block also requires an authenticated person.

MCP tools

The voice agent can be extended with MCP (Model Context Protocol) servers so the assistant can call tools and read context from Rock or from external systems.

Both lists are merged and passed to the realtime session as the available tool set. You tailor what the agent can actually do by choosing which skills and tools the connected AI Agent exposes. Add the capabilities you want people to reach by voice, leave off the ones you don't, and the conversation is shaped accordingly. For how to build and configure these agents, see the Rock AI Agents manual: https://community.rockrms.com/developer/ai-agents

How the MCP API key is scoped per person

Each person who uses the Voice Agent has their own MCP API key. The first time someone opens the block, Rock creates a unique key for them and stores it on their account. Every session they have from then on reuses that same key.

The key is embedded in the MCP server URL the voice agent uses to call back into Rock. So when the agent runs a tool on someone's behalf, the request carries that person's key, and Rock uses it to identify exactly which person is on the other end. Permissions, data access, and any tool that depends on knowing who the person is all resolve to that person automatically. Because every person has a different key, two people using the same voice agent stay fully isolated: their sessions never share state, and one person's voice agent can never see another person's data.

Personal settings

In addition to the admin-controlled block settings above, the block exposes an in-app Settings cover sheet (gear icon in the bottom-left of the block) that lets each person choose:

Each of these is saved as a per-person block preference and restored the next time the block loads, so each person keeps their own preferred voice and interaction style.

Microphone permission

The block requests microphone permission via the platform permission helper on load. If the person denies the request, the block does not start a session and surfaces nothing further; the rest of the page renders normally. Microphone permissions can then be enabled within the OS settings. The display is kept awake for the duration of the session and released on unload.

Notes