# Patch an ongoing call by session ID and call name

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.

Endpoint: PATCH /v2/projects/{projectId}/sessions/{sessionId}/calls/{callName}
Version: 2.0.58
Security: BasicAuth, SinchOAuth2

## Path parameters:

  - `projectId` (string, required)
    The ID of the project.

  - `sessionId` (string, required)
    The ID of the session.

  - `callName` (string, required)
    The name of the call leg within the session, as assigned by the callName property in the dial command.
    Example: "origin"

## Header parameters:

  - `Idempotency-Key` (string)
    Client-generated idempotency key to safely retry requests. The server uses this key to recognize retries of the same request. If a request with the same key is received within 10 minutes, the server returns the cached response from the original request. Using a random UUID (v4) is strongly recommended.

## Request fields (application/json):

  - `commands` (array, required) — one of (discriminator: command):
    An ordered list of SVAML v2 (Sinch Voice Application Markup Language) commands that describe a call flow. Commands are executed sequentially in the order they are defined.

Blocking vs. non-blocking: Some commands block execution until they complete (pause, webhook, menu, gotoMenu), while others return immediately and run in parallel (dial, messages, amd, answer, hangup, startRecording, stopRecording, bridgeCall, stopMessages). Each command's description specifies its behavior.

Nesting scope: Commands that appear inside event handlers (e.g., dial.events.onAnswer, messages.events.onFinish) form independent sequences and execute in their own context — they are not continuations of the parent sequence.
    - amd:
      - `command` (string, required)
        Command to run Answering Machine Detection on the call
      - `events` (object)
        SVAML commands to execute based on the answering machine detection result. These events define different call flows depending on whether a human, machine, beep, or unknown entity answers the call.
      - `events.onHuman` (array)
        SVAML commands to be executed when a human is detected
      - `events.onMachine` (array)
        SVAML commands to be executed when a machine is detected
      - `events.onBeep` (array)
        SVAML commands to be executed when a beep is detected
      - `events.onUnknown` (array)
        SVAML commands to be executed when an unknown event is detected
    - dial:
      - `command` (string, required)
        Command to initiate a new call
      - `to` (any, required) — one of (discriminator: type):
        Call destination - Phone Number or Stream URI
        - PHONE:
          - `type` (string, required)
            Routes the call to a phone number on the Public Switched Telephone Network (PSTN). The number must be in E.164 format.
          - `phone` (object, required)
          - `phone.number` (string, required)
            E.164 Phone number
        - SIP:
          - `type` (string, required)
            Routes the call to a SIP (Session Initiation Protocol) endpoint.
          - `sip` (object, required)
          - `sip.endpoint` (string, required)
            SIP URI of the destination endpoint. Both sip: (unencrypted) and sips: (TLS-encrypted) schemes are supported.
          - `sip.transport` (string)
            Transport protocol to use for the SIP signalling channel.

If omitted, the platform selects a default based on the URI scheme: UDP for sip: and TLS for sips:. Setting this explicitly overrides that default — for example, to force TCP for a sip: URI or to use TLS without switching to the sips: scheme.
            Enum: "UDP", "TCP", "TLS"
          - `sip.callHeaders` (array)
            Custom SIP headers to be sent in the call setup.
          - `sip.callHeaders.key` (string, required)
            Name of the SIP header.
            Example: "X-Correlation-Id"
          - `sip.callHeaders.value` (string)
            Value of the SIP header.
            Example: "12345"
        - STREAM:
          - `type` (string, required)
            Routes the call to a WebSocket stream endpoint for real-time audio processing.
          - `stream` (object, required)
          - `stream.endpoint` (string, required)
            WebSocket endpoint that will accept the incoming connection for real-time audio streaming. Must be a valid WebSocket URL using either ws:// or wss:// (recommended). The URL must be reachable from the public internet and capable of handling the negotiated stream protocol.
            Example: "wss://example.com"
          - `stream.streamOptions` (object)
          - `stream.streamOptions.version` (integer)
            Defines the version of the stream protocol.
            Example: 1
          - `stream.streamOptions.codec` (string)
            Defines the audio codec/format used for the stream audio payload.

Currently, only PCM is supported (uncompressed raw audio). Use sampleRate to configure the sampling rate for the stream.
          - `stream.streamOptions.sampleRate` (integer)
            Defines the audio sampling rate (Hz) used for the stream.

