# Voice API v2 # Core Concepts The Voice API enables embedding voice calling into applications for virtually limitless use cases. From **number masking** for privacy, automated **appointment reminders**, and **outreach campaigns** with answering machine detection, to **bridging calls** between PSTN and SIP endpoints, the API offers the flexibility and control needed for modern communications. ## Call Model {% table %} - Concept - Description --- - **Session** - A session initiates as soon as the first call is created. It serves as a container for all related calls and their connections, maintaining context and state throughout the interaction. The session persists until all associated calls are terminated. --- - **Call** - A single participant's connection in a session (e.g., caller or callee). - **Inbound Call:** A call initiated from an external source (PSTN, SIP, etc.) into the service. - **Outbound Call:** A call initiated by the service to an external destination. --- - **Bridge** - A mechanism to connect one or more calls, so that participants can communicate with each other. ![session bridge chart](/images/voicev2/voicev2-session-chart.png) {% /table %} ### Initiating Calls There are a few ways to create a call: 1. **Inbound Calls:** Triggered by incoming traffic from PSTN, SIP, or other sources. 2. **Outbound Calls (via Dial):** Initiated from within an existing call session using the `dial` command. 3. **Outbound Calls (via API):** Created directly by sending an API request to the Voice API. 4. **Call Queuing:** Calls can be queued and processed based on parameters such as priority, time, or custom logic. ### Call Pacing (Batch) The new Voice API v2 supports Call pacing via batch calling to efficiently manage high volumes of outbound calls. This is especially useful for scenarios like appointment reminders, notifications, or campaigns where customers need to reach multiple recipients in a controlled and scalable way. #### How To Initiate Batch Calls To initiate several calls in a batch, send a POST request to the `/v2/projects/{projectId}/calls` endpoint. The request body contains a SVAML payload describing the call flow and a list of parameters for each call in the batch. The API queues and triggers calls according to the provided configuration, such as maximum calls per second (`maxCps`) and time-to-live (`ttlSeconds`). ```json { "commands": [ { "command": "dial", "callName": "batch-notification", "from": { "type": "PHONE", "phone": { "number": "@from" } }, "to": { "type": "PHONE", "phone": { "number": "@to" } }, "events": { "onAnswer": [ { "command": "messages", "messages": [ { "type": "SAY", "say": { "text": "Hello @name, you have an appointment tomorrow at 10 AM.", "voiceName": "Emma" } } ] } ] } } ], "parameters": [ { "from": "+46712345678", "to": "+46787654321", "name": "Alice" }, { "from": "+46712345678", "to": "+46781234567", "name": "Bob" } ], "batchOptions": { "maxCps": 10, "ttlSeconds": 60 } } ``` - **commands:** SVAML commands describing the call flow for each call in the batch. Parameter placeholders start with `@` and can be used as variables for each call. They can be used alone as in `@from` or in combination with text in a say message (e.g., `Hello @name, your appointment is at @time`). - **parameters:** An array of objects, each specifying the values for the placeholders in the commands. Each object represents a call to be queued and triggered. - **batchOptions:** Controls how the batch is processed: - `maxCps`: Maximum number of calls per second to be initiated. - `ttlSeconds`: Time-to-live for the batch in seconds; calls not initiated within this time window will be skipped. The API responds with metadata for the queued calls: - **sessionIds:** Each call in the batch is assigned a unique sessionId, which can be used to track the state and progress of individual calls. - **batchId:** The batchId identifies the entire batch operation, allowing batch state and summaries to be queried, or the batch to be managed as a whole (e.g., cancel unprocessed calls). - **Other properties:** The response may also include other Ids, timestamps, and state related information. #### How Calls Are Triggered When a batch request is submitted: 1. The API validates the SVAML commands and parameters. 2. Calls are queued and triggered according to `maxCps` and `ttlSeconds` settings. 3. Each call is processed independently, using the provided parameters to personalize the call flow. 4. The API tracks the state of each call (e.g., `QUEUED`, `INITIATED`, `IN_PROGRESS`, `COMPLETED`). 5. Batch progress can be monitored and summaries can be retrieved via the [GET] `/v2/projects/{projectId}/batches/{batchId}` endpoint. ## Call Lifecycle A call progresses through several states from creation to completion. **Call States** {% table %} - State - Description --- - `QUEUED` - Call is waiting to be processed. --- - `INITIATED` - Call setup is in progress (ringing). --- - `IN_PROGRESS` - Call is answered and active. --- - `COMPLETED` - Call ended normally. --- - `REJECTED` - Recipient rejected the call. --- - `NO_ANSWER` - Recipient did not answer. --- - `CANCEL` - Call was cancelled before being answered. --- - `BUSY` - Recipient was busy. --- - `FAILED` - Call could not be set up. {% /table %} **Call Transitions** ![transition states flowchart](/images/voicev2/voicev2-transition-states.png) This diagram shows how a call moves between states. Typically, most calls start at `QUEUED`, progress to `INITIATED`, and either get answered (`IN_PROGRESS`) or end in a final state (`COMPLETED`, `NO_ANSWER`, etc.). ## Handling Events with Webhooks When a specific event occurs (for example, a call is answered), the Voice API v2 sends an HTTP request (usually POST) to the webhook URL configured in service settings. The request contains details about the event, such as call identifiers and timestamps. The application can then respond with [SVAML commands](/docs/voice-2.0/api-reference/svaml) to control the ongoing call or perform other actions. ### Typical Request-Response Cycle 1. An event (e.g., call.answered) occurs in the Voice API. 2. The API sends a POST request to the configured webhook endpoint with event details. 3. The server processes the event and responds with SVAML commands (e.g., play a message, gather input). 4. The API executes the commands and updates the call state. ```mermaid sequenceDiagram participant VoiceAPI as Voice API participant Backend as Application Backend VoiceAPI ->> Backend: POST webhook (event details) Backend ->> VoiceAPI: SVAML commands (response) VoiceAPI ->> Backend: Further webhooks (if needed) Backend ->> VoiceAPI: Additional SVAML commands ``` Webhook endpoints must respond within 5 seconds. If the endpoint fails or times out and a `fallbackUrl` is configured, the request is re-sent to the fallback URL. See *Timeouts and failover* in the **Webhooks** section for the algorithm and its effect on delivery guarantees. ### Webhooks vs. Events - **Webhooks:** External HTTP notifications sent to the application when specific events occur. - **Events:** Internal API notifications about call state changes; can be exposed via webhooks for external handling or internally by predefining event handlers in SVAML commands. ### Event Naming Convention Events are named using the pattern `resource.command.event`. For example: - `call.answered`: Indicates that a call was answered. - `call.amd.machine`: Indicates that the Answering Machine Detection (AMD) on a call detected a machine. This convention helps clearly identify the resource, the command involved, and the specific event that occurred. #### Common Webhook Events - `call.incoming`: Triggered when a call is received from PSTN, SIP, etc. - `call.answered`: Triggered when a call is answered. - `call.hangup`: Triggered when a call is hung up. ### Precedence Rules When handling events in call flows, the Voice API applies the following precedence rules to determine which SVAML commands are executed: - **Command-Level Event Handlers:** If an event handler (e.g., `on_answer`, `on_machine`) is defined directly within a SVAML command, the commands specified in that handler are executed first for that event. - **Service Configuration Fallback:** If the event handler is not defined in the SVAML command, the API falls back to the event handler defined in the service configuration. This allows default behaviors for events to be set at the service level. - **Execution Order:** - Command-level event handlers always take priority over service-level handlers. - If neither is defined, the event is ignored and no commands are executed for that event. **Best Practice:** Define event handlers in SVAML commands for custom, per-call logic. Use service configuration event handlers for default or global behaviors across all calls. ### Webhook Request Example When a call is answered, the API sends a POST request to the configured webhook endpoint that includes the event type and the current call details. The webhook endpoint should return a valid SVAML payload specifying which commands to execute on the call. For example, the response below synthesizes a welcome message and then ends the call. ```json { "commands": [ { "command": "messages", "messages": [ { "type": "SAY", "say": { "text": "Welcome to our service!", "voiceName": "Emma" } } ], "events": { "onFinish": [ { "command": "hangup" } ] } } ] } ``` ### Regions The following table displays the servers available for each region. | Region | Server | | ------ | ------ | | Global endpoint - Redirected by Sinch to the closest region. | `https://voice.api.sinch.com` | | North America 1 - East | `https://us1.voice.api.sinch.com` | | South America 1 - East | `https://br1.voice.api.sinch.com` | | Europe 1 - Central | `https://eu1.voice.api.sinch.com` | | Asia Pacific 1 - Southeast | `https://sg1.voice.api.sinch.com` | | Australia & Oceania 1 - Southeast | `https://au1.voice.api.sinch.com` | ### Best Practices - **Respond Quickly:** Webhook requests should be processed and responded to as quickly as possible to avoid call delays. - **Idempotency:** A failed request is re-sent to the fallback URL, so the same event can arrive more than once. Make the handler idempotent and deduplicate on the `ce-id` and `ce-source` headers — see *Timeouts and failover* in the **Webhooks** section. - **Logging:** Log incoming webhook requests and responses for troubleshooting and auditing. - **Validation:** Validate incoming requests to ensure they are from the Voice API (see Security below). ### Security To safeguard a webhook endpoint, verify that incoming requests are genuinely sent by the Voice API and have not been altered in transit. This prevents unauthorized access and mitigates risks such as man-in-the-middle attacks. 1. Each service has an identifier and a secret. 2. When a webhook arrives, use the secret to compute a signature over the canonical request string. 3. Compare the computed signature to the one in the request authorization header. 4. Only process the webhook if the signatures match. For the exact `Authorization` header format, the canonical string that is signed, the signature algorithm and a worked example, see *Request signing* on the **Call webhook** operation in the **Webhooks** section. Access to the webhook endpoint may also be restricted by IP address, and HTTPS can be used to encrypt traffic. Make and receive voice calls with Sinch's RESTful Voice API interface. Version: 2.0.58 License: Sinch License ## Servers Endpoint which enables consuming the Voice API globally - Redirected by Sinch to the closest region. ``` https://voice.api.sinch.com ``` North America 1 - East ``` https://us1.voice.api.sinch.com ``` South America 1 - East ``` https://br1.voice.api.sinch.com ``` Europe 1 - Central ``` https://eu1.voice.api.sinch.com ``` Asia Pacific 1 - Southeast ``` https://sg1.voice.api.sinch.com ``` Australia & Oceania 1 - Southeast ``` https://au1.voice.api.sinch.com ``` ## Security ### BasicAuth Use HTTP Basic authentication. - **Username**: the **Access Key ID** - **Password**: the **Access Key Secret** Send credentials in the `Authorization` header: `Authorization: Basic ` Create and manage access keys in the Dashboard: https://dashboard.sinch.com/settings/access-keys Type: http Scheme: basic ### SinchOAuth2 OAuth 2.0 **Client Credentials** grant (recommended for production). Exchange the **Access Key ID** (`client_id`) and **Access Key Secret** (`client_secret`) for a short-lived Bearer token. Tokens typically expire after **3600 seconds**. When the token expires, request a new one using the same `tokenUrl`. There is no separate refresh token in the client credentials flow — simply re-authenticate. Access keys are managed in the Dashboard: https://dashboard.sinch.com/settings/access-keys Type: oauth2 ## Download OpenAPI description [Voice API v2](https://developers.sinch.com/_bundle/docs/voice-2.0/api-reference/voice.yaml) ## Calls Calls are the core resource for voice interactions. The API supports creating, retrieving, updating, and deleting calls, and accessing call metadata, state, and participants. A `Call` resource represents a connection between a voice channel and Sinch. Using this resource, customers can initiate a call, fetch information about a completed call, fetch a list of calls made to and from the [Voice service](/docs/voice-2.0/api-reference/voice/services/), and redirect or end a call in progress. A call always has a `direction`, either *inbound* or *outbound*. The direction of the call dictates when and how the call can be controlled. An **outbound** call is created when a DIAL command is invoked. Outbound calls can be controlled by supplying [SVAMLv2](/docs/voice-2.0/api-reference/svaml) commands when creating the call, via the responses to the call's webhooks, or by sending a `PATCH` request. An **inbound** call is created when the service receives a call via one of the Sinch voice channels [Phone, In-App, SIP, Streams]. To handle incoming calls, a service webhook must be configured via the [services API](/docs/voice-2.0/api-reference/voice/services) or the [dashboard](https://dashboard.sinch.com/voice). ### List calls made with Sinch Voice API - [GET /v2/projects/{projectId}/calls](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/calls/listcalls.md): List and filter calls made with Sinch ### Create and initiate a new outbound voice call - [POST /v2/projects/{projectId}/calls](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/calls/createcall.md): Create a new outbound call associated to the project's default service or to the service specified in the serviceId query parameter. ### Retrieve call details by call ID - [GET /v2/projects/{projectId}/calls/{callId}](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/calls/getcallbyid.md): Retrieve detailed information about a specific call using its unique identifier. ### Patch an ongoing call by call ID - [PATCH /v2/projects/{projectId}/calls/{callId}](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/calls/patchcallbyid.md): Interact with an ongoing call by submitting a set of SVAML commands. Use this to force disconnect, play messages, bridge with another call, or perform other call control actions. ### Patch an ongoing call by session ID and call name - [PATCH /v2/projects/{projectId}/sessions/{sessionId}/calls/{callName}](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/calls/patchcallbysessionandname.md): Interact with an ongoing call identified by its session and call name by submitting a set of SVAML commands. Use this to force disconnect, play messages, bridge with another call, or perform other call control actions. ## Sessions A session represents a single interaction between a user and the Sinch Voice API. Sessions can be used to track the state of a call, including its duration, participants, and any associated metadata. ### Get a session details by the session ID - [GET /v2/projects/{projectId}/sessions/{sessionId}](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/sessions/getsessionbyid.md): Retrieve detailed information about a specific session, including all associated calls and their current states. Sessions represent the complete interaction lifecycle and can contain multiple related calls. ## Batches A batch represents a group of call sessions initiated together as a single operation. Batches are useful for scenarios like outbound campaigns, notifications, or any use case requiring multiple calls to be placed concurrently with controlled pacing. ### Key Features - **Rate limiting**: Control the maximum calls per second (CPS) to manage load and comply with carrier requirements - **TTL (Time-to-Live)**: Set a maximum time window for initiating queued calls - **Monitoring**: Track batch execution state including completed, failed, in-progress, and queued calls - **Cancellation**: Stop processing queued calls while allowing in-progress calls to complete ### Stop processing a batch of call sessions - [DELETE /v2/projects/{projectId}/batches/{batchId}](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/batches/stopbatchprocessing.md): Stop processing a batch of call sessions. This will prevent any queued calls in the batch from being initiated. Calls that are already in progress will not be affected and will continue until completion. ### Get a batch summary - [GET /v2/projects/{projectId}/batches/{batchId}](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/batches/getbatchcallsummary.md): Retrieve a summary of a batch call operation, including statistics on completed, failed, in-progress, and queued calls. This provides an overview of the batch execution state and individual call session states. ### Get batch details - [GET /v2/projects/{projectId}/batches/{batchId}/details](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/batches/getbatchdetails.md): Retrieve per-session details for a batch call operation, including the current state of each call session in the batch. Use this endpoint when individual session-level visibility is needed (for example, to inspect which sessions are QUEUED, IN_PROGRESS or COMPLETED). EXPIRED sessions are never returned because they were never initiated. ## Webhooks The Sinch Voice platform delivers real-time call event notifications to a configured webhook URL via HTTP POST requests. The receiving endpoint responds with [SVAML commands](/docs/voice-2.0/api-reference/svaml) that control the ongoing call flow. ## Request Format Webhook requests conform to the [CloudEvents 1.0](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md) specification using **HTTP binary content mode**: - CloudEvent metadata is carried as `ce-*` HTTP headers (see parameters below). - The request body contains only the event data payload (`call` object), encoded as `application/json`. ## When webhooks are triggered - **Incoming calls**: When a call arrives on a service configured with a webhook URL. Services using static SVAML behavior (`STATIC`) do not trigger this webhook. - **Call events**: When the service is configured with a webhook URL **and** the SVAML command does not have an `events` property defined. If the `events` property is present — even if empty — no webhook is triggered for that command's events. For example, a `dial` command with no `events` property will trigger a webhook when the call is answered; a `dial` command with `events: {}` will not. - **Custom events**: When a `webhook` SVAML command is executed explicitly during a call. ## Response The endpoint must return HTTP `200` with a JSON body containing SVAML commands to execute next, or an empty `commands` array to take no action. ## Timeouts and failover - Sinch enforces a **5-second response timeout**. Slow responses may affect call quality. - Webhook requests are **blocking**: execution of the call flow pauses until the endpoint responds, and the next command runs once a response has been received. - Webhook URLs are configured on the service via the [Services API](/docs/voice-2.0/api-reference/voice/services) or the [Dashboard](https://dashboard.sinch.com/voice/services). The `webhook` SVAML command carries its own `url` and `fallbackUrl` for mid-call events. ### What counts as a failure A delivery attempt has failed when: - The endpoint returns a non-successful status code. - The endpoint does not respond within the 5-second timeout. - Returned body does not contain proper SVAML commands. Because the call flow is blocked while waiting, a delivery that ends with a failure disconnects the call. This happens when the primary URL fails and no `fallbackUrl` is configured, or when both the primary URL and the `fallbackUrl` fail. ### Failover algorithm This section is the authoritative description of how the webhook URL is selected. When a `fallbackUrl` is configured: 1. Requests are sent to the primary `url`. 2. If a request to the primary URL fails, that same event is re-sent immediately to the `fallbackUrl`. The primary URL continues to be used for subsequent requests. 3. After several **consecutive failures** (exact number may vary) of the primary URL, the primary URL is bypassed and requests are sent only to the `fallbackUrl`. This avoids incurring the timeout on every request. 4. While the primary URL is bypassed it is retried once every **60 seconds**. The interval is counted from the last failure of the primary URL that triggers the bypass. Each unsuccessful retry restarts the 60-second clock. As soon as a retry succeeds the primary URL is restored and processing returns to step 1. If no `fallbackUrl` is configured, a failed request is not retried and the event is not delivered. ### Delivery guarantees Because a failed request is re-sent to the fallback URL, the same event can be delivered more than once — for example when the primary endpoint received and processed the request but responded too slowly. Webhook handlers should be idempotent and deduplicate on the `ce-id` and `ce-source` header pair. ### Call webhook - [POST call.webhook](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/webhooks/callwebhook.md): Receives webhook notifications for call events from the Voice Platform. ### Request signing Every webhook request is signed by the Voice Platform so that the receiving endpoint can verify that the request was sent by Sinch and was not altered in transit. The signature is carried in the Authorization header, using the service authentication scheme. The header value is the service identifier and the signature, separated by a colon: Authorization: service : | Element | Description | | --- | --- | | ` | Identifier of the service the webhook belongs to. Matches the serviceId segment of the ce-source header and the call.serviceId field of the request body. | | | Base64-encoded HMAC-SHA256 hash of the canonical request string, keyed with the service secret. | #### Signature signature = Base64( HMAC-SHA256( secretBytes, UTF8(stringToSign) ) ) secretBytes is the 16-byte binary value of the service secret, and the signed message is the UTF-8 encoding of stringToSign. The service secret is issued as a Base64 string, for example F5wrP9SKYU6w8sbZXkp7GA==. Base64-decoding it yields the 16 bytes of secretBytes. The decoded bytes are used as the HMAC key — signing with the characters of the Base64 string instead produces a different, invalid signature. #### Canonical string stringToSign is the concatenation of five parts. Each of the first four parts is terminated by a single line feed (\n); the last part is not followed by a line feed. POST {contentMd5} {contentType} x-timestamp:{timestamp} {path} | Part | Value | | --- | --- | | Method | The HTTP method, always POST for webhook requests. | | {contentMd5} | Base64( MD5( UTF8(body) ) ) — the Base64-encoded MD5 digest of the raw request body. Empty when the request carries no body. | | {contentType} | The full value of the Content-Type header, including its parameters, for example application/json; charset=utf-8. Empty when the request carries no body. | | {timestamp} | The verbatim value of the x-timestamp request header, an ISO 8601 UTC timestamp with seven fractional-second digits, for example 2026-04-01T12:00:00.0000000Z. The literal prefix x-timestamp: is part of the canonical string. | | {path} | The absolute path of the configured webhook URL, without scheme, host, query string or fragment, for example /voice-webhooks. | The MD5 digest acts as a checksum of the body inside the canonical string. The integrity and authenticity guarantee is provided by the HMAC-SHA256 signature computed over that string. The CloudEvents (ce-*) headers are not covered by the signature. #### Example A request delivered to https://example.com/voice-webhooks with the body json {"event":"call.incoming","call":{"callId":"01AN4Z07BY79KA1307SR9X4MV3"}} Content-Type: application/json; charset=utf-8 and x-timestamp: 2026-04-01T12:00:00.0000000Z produces the canonical string POST CH5/FnzqzRJ81QlTLGAhAw== application/json; charset=utf-8 x-timestamp:2026-04-01T12:00:00.0000000Z /voice-webhooks With the service secret F5wrP9SKYU6w8sbZXkp7GA==, the resulting header is Authorization: service a74b1566-0f18-4f8e-9c23-8e6b5df8fd3e:EWFtVTrykdhMTdyYSbn40GBJpf5UBeggO9T99sdwLyY= #### Verification 1. Split the Authorization header value into the service identifier and the signature. 2. Rebuild stringToSign from the received request, using the raw request body exactly as delivered, before any parsing, re-serialization or whitespace normalization. 3. Recompute the signature with the secret of the identified service and compare it to the received value using a constant-time comparison. 4. Reject the request when the two values differ. 5. Reject requests whose x-timestamp` lies outside an accepted clock-skew window, to limit replay of previously valid requests. ## Services Services represent sets of configuration values and groupings for managing calls, such as service profiles, routing rules, and project settings. Services can be created, updated, and deleted via the API to organize call flows and endpoints. Service is the way you can manage your voice calls. Each service has its own configuration, including webhook URLs, default caller IDs, and other settings that control how calls are handled. ### Default Services When a new project is created a default service is automatically generated under this project. A default cannot be deleted directly, in order to delete a default service you must first promote another service to be the default one. When performing some Voice API operations, you may choose not to specify a serviceId, in which case the default service will be used. If you have multiple services, you can specify which one to use by providing its serviceId in the request. **If your account was created before the release of the voice API v2**, you may not have a service created under your projects. In this case, you must create a new one and set it as the default before you can use the programmable voice product within this project. You can do this via the API or the Dashboard. This can be useful if customers want to point a group of numbers to a particular incoming call URL, or want to record all calls for one voice service but not for the other. ### Dashboard Voice services and their settings can be managed via the [Dashboard](https://dashboard.sinch.com/voice-v2/services). ### List all services of a project - [GET /v2/projects/{projectId}/services](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/services/listservices.md): Retrieve a list of voice services in the specified project. Optionally: - Filter services by partial match on name or description (filter) - Return only the default service (default=true) ### Create a new voice service - [POST /v2/projects/{projectId}/services](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/services/createservice.md): Creates a new voice service in the specified project. ### Retrieve a voice service by ID - [GET /v2/projects/{projectId}/services/{serviceId}](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/services/getservice.md): Retrieve the full details of a specific voice service by its serviceId. ### Update a voice service - [PATCH /v2/projects/{projectId}/services/{serviceId}](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/services/updateservice.md): Updates an existing service resource with the provided properties. Only the fields included in the request body will be modified; omitted fields remain unchanged. To set a service as the default for the project, include "isDefault": true in the request. Note that each project can have only one default service. Setting a new default will automatically remove the default status from the previously designated service. "isDefault": false is invalid and will not be accepted by the API. ### Delete a voice service by ID - [DELETE /v2/projects/{projectId}/services/{serviceId}](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/services/deleteservice.md): Deletes a service permanently. Important: The default service cannot be deleted. To delete the current default service, a different service must first be designated as the default using the PATCH endpoint. ## Payloads SVAML (Sinch Voice API Markup Language) is a JSON-based markup language used to define call flows and control the behavior of voice calls in the Sinch Voice API. It allows developers to specify commands that dictate how calls are handled, including dialing, playing messages, gathering input, and more. SVAML is used in various contexts within the Voice API, including: - **Call Creation**: When initiating outbound calls via the API. - **Webhooks**: When responding to call events with commands to control the ongoing call flow. - **Batch Calls**: When defining call flows for multiple calls in a batch operation. ### Describe the call flow from the SVAML payload - [POST /v2/projects/{projectId}/svaml/describe](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/payloads/describesvaml.md): This endpoint is useful for understanding the structure and flow of a SVAML payload without executing it. It provides a detailed description of the commands, events, and messages defined in the SVAML. ### Validate a SVAML payload - [POST /v2/projects/{projectId}/svaml/validate](https://developers.sinch.com/docs/voice-2.0/api-reference/voice/payloads/validatesvaml.md): This endpoint checks the structure and content of the SVAML commands to ensure they conform to the expected schema and rules. It can operate in different validation modes, such as strict or lenient, depending on the requirements.