# Instructions

Instructions allow your application to perform tasks during a call, such as play a message to participants given a particular locale, or starting a recording. The following instructions are available to use:

## playFiles

Plays Interactive Voice Response (IVR) files for the supported locale or SSML commands at the Sinch backend. An IVR message is played only on the caller's side.

Available to use in a response to an [Incoming Call Event](/docs/voice/api-reference/voice/callbacks/ice) callback, an [Answered Call Event](/docs/voice/api-reference/voice/callbacks/ace) callback, or a [Prompt Input Event](/docs/voice/api-reference/voice/callbacks/pie) callback.

**Example code**

**Schema**

```json
{
  "$ref": "#/components/schemas/svaml.instruction.playFiles",
  "components": {
    "schemas": {
      "svaml.instruction.playFiles": {
        "type": "object",
        "description": "Plays Interactive Voice Response (IVR) files for the supported locale or SSML commands at the Sinch backend. An IVR message is played only on the caller's side.",
        "required": [
          "name",
          "ids"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The `name` property. Must have the value `playFiles`.",
            "x-enumDescriptions": {
              "playFiles": "The `playFiles` instruction."
            },
            "enum": [
              "playFiles"
            ],
            "default": "playFiles"
          },
          "ids": {
            "type": "array",
            "description": "The IDs of the files which will be played. These can be a URL to a file, SSML commands using the `#ssml[]` element, or text using the `#tts[]` element.",
            "items": {
              "type": "string"
            },
            "example": [
              "#ssml[Thank you for calling Sinch!]"
            ]
          },
          "locale": {
            "type": "string",
            "description": "If using SSML or TTS, this is a required field. The voice and language you want to use for the text-to-speech message. This can either be defined by the ISO 639 locale and language code or by specifying a particular voice. Supported languages and voices are detailed [here](https://developers.sinch.com/docs/voice/api-reference/voice-locales).",
            "example": "en-US"
          }
        }
      }
    }
  }
}
```

## say

Plays a synthesized text-to-speech message to the end user. The message is provided in the text field.

Available to use in a response to an [Incoming Call Event](/docs/voice/api-reference/voice/callbacks/ice) callback, an [Answered Call Event](/docs/voice/api-reference/voice/callbacks/ace) callback, or a [Prompt Input Event](/docs/voice/api-reference/voice/callbacks/pie) callback.

**Example code**

**Schema**

```json
{
  "$ref": "#/components/schemas/svaml.instruction.say",
  "components": {
    "schemas": {
      "svaml.instruction.say": {
        "type": "object",
        "description": "Plays a synthesized text-to-speech message to the end user. The message is provided in the text field.",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The `name` property. Must have the value `say`.",
            "x-enumDescriptions": {
              "say": "The `say` instruction."
            },
            "enum": [
              "say"
            ],
            "default": "say"
          },
          "text": {
            "type": "string",
            "description": "Contains the message that will be spoken. Default maximum length is 600 characters. To change this limit, please contact support.",
            "example": "Hello, thank you for calling Sinch!"
          },
          "locale": {
            "type": "string",
            "description": "The voice and language you want to use for the text-to-speech message. This can either be defined by the ISO 639 locale and language code or by specifying a particular voice. Supported languages and voices are detailed [here](https://developers.sinch.com/docs/voice/api-reference/voice-locales).",
            "example": "en-US"
          }
        }
      }
    }
  }
}
```

## sendDtmf

Plays DTMF tones in the call.

Available to use in a response to an [Incoming Call Event](/docs/voice/api-reference/voice/callbacks/ice) callback or a [Prompt Input Event](/docs/voice/api-reference/voice/callbacks/pie) callback.

**Example code**

**Schema**

```json
{
  "$ref": "#/components/schemas/svaml.instruction.sendDtmf",
  "components": {
    "schemas": {
      "svaml.instruction.sendDtmf": {
        "type": "object",
        "description": "Plays DTMF tones in the call.",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The `name` property. Must have the value `sendDtmf`.",
            "x-enumDescriptions": {
              "sendDtmf": "The `sendDtmf` instruction."
            },
            "enum": [
              "sendDtmf"
            ],
            "default": "sendDtmf"
          },
          "value": {
            "type": "string",
            "description": "A string that determines the DTMF tones to play to the callee when the call is picked up.\nValid characters are: `0-9`, `#`, and `w`. `w` renders a 500ms pause. For example, the string `ww1234#w#`, plays a 1 second pause, the DTMF tones for `1`, `2`, `3`, `4`, and `#`, followed by a 500ms pause and finally the `#` tone.\nThis is useful if the callout destination requires a conference PIN code or an extension. If there is a calling party, it will hear progress while the DTMF is sent.",
            "example": "ww1234#w#"
          }
        }
      }
    }
  }
}
```

## setCookie

Creates a cookie for the call.

Available to use in a response to an [Incoming Call Event](/docs/voice/api-reference/voice/callbacks/ice) callback, an [Answered Call Event](/docs/voice/api-reference/voice/callbacks/ace) callback, or a [Prompt Input Event](/docs/voice/api-reference/voice/callbacks/pie) callback.

**Example code**

**Schema**

```json
{
  "$ref": "#/components/schemas/svaml.instruction.setCookie",
  "components": {
    "schemas": {
      "svaml.instruction.setCookie": {
        "type": "object",
        "required": [
          "name"
        ],
        "description": "Creates a cookie for the duration of the call.",
        "properties": {
          "name": {
            "type": "string",
            "description": "The `name` property. Must have the value `setCookie`.",
            "x-enumDescriptions": {
              "setCookie": "The `setCookie` instruction."
            },
            "enum": [
              "setCookie"
            ],
            "default": "setCookie"
          },
          "key": {
            "type": "string",
            "description": "The name of the cookie you want to set.",
            "example": "cookie_name"
          },
          "value": {
            "type": "string",
            "description": "The value of the cookie you want to set.",
            "example": "cookie_value"
          }
        }
      }
    }
  }
}
```

If you set a cookie in the response to an event (like “ice” or “ace”), it will be sent along in subsequent events in the session (like for instance “dice”). This can be used to keep simple application state during a call.

Limitations
The total size of cookie data (keys and values) may not exceed 1024 bytes.

## answer

Forces the callee to answer the call.

**Example code**

**Schema**

```json
{
  "$ref": "#/components/schemas/svaml.instruction.answer",
  "components": {
    "schemas": {
      "svaml.instruction.answer": {
        "type": "object",
        "description": "Forces the callee to answer the call.",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The `name` property. Must have the value `answer`.",
            "x-enumDescriptions": {
              "answer": "The `answer` instruction."
            },
            "enum": [
              "answer"
            ],
            "default": "answer"
          }
        }
      }
    }
  }
}
```

Normally, a call is “answered” when a callee picks up a call from a caller (for instance, when the callee picks up when doing a `connectPstn` action for an incoming call, see [connectPstn](/docs/voice/api-reference/svaml/actions#connectpstn)). This normally means that the call duration starts “ticking” on the caller's phone and that sound can flow in both directions.

This is normally handled automatically, but by adding the `answer` instruction, you can force the incoming call to be answered before the call is connected and a callee picks up. For instance, if you add the `answer` instruction in an ICE response with the `connectPstn` action, the caller's phone will pick up and its call duration will start ticking immediately (and not wait until the callee answers the call).

## startRecording

Starts recording the call.

Available to use in a response to an [Incoming Call Event](/docs/voice/api-reference/voice/callbacks/ice) callback, an [Answered Call Event](/docs/voice/api-reference/voice/callbacks/ace) callback, or a [Prompt Input Event](/docs/voice/api-reference/voice/callbacks/pie) callback.

**Example code**

**Schema**

```json
{
  "$ref": "#/components/schemas/svaml.instruction.startRecording",
  "components": {
    "schemas": {
      "svaml.instruction.startRecordingOptions": {
        "type": "object",
        "properties": {
          "destinationUrl": {
            "type": "string"
          },
          "credentials": {
            "type": "string"
          },
          "format": {
            "type": "string"
          },
          "notificationEvents": {
            "type": "boolean"
          },
          "transcriptionOptions": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "locale": {
                "type": "string"
              }
            }
          }
        }
      },
      "svaml.instruction.startRecording": {
        "type": "object",
        "description": "Starts a recording of the call.",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The `name` property. Must have the value `startRecording`.",
            "x-enumDescriptions": {
              "startRecording": "The `startRecording` instruction."
            },
            "enum": [
              "startRecording"
            ],
            "default": "startRecording"
          },
          "options": {
            "$ref": "#/components/schemas/svaml.instruction.startRecordingOptions"
          }
        }
      }
    }
  }
}
```

Note:
Recording calls when using the `connectMxp` action is not supported.

## stopRecording

Stops an ongoing recording for the current call.

Available to use in a response to a [Prompt Input Event](/docs/voice/api-reference/voice/callbacks/pie) callback.

**Example code**

**Schema**

```json
{
  "$ref": "#/components/schemas/svaml.instruction.stopRecording",
  "components": {
    "schemas": {
      "svaml.instruction.stopRecording": {
        "type": "object",
        "description": "Stops the recording of the call.",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The `name` property. Must have the value `stopRecording`.",
            "x-enumDescriptions": {
              "stopRecording": "The `stopRecording` instruction."
            },
            "enum": [
              "stopRecording"
            ],
            "default": "stopRecording"
          }
        }
      }
    }
  }
}
```