For calls that traverse the PSTN, audio is typically sampled at 8 kHz, so using a higher value will not improve perceived quality. 
Higher sample rates can be useful for non-PSTN scenarios (for example, SIP/streaming paths), but will increase bandwidth usage and processing load.
            Enum: 8000, 16000, 24000, 44100, 48000, 96000
          - `stream.callHeaders` (array)
            Custom headers to be sent in the call setup.
          - `stream.callHeaders.key` (string, required)
            Name of the header.
            Example: "headerKey"
          - `stream.callHeaders.value` (string)
            Value of the header.
            Example: "headerValue"
        - VOICE_RELAY:
          - `type` (string, required)
            Connects to the Voice Relay service to enable STT and TTS services...
          - `voiceRelay` (object, required)
          - `voiceRelay.endpoint` (string, required)
            URL to the server that will accept the web-socket request
            Example: "wss://acme.com/agent"
          - `voiceRelay.ttsVoice` (string, required)
            Name of the voice to be used when synthesizing speech. 

This is the default voice used, if no override voice is provided in the web-socket TTS message.

Supported voices include: Emma, Brian, and others. For a complete list of available voices and their characteristics, see the [Text-to-Speech Voices documentation](/docs/voice/api-reference/text-to-speech-voices).
            Example: "Emma"
          - `voiceRelay.sttLanguage` (string, required)
            BCP-47 language tag used for speech-to-text transcription of the inbound audio.

This value determines which language model is used for transcription.
            Example: "en-US"
          - `voiceRelay.enableInterruptions` (boolean)
            Allow "barge-in" during text-to-speech (TTS) playback.

When true, TTS playback is interrupted as soon as inbound speech is detected, unless the currently playing content is marked as uninterruptible.

When false, TTS playback continues uninterrupted, but an interruption signal is still sent over the WebSocket so the client application can choose to stop playback manually if needed.
            Example: true
          - `voiceRelay.callHeaders` (array)
            Custom headers to be sent in the call setup.
          - `voiceRelay.callHeaders.key` (string, required)
            Name of the header.
            Example: "headerKey"
          - `voiceRelay.callHeaders.value` (string)
            Value of the header.
            Example: "headerValue"
      - `callName` (string)
        Identifier for this call leg within the session. Must be unique across all active call legs in the session.

Other commands (e.g., hangup) can reference this name to target this specific leg.
        Example: "outgoing"
      - `from` (any) — one of (discriminator: type):
        Call origin - Phone Number or SIP endpoint
        - PHONE:
          - `type` (string, required)
            Routes the call to a phone number on the Public Switched Telephone Network (PSTN). The number must be in E.164 format.
          - `phone` (object, required)
          - `phone.number` (string, required)
            E.164 Phone number
        - SIP:
          - `type` (string, required)
            Indicates the call originated from a SIP (Session Initiation Protocol) endpoint.
          - `sip` (object, required)
          - `sip.endpoint` (string, required)
            SIP URI of the originating endpoint. Both sip: (unencrypted) and sips: (TLS-encrypted) schemes are supported.
          - `sip.displayName` (string)
            Display name presented to the called party as the caller identity. Transmitted as the display name part of the SIP From header (for example, Alice ).
            Example: "Alice"
      - `dialTimeoutDurationSeconds` (integer)
        Maximum time in seconds to wait for the call to be answered. If the timeout expires without an answer, the onTimeout event is triggered.
        Example: 15
      - `maxCallDurationSeconds` (integer)
        Maximum duration of the call in seconds. The call is terminated automatically when this limit is reached.
        Example: 3600
      - `events` (object)
        Webhook to handle call events, used when callBehaviors are set to WEBHOOK
      - `events.onAnswer` (array)
        SVAML commands to be executed when the call is answered
      - `events.onBusy` (array)
        SVAML commands to be executed when the call is busy
      - `events.onReject` (array)
        SVAML commands to be executed when the call is rejected
      - `events.onTimeout` (array)
        SVAML commands to be executed when the call is timed out
      - `events.onHangup` (array)
        SVAML commands to be executed when the call is hung up
      - `events.onFailure` (array)
        SVAML commands to be executed when the call fails
    - messages:
      - `command` (string, required)
        Command to play a message on the channel
      - `messages` (array, required) — one of (discriminator: type):
        Ordered list of messages to play.
        - SAY:
          - `type` (string, required)
            Text-to-speech message to be played during the call.
          - `say` (object, required)
          - `say.text` (string, required)
            The text to be synthesized into speech.

