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 callback, an Answered Call Event callback, or a Prompt Input Event callback.

Example code

{
  • "instructions": [
    • {
      • "name": "playFiles",
      • "ids": [
        • "[Welcome]"
        ],
      • "locale": "en-US"
      }
    ]
}

Schema

name
required
string
Default: "playFiles"

The name property. Must have the value playFiles.

ids
required
array

The IDs of the files which will be played. These can be a URL to a file or SSML commands.

locale
required
string

Specifies the locale. Uses the language code according to ISO 639, a dash (-), and a country code according to ISO 3166-1 alpha-2.

Enum: Description
arb

Arabic

cmn-CN

Chinese, Mandarin

da-DK

Danish

nl-NL

Dutch

en-AU

English, Australian

en-GB

English, British

en-IN

English, Indian

en-NZ

English, New Zealand

en-ZA

English, South African

en-US

English, US

en-GB-WLS

English, Welsh

fr-FR

French

fr-CA

French, Canadian

hi-IN

Hindi

de-DE

German

is-IS

Icelandic

it-IT

Italian

ja-JP

Japanese

ko-KR

Korean

nb-NO

Norwegian

pl-PL

Polish

pt-BR

Portuguese, Brazilian

pt-PT

Portuguese, European

ro-RO

Romanian

ru-RU

Russian

es-ES

Spanish, European

es-MX

Spanish, Mexican

es-US

Spanish, US

sv-SE

Swedish

tr-TR

Turkish

cy-GB

Welsh

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 callback, an Answered Call Event callback, or a Prompt Input Event callback.

Example code

{
  • "instructions": [
    • {
      • "name": "say",
      • "text": "Hello, this is a text-to-speech message.",
      • "locale": "en-US"
      }
    ]
}

Schema

name
string
Default: "say"

The name property. Must have the value say.

text
string

Contains the message that will be spoken. Default maximum length is 600 characters. To change this limit, please contact support.

locale
string

Specifies the locale. Uses the language code according to ISO 639, a dash (-), and a country code according to ISO 3166-1 alpha-2.

Enum: Description
arb

Arabic

cmn-CN

Chinese, Mandarin

da-DK

Danish

nl-NL

Dutch

en-AU

English, Australian

en-GB

English, British

en-IN

English, Indian

en-NZ

English, New Zealand

en-ZA

English, South African

en-US

English, US

en-GB-WLS

English, Welsh

fr-FR

French

fr-CA

French, Canadian

hi-IN

Hindi

de-DE

German

is-IS

Icelandic

it-IT

Italian

ja-JP

Japanese

ko-KR

Korean

nb-NO

Norwegian

pl-PL

Polish

pt-BR

Portuguese, Brazilian

pt-PT

Portuguese, European

ro-RO

Romanian

ru-RU

Russian

es-ES

Spanish, European

es-MX

Spanish, Mexican

es-US

Spanish, US

sv-SE

Swedish

tr-TR

Turkish

cy-GB

Welsh

sendDtmf

Plays DTMF tones in the call.

Available to use in a response to an Incoming Call Event callback, an Answered Call Event callback, or a Prompt Input Event callback.

Example code

{
  • "instructions": [
    • {
      • "name": "sendDtmf",
      • "value": "1234#"
      }
    ]
}

Schema

name
string
Default: "sendDtmf"

The name property. Must have the value sendDtmf.

value
string

A string that determines the DTMF tones to play to the callee when the call is picked up. Valid 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. This 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.

setCookie

Creates a cookie for the call.

Available to use in a response to an Incoming Call Event callback, an Answered Call Event callback, or a Prompt Input Event callback.

Example code

{
  • "instructions": [
    • {
      • "name": "setCookie",
      • "key": "cookie_name",
      • "value": "cookie_value"
      }
    ]
}

Schema

name
string
Default: "setCookie"

The name property. Must have the value setCookie.

key
string

The name of the cookie you want to set.

value
string

The value of the cookie you want to set.

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

{
  • "instructions": [
    • {
      • "name": "answer"
      }
    ]
}

Schema

name
string
Default: "answer"

The name property. Must have the value 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. 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 callback, an Answered Call Event callback, or a Prompt Input Event callback.

Example code

{
  • "instructions": [
    • {
      • "name": "startRecording",
      • "options": {
        • "destination": "s3://my-bucket/",
        • "credentials": "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY:eu-central-1",
        • "notificationEvents": true
        }
      }
    ]
}

Schema

name
string
Default: "startRecording"

The name property. Must have the value startRecording.

options
object

An object that specifies details about the recording. For more details, see Recording Options.

Note

startRecording with connectMxp is not supported Recording calls when using the action connectMxp is not supported.

stopRecording

Stops an ongoing recording for the current call.

Available to use in a response to a Prompt Input Event callback.

Example code

{
  • "instructions": [
    • {
      • "name": "stopRecording"
      }
    ]
}

Schema

name
string
Default: "stopRecording"

The name property. Must have the value stopRecording.

Was this page helpful?