> ## Documentation Index > Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt > Use this file to discover all available pages before exploring further. # Start voice session > Prepare a real-time voice conversation with an AI Agent. Returns a WebSocket URL and a ready-made `start` message. Open a WebSocket connection to the returned `url`, send `start_message` as the first frame, then stream audio back and forth. This REST flow depends on Redis to issue a short-lived REST-to-WebSocket handoff token. During a Redis incident, clients that can construct their own `start` message may use the direct WebSocket flow below with a raw API key. You can also skip this endpoint and connect directly: `wss://api.datagrid.com/ws/voice?token=YOUR_API_KEY` **WebSocket Protocol:** Once connected, send a JSON message with `type: "start"` and the session parameters as the payload. The server responds with `type: "started"` containing the session and conversation IDs, followed by `type: "ready"` when the agent is ready to receive audio. **Audio Format:** - Client → Server: 16-bit mono PCM at 16kHz, base64-encoded - Server → Client: 16-bit mono PCM at 24kHz, base64-encoded **Message Types:** - Client: `start`, `audio`, `stop`, `interrupt`, `end_turn`, `text` - Server: `started`, `ready`, `audio`, `tool_call`, `interrupted`, `error`, `transcript`, `citation`, `ended` ## OpenAPI ````yaml post /voice openapi: 3.0.3 info: version: 0.1.1 title: Datagrid API description: Datagrid API servers: - url: https://api.datagrid.com/v1 security: - BearerAuth: [] paths: /voice: post: tags: - Voice summary: Start voice session description: > Prepare a real-time voice conversation with an AI Agent. Returns a WebSocket URL and a ready-made `start` message. Open a WebSocket connection to the returned `url`, send `start_message` as the first frame, then stream audio back and forth. This REST flow depends on Redis to issue a short-lived REST-to-WebSocket handoff token. During a Redis incident, clients that can construct their own `start` message may use the direct WebSocket flow below with a raw API key. You can also skip this endpoint and connect directly: `wss://api.datagrid.com/ws/voice?token=YOUR_API_KEY` **WebSocket Protocol:** Once connected, send a JSON message with `type: "start"` and the session parameters as the payload. The server responds with `type: "started"` containing the session and conversation IDs, followed by `type: "ready"` when the agent is ready to receive audio. **Audio Format:** - Client → Server: 16-bit mono PCM at 16kHz, base64-encoded - Server → Client: 16-bit mono PCM at 24kHz, base64-encoded **Message Types:** - Client: `start`, `audio`, `stop`, `interrupt`, `end_turn`, `text` - Server: `started`, `ready`, `audio`, `tool_call`, `interrupted`, `error`, `transcript`, `citation`, `ended` operationId: Voice.startSession requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VoiceSessionRequest' responses: '200': description: Voice session prepared content: application/json: schema: $ref: '#/components/schemas/VoiceSessionResponse' headers: X-Daily-Credit-Cap-Remaining: $ref: '#/components/headers/DailyCreditCapRemaining' X-Monthly-Credit-Cap-Remaining: $ref: '#/components/headers/MonthlyCreditCapRemaining' '429': description: >- Rate limit exceeded. The request has been throttled because the rate limit for this endpoint has been reached. Check the `Retry-After` response header and retry after the specified number of seconds. content: application/json: schema: $ref: '#/components/schemas/RateLimitError' components: schemas: VoiceSessionRequest: type: object properties: agent_id: type: string description: >- The ID of the agent to use for a direct-agent voice conversation. Ignored when voice_mode is orchestrator. nullable: true voice_mode: type: string description: >- Controls whether the session uses the voice orchestrator, with delegation tools, or talks directly to a specific agent. Defaults to orchestrator when agent_id is omitted and direct_agent when agent_id is provided. enum: - orchestrator - direct_agent nullable: true allow_delegation: type: boolean description: >- Orchestrator sessions only: set false to disable specialist delegation tools for the session. Ignored for direct-agent sessions. nullable: true conversation_id: type: string description: >- The ID of an existing conversation to continue. If not provided, a new conversation will be created. If the id cannot be resolved, the session start fails with the `conversation_not_found` error code rather than silently creating a new conversation. nullable: true config: type: object description: > Override the agent config for this voice session. Only prompt overrides are supported — voice sessions always use Gemini Live, so LLM model, agent model, planning prompt, and tool settings are not applicable. Prompt overrides fully replace the agent's stored values for this session only and are never persisted; empty or whitespace-only values are treated as omitted. nullable: true properties: system_prompt: type: string description: >- Directs your AI Agent's operational behavior during the voice session. Replaces the agent's stored system prompt for this session only. nullable: true maxLength: 20000 custom_prompt: type: string description: Custom instructions for the AI Agent during the voice session. nullable: true maxLength: 20000 voice_prompt: type: string description: >- Voice-specific instructions (tone, pacing, speaking style). Replaces the agent's stored voice instructions for this session only. Not persisted. nullable: true maxLength: 20000 file_ids: type: array description: Array of file IDs to attach to the voice conversation. items: type: string nullable: true secret_ids: type: array description: Array of secret IDs to include in the context. items: type: string nullable: true knowledge_ids: type: array description: Array of knowledge IDs to make accessible to the agent. items: type: string nullable: true page_ids: type: array description: >- Array of page IDs to make accessible to the agent. The page and all knowledge under it will be accessible. items: type: string nullable: true user: description: Override user information for this voice session. nullable: true allOf: - $ref: '#/components/schemas/UserOverride' initial_context: type: string description: >- Optional context text for the voice session. When provided, the AI will start by briefly explaining this content before listening for user input. nullable: true maxLength: 2000 initial_message: type: string description: >- Optional initial user message. When provided, the system greeting is skipped and the AI responds directly to this text (e.g. a suggested prompt). Takes precedence over initial_context. nullable: true maxLength: 2000 ephemeral: type: boolean description: >- When true, the session is ephemeral and will not save messages to conversation history. default: false nullable: true voice_config: type: object description: Voice session configuration options. nullable: true properties: turn_end_mode: type: string enum: - server - client default: server description: >- Controls how user audio turns close. 'server' uses the existing RMS and silence timer. 'client' disables that timer and requires an explicit end_turn message after each utterance. nullable: true voice_preset: type: string description: >- Voice preset to use (e.g., 'sage', 'nova', 'spark'). If not provided, uses the agent's configured voice preset or the default. nullable: true silence_commit_ms: type: number description: >- Duration of silence (no agent audio) in milliseconds before auto-committing a segment. Default: 30000 (30 seconds). nullable: true segment_max_duration_ms: type: number description: >- Maximum duration in milliseconds of a buffered segment before force-commit. Default: 180000 (3 minutes). nullable: true silence_discard_ratio: type: number description: >- Discard a segment if this fraction (0-1) of its audio is silence. Default: 0.9 (90% silence threshold). nullable: true input_transcription: type: boolean description: 'Enable transcription of user input audio. Default: true.' nullable: true output_transcription: type: boolean description: 'Enable transcription of agent output audio. Default: true.' nullable: true silence_timeout: type: boolean description: >- When true, the server closes the connection after the client has been continuously sending audio frames below the speech-detection threshold for 60 seconds. Frames are still required — a fully muted microphone (no frames sent) pauses the countdown. Disabled by default. nullable: true silent_start: type: boolean description: >- When true, skip the launch greeting and start directly in listening mode. Disabled by default. nullable: true discard_if_empty: type: boolean description: >- When true and this session creates a brand-new conversation (no conversation_id was provided), that conversation is discarded if the session ends without any message ever being sent. Has no effect when continuing an existing conversation. Disabled by default. default: false nullable: true VoiceSessionResponse: type: object required: - object - url - agent_id - start_message properties: object: type: string description: Object type discriminator. enum: - voice.session url: type: string description: >- WebSocket URL to connect to. Includes the authentication token as a query parameter. agent_id: type: string description: >- The resolved agent ID. If no agent was specified in the request, this is the default agent. start_message: type: object description: >- Ready-made JSON message to send as the first WebSocket frame after connecting. Contains `type: "start"` and a `payload` with all session parameters. RateLimitError: type: object description: >- Returned when the rate limit is exceeded. Rate limits are enforced per teamspace, endpoint path, and HTTP method over a 60-second sliding window. Each endpoint may have its own limit — check the X-RateLimit-Limit response header for the effective value. required: - error - message - retryable - status_code properties: status_code: type: integer description: The HTTP status code (429). statusCode: type: integer deprecated: true description: Deprecated. Use status_code instead. error: type: string enum: - rate_limit_exceeded description: The error code identifying this as a rate limit error. message: type: string description: A human-readable error message. mitigation: type: string description: Suggested action to resolve the error. retryable: type: boolean description: Whether the request can be retried after a delay. details: type: object properties: reason: type: string description: A detailed explanation of why the rate limit was exceeded. UserOverride: type: object description: >- User information override for converse calls. All fields are optional - only provided fields will override the default user information. properties: first_name: type: string description: Override the user's first name for this converse call. nullable: true last_name: type: string description: Override the user's last name for this converse call. nullable: true email: type: string description: Override the user's email for this converse call. nullable: true headers: DailyCreditCapRemaining: description: >- Credits left before the account's daily credit cap (set in Control Tower) is reached, rounded up. `0` means the cap has been reached; the daily cap does not block requests. Present only when a daily cap is configured. schema: type: integer example: 600 MonthlyCreditCapRemaining: description: >- Credits left before the account's monthly credit cap (set in Control Tower) is reached, rounded up. At `0`, credit-consuming requests return `402` until the next calendar month. Present only when a monthly cap is configured. schema: type: integer example: 15000 securitySchemes: BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.