If format is TEXT (default), provide plain text.
If format is SSML, provide a valid SSML document (for example, ...).
            Example: "Hello world"
          - `say.voiceName` (string, required)
            The name of the voice to use for text-to-speech synthesis.

Supported voices include: Emma, Brian, and others. For a complete list of available voices and their characteristics, see the [Text-to-Speech Voices documentation](/docs/voice/api-reference/text-to-speech-voices).
            Example: "Emma"
          - `say.format` (string)
            Format of the message
            Enum: "TEXT", "SSML"
        - PLAY:
          - `type` (string, required)
            Audio file playback during the call.
          - `play` (object, required)
          - `play.url` (string, required)
            URL of the media to send
      - `messagesName` (string)
        Name of the message for identification and reference within the call session.

This name is used to uniquely identify the message and must be unique within the current call session.
This name can be referenced in other commands (e.g., stopMessages) to control this specific message.
        Example: "my-messages"
      - `events` (object)
        SVAML commands to execute based on message playback outcomes.
      - `events.onFinish` (array)
        Commands to execute when all messages in the sequence have finished playing.
    - stopMessages:
      - `command` (string, required)
        Command to stop playing messages
      - `messagesName` (string, required)
        Name of the message sequence to stop, as set by messagesName in the messages command.
      - `flags` (string)
        Controls how much of the sequence is stopped — only the currently playing message or all remaining queued messages.
        Enum: "ONLY_PLAYING", "ALL_FROM_NOW_ON"
    - webhook:
      - `command` (string, required)
        Command to trigger a mid-call webhook
      - `webhookName` (string, required)
        Name for this webhook event. When triggered, the webhook request's event property will contain this name prepended with call.webhook..

For example, if webhookName is set to "my.custom.event", the event will be delivered as "call.webhook.my.custom.event".
      - `url` (string, required)
        URL of the webhook endpoint to send the mid-call event to.
      - `fallbackUrl` (string)
        Fallback webhook URL used when the primary webhook URL fails.

A failed request is re-sent to this URL immediately. After repeated consecutive failures of the primary URL, requests are sent only here until the primary URL recovers.

See Timeouts and failover in the Webhooks section for the authoritative algorithm.
    - hangup:
      - `command` (string, required)
        Hangup call
      - `callName` (string)
        Name of the call leg to end, as set by callName in the dial command.

If omitted, the current call leg is ended.
        Example: "origin"
    - answer:
      - `command` (string, required)
        Answer call
    - pause:
      - `command` (string, required)
        Pause execution.
      - `durationMilliseconds` (integer, required)
        Duration of the pause in milliseconds.
        Example: 1000
    - startRecording:
      - `command` (string, required)
        Command to start recording on the channel
      - `recordingOptions` (object, required)
        Recording options for this recording.
      - `recordingOptions.destination` (string, required)
        Select target service to receive recorded and transcribed files
        Enum: "AWS", "GCP", "AZURE"
      - `recordingOptions.destinationUrl` (string, required)
        Destination URL for the recording.
        Example: "s3://voice-recordings-prod/calls"
      - `recordingOptions.credentials` (string, required)
        Credentials to third party storage.
        Example: "accessKeyId:secretAccessKey:eu-central-1"
      - `recordingOptions.format` (string)
        Audio format for this recording.
        Enum: "MP3", "WAV"
      - `recordingOptions.recordingType` (string)
        The type of recording to perform.
        Enum: "COMBINED", "INBOUND", "OUTBOUND"
      - `recordingOptions.transcriptionOptions` (object)
        Configuration for automatic speech-to-text transcription of the recording.
      - `recordingOptions.transcriptionOptions.isEnabled` (boolean, required)
        If true, the recording will be transcribed to text.
        Example: true
      - `recordingOptions.transcriptionOptions.locale` (string)
        Language code in BCP-47 format.
        Example: "en-US"
      - `recordingName` (string)
        Identifier for this recording within the session. Must be unique across active recordings in the session.

Other commands (e.g., stopRecording) reference this name to target a specific recording.

