# What’s new in Voice API v2?

Voice API v2 is a ground-up redesign that gives developers total flexibility, native AI integration, and a cleaner architecture for building modern voice applications. Here’s what’s new:

## Redesigned Call Model (Sessions, Calls, & Bridges)

We have replaced the flat, call-leg model of V1 with a robust, hierarchical architecture that matches how real-world voice applications operate:

Sessions: A session acts as a master container that initializes automatically as soon as the first call is created. It groups all related calls and connections together and maintains state and context throughout the entire interaction lifecycle until all associated calls are terminated.

Calls (The Core Resource): A Call represents a single participant's connection (such as PSTN, SIP, Streams or Voice Relay) to Sinch.

Inbound Calls: Created automatically when a call arrives via a Sinch voice channel. These are handled via a service webhook or dashboard configuration.

Outbound Calls: Initiated via a direct API request or dynamically inside an active session using the SVAML dial command.

Developer Power: You can interact with and control active calls in real time using the new PATCH endpoints—either by target callId or cleanly by scoping sessionId and callName.

Bridges: A mechanism to dynamically connect one or more calls within a session, enabling immediate, seamless communication and routing between different participants.

## SVAML v2: Powerful Serverless & Dynamic Call Control

The SVAML (Sinch Voice API Markup Language) has been completely overhauled. It is no longer instructions and actions; it is a powerful, nestable language designed for both standalone and dynamically routed call flows.

Core Architectural Capabilities:

Serverless Execution via Nested Events: You can now define comprehensive flows entirely within a single API payload. Because events (like onAnswer or onFail) are nested directly within the JSON, you can execute complex branching logic with no webhook round-trips required.

Dynamic Routing via Webhooks: For highly dynamic, stateful, or database-driven use cases, you can use the webhook command to intentionally pause call execution and hand control back to your backend, expecting a new set of SVAML commands in response.

Blocking vs. Non-Blocking Commands: V2 introduces precise execution models. Non-blocking commands (like dial, messages, amd) fire and run in parallel, while blocking commands (like webhook, pause, menu) pause execution until they complete.

Built-in Payload Validation: Use the new /svaml/validate and /svaml/describe endpoints to test your nested JSON structures against strict schemas before production, eliminating runtime routing errors.

Built-In Command Features:

Answering Machine Detection (AMD): Use the amd command to automatically classify calls as human, machine, beep, or unknown, natively triggering nested event handlers based on the result.

Rich IVR & Media (TTS): Build native IVR trees using the menu and gotoMenu commands, featuring built-in DTMF gathering, regex matching, timeouts, and barge-in. Dynamically manage media mid-call with messages (featuring SAY for Text-to-Speech and PLAY for audio) and stopMessages.

Native Cloud Recording: Use the startRecording command to push call audio and automatic transcriptions directly to AWS S3, Google Cloud Storage (GCP), or Azure Blob out of the box.

## Native AI Capabilities & Real-Time Streams

Voice-enable your AI agents natively without writing complex code. V2 ships with dedicated AI integration paths built directly into the API core:

Voice Relay: A powerful WebSocket bridge that streams real-time speech-to-text (STT) to your AI agent and plays back text-to-speech (TTS) responses with native barge-in and interruption detection.

Raw Audio Streaming: Pipe bidirectional, raw PCM audio streams directly to your WebSocket endpoint if you prefer to bring your own custom STT/TTS stack.

Over 750 Voices & SSML Support

Our expanded voice library now features over 750 voices, bringing you a massive selection of both standard and cutting-edge new AI voices across a multitude of languages and accents. All text-to-speech commands (SAY) support SSML, giving you fine-grained control over pronunciation, pacing, and emphasis.

## Batch Calling with Intelligent Call Pacing

Initiating and managing bulk outbound campaigns (such as notifications, marketing outreach, or appointment reminders) is fully native in V2. A Batch represents a group of call sessions initiated together as a single, highly controlled operation, eliminating the need to build your own custom throttling queues.

Parameter Templating: Send a single SVAML command payload with placeholders (e.g., @name, @time) alongside an array of target parameters. The API automatically triggers and personalizes each session.

Built-in Traffic Pacing:

Rate Limiting (maxCps): Control the maximum Calls Per Second (CPS) to comply with carrier regulatory limits.

Time-to-Live (ttlSeconds): Set a maximum time window for initiating the calls. Any call not triggered before the TTL expires is automatically skipped.

Full Lifecycle Management: Developers have native control over active operations. Fetch aggregated statistics, drill down into per-session details, or safely stop an active batch mid-run without disconnecting ongoing calls.

## CloudEvents Webhooks & Failover Reliability

Our webhooks have been fully modernized for modern event-driven, serverless architectures:

CloudEvents 1.0: Webhook events conform to the CloudEvents standard, making them directly compatible with platforms like AWS EventBridge and Apache Kafka with zero custom parsing.

Advanced Precedence Rules: V2 introduces granular event handling. You can now define event handlers at the command level (inside specific SVAML commands) to override global service-level handlers, giving you precise, per-call logic control.

Built-in Failover: If your primary webhook endpoint fails or times out (5-second limit), the blocking webhook command automatically re-routes the request to a configured fallback URL, ensuring high availability and call continuity.

## Logs & Analytics in the Customer Build Dashboard

We have completely rebuilt the dashboard experience alongside the API to make monitoring, troubleshooting, and optimization frictionless.

Logs Dashboard enables rapid troubleshooting. Developers can search for specific interactions instantly via Call or Session IDs and employ advanced filters to narrow down entries by date, Voice Services, geographical region, or voice channels (Phone, SIP, Stream, Voice Relay). Selecting any log entry opens a detailed view showing aggregated session metadata, an interactive call timeline illustrating exact state transitions (such as Queued, Initiated, In Progress, and Completed), and the raw request/response JSON payloads for validating SVAML execution.

Comprehensive Analytics Console. For macro-level insights, the new Analytics Console aggregates high-level performance metrics such as Answer Seizure Ratio (ASR), total call counts, and average call durations across all voice channels. The console offers observability into advanced features—allowing you to track active recording durations, transcription events, total TTS messages, and synthesized characters. It also features graphical distribution maps to visualize traffic geographically, alongside breakdowns of call results and explicit termination reasons (like Callee Hangup or Busy) for absolute traffic clarity.

## Unified Authentication & Webhook Security

V2 introduces a new, project-based authentication system (supporting OAuth 2.0 and Basic Auth) designed to work seamlessly across multiple Sinch products. For inbound security, webhook endpoints can now easily verify that requests are genuinely from Sinch by computing a hash of the payload using your service's access key and secret, mitigating man-in-the-middle attacks.