Setting the recording name is useful for stopping the recording using the stopRecording command. If name is not set, recording can only be stopped when the call is disconnected.
        Example: "my-recording"
      - `events` (object)
        SVAML commands to execute based on recording lifecycle outcomes.
      - `events.onFinish` (array)
        Commands to execute when the recording is successfully stopped. Note that this does not mean that the file is delivered to the configured destination yet.
      - `events.onFailure` (array)
        Commands to execute if the recording fails to start. If omitted, failures are silently ignored and the call flow continues.
    - stopRecording:
      - `command` (string, required)
        Command to stop recording on the channel
      - `recordingName` (string, required)
        Name of the recording to stop, as set by recordingName in the startRecording command.
        Example: "my-recording"
    - bridgeCall:
      - `command` (string, required)
        Command to add the call to a bridge
      - `bridgeName` (string, required)
        Name of the bridge to join. If no bridge with this name exists in the session, a new one is created automatically.
    - menu:
      - `command` (string, required)
        Executes menu-based input collection using the configured menu definitions.
      - `startMenu` (string, required)
        Name of the menu to execute first. Must match a key in menus.
      - `menus` (object, required)
        Map of menu definitions keyed by menu name.
    - gotoMenu:
      - `command` (string, required)
        Switch execution to another menu within the current menu context.
      - `menuName` (string, required)
        Name of the target menu to execute next. Must match a key in menus.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    URI that identifies the problem type and links to the corresponding error documentation.

  - `title` (string, required)
    Human-readable short summary of the problem type.

  - `detail` (string, required)
    Human-readable explanation of the specific problem occurrence.
    Example: "The request body is invalid or malformed."

  - `instance` (string, required)
    URI reference that identifies the specific occurrence of the problem (typically the request path).
    Example: "/v2/projects/5c5bf2b1-35ae-4825-ab89-457e07bb60e6/calls/01ARZ3NDEKTSV4RRFFQ69G5FAA"

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    URI that identifies the problem type and links to the corresponding error documentation.

  - `title` (string, required)
    Human-readable short summary of the problem type.

  - `detail` (string, required)
    Human-readable explanation of the specific problem occurrence.
    Example: "The token is missing, invalid, or has expired."

  - `instance` (string, required)
    URI reference that identifies the specific occurrence of the problem (typically the request path).
    Example: "/v2/projects/5c5bf2b1-35ae-4825-ab89-457e07bb60e6/calls/01ARZ3NDEKTSV4RRFFQ69G5FAA"

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    URI that identifies the problem type and links to the corresponding error documentation.

  - `title` (string, required)
    Human-readable short summary of the problem type.

  - `detail` (string, required)
    Human-readable explanation of the specific problem occurrence.
    Example: "The request was rejected."

  - `instance` (string, required)
    URI reference that identifies the specific occurrence of the problem (typically the request path).
    Example: "/v2/projects/5c5bf2b1-35ae-4825-ab89-457e07bb60e6/calls/01ARZ3NDEKTSV4RRFFQ69G5FAA"

## Response 404 fields (application/problem+json):

  - `type` (string, required)
    URI that identifies the problem type and links to the corresponding error documentation.

  - `title` (string, required)
    Human-readable short summary of the problem type.

  - `detail` (string, required)
    Human-readable explanation of the specific problem occurrence.
    Example: "The requested resource was not found."

  - `instance` (string, required)
    URI reference that identifies the specific occurrence of the problem (typically the request path).
    Example: "/v2/projects/5c5bf2b1-35ae-4825-ab89-457e07bb60e6/calls/01ARZ3NDEKTSV4RRFFQ69G5FAA"

## Response 429 fields (application/problem+json):

  - `type` (string, required)
    URI that identifies the problem type and links to the corresponding error documentation.

  - `title` (string, required)
    Human-readable short summary of the problem type.

  - `detail` (string, required)
    Human-readable explanation of the specific problem occurrence.
    Example: "Rate limit exceeded. Please slow down your request rate and retry after the indicated period."

  - `instance` (string, required)
    URI reference that identifies the specific occurrence of the problem (typically the request path).
    Example: "/v2/projects/5c5bf2b1-35ae-4825-ab89-457e07bb60e6/calls"

## Response 500 fields (application/problem+json):

  - `type` (string, required)
    URI that identifies the problem type and links to the corresponding error documentation.

  - `title` (string, required)
    Human-readable short summary of the problem type.

  - `detail` (string, required)
    Human-readable explanation of the specific problem occurrence.
    Example: "An unexpected error occurred on the server."

  - `instance` (string, required)
    URI reference that identifies the specific occurrence of the problem (typically the request path).
    Example: "/v2/projects/5c5bf2b1-35ae-4825-ab89-457e07bb60e6/calls/01ARZ3NDEKTSV4RRFFQ69G5FAA"


## Response 202 fields