play Action

Plays one or more play media objects to the call. A play media object can be some TTS text, a wav file or some digits (played as tones). When specifying a wav file, the play media object can contain the name of a file in the Aculab media file store or the URL of a remote file. Optionally, pressing any digit on the call or saying a word or short phrase can barge in and stop the play.

Note that speech recognition/transcription is a chargeable feature.

language wrappers and examples

The play properties are:

PropertyRequired/OptionalDefaultDescription
play listrequiredAn array of play media objects to play. Each element is either a TTS, media file or digits object.
barge in on digit
from API V2.0
optional true Whether a digit pressed during the play will barge in.
barge in on speech
from API V2.0
optional false Whether speech recognised during the play will barge in. Note that speech recognition/transcription is a chargeable feature.
barge in on speech options
from API V2.0
optional - A speech barge in options object. Ignored unless barge in on speech is enabled. Specifies the language for speech recognition and whether barge in should only occur if specific short phrases are recognised.

Remarks

Barge in on a single play action will skip all the remaining media in that play action.
Barge in on one play action will not affect a subsequent play action.
Barge in on a play action immediately preceding a run menu, run speech menu, get number, or get input action may result in that action returning the digit or speech that barged in.

The Play action does not generate an action result and does not report whether barge in occured or the cause of a barge in. If you are interested in barge in details you can use get input immediately after the play to identify if there was a barge in and the corresponding digit entered or phrase spoken. This is designed only to get words or short phrases that barged in. Longer phrases that barged in may be truncated.

Barge in is not supported on the connect to conference actions's hold media property or any of its conference participant plays.



  • Examples:

    • Play some text allowing barge in on a digit press:

      "play" :
      {
          "play_list" :
          [
              {
                  "text_to_say" : "Hello, good evening and welcome."
              }
          ]
      }
      
    • Play a file from your Aculab Cloud media file store disabling barge in on a digit press:

      "play" :
      {
          "play_list" :
          [
              {
                  "file_to_play" : "welcome.wav"
              }
          ],
      	"barge_in_on_digit" : false
      }
      
    • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file, allowing barge in on a digit press:

      "play" :
      {
          "play_list" :
          [
              {
                  "file_to_play" : "welcome_encrypted.wav",
                  "decryption_cipher": 
                  {
                      "type" : "aescbc",
                      "key" : "419EEA86DF595D3A431F43FAF57534C91F2DEB2E502A4C8CBA58AB5018BD1506",
                      "initialisation_vector" : "D5A82A31F846443B9B85FAED9AB17570"
                  }
              }
          ]
      }
      
    • Play a file from the web allowing barge in on a digit press:

      "play" :
      {
          "play_list" :
          [
              {
                  "file_to_play":
                  { 
                      "url" : "http://badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1" 
                  }
              }
          ]
      }
      
    • Play some digits allowing barge in on a digit press:

      "play" :
      {
          "play_list" :
          [
              {
                  "digits_to_play" : "1234"
              }
          ]
      }
      
    • Play some text, allowing barge in on any recognised words but not on a digit press:

      "play" :
      {
          "play_list" :
          [
              {
                  "text_to_say": "Hello, good evening and welcome."
              }
          ],
      	"barge_in_on_speech" : true,
      	"barge_in_on_digit" : false
      }
      
    • Play some text, allowing barge in on certain words and on a digit press:

      "play" :
      {
          "play_list" :
          [
              {
                  "text_to_say": "Hello, good evening and welcome."
              }
          ],
      	"barge_in_on_speech" : true,
      	"barge_in_on_speech_options" :
      	{
      		"barge_in_phrases" :
      		[
      			"cancel",
      			"stop"
      		]
      	}
      }
      
    • Play a file, some text, some text using a specific voice followed by some digits, with barge in disabled:

      "play" :
      {
          "play_list" :
          [
              {
                  "file_to_play" : "welcome.wav"
              },
              {
                  "text_to_say" : "Good morning."
              },
              {
                  "text_to_say" : "And now for something completely different.",
                  "tts_voice" : "English US Male Polly Joey"
              },
              {
                  "digits_to_play" : "1234"
              }
          ],
          "barge_in_on_digit" : false
      }
      
    • Play some private text allowing barge in on a digit press:

      "play" :
      {
          "play_list" :
          [
              {
                  "text_to_say" : "Your test results are negative.",
                  "text_is_private" : true
              }
          ]
      }
      
  • Play Class
    Namespace: Aculab.Cloud.RestAPIWrapper
    Assembly: Aculab.Cloud.RestAPIWrapper.dll

    An action to play one or more media objects to a call. A media object can be some TTS text, some digits (played as tones), or a wav file in the Aculab media file store or hosted on the web.

    • public class Play : TelephonyAction
      {
          // Static Members
          public static Play SayText(string textToSay, string ttsVoice = null, bool? textIsPrivate = null);
          public static Play PlayFile(string encryptedFileToPlay, Cipher decryptionCipher = null);
          public static Play PlayFile(Uri fileToPlay);
          public static Play PlayDigits(string digitsToPlay);
      
          // Constructors
          public Play();
      
          // Members
          public void AddText(string textToSay, string ttsVoice = null, bool? textIsPrivate = null);
          public void AddFile(string fileToPlay);
          public void AddFile(string encryptedFileToPlay, Cipher decryptionCipher);
          public void AddFile(Uri fileToPlay);
          public void AddDigits(string digitsToPlay);
          [Obsolete] public bool BargeIn;
          public bool BargeInOnDigit;
          public bool BargeInOnSpeech;
          public SpeechBargeInOptions BargeInOnSpeechOptions;
      }
      

      Examples:

      • Play some text allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        actions.Add(Play.SayText("Hello, good evening and welcome."));
        
      • Play a file from your Aculab Cloud media file store disabling barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.PlayFile("welcome.wav");
        play.BargeInOnDigit = false;
        actions.Add(play);
        
      • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file, allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        byte[] key = new byte[] {
            0x41, 0x9E, 0xEA, 0x86, 0xDF, 0x59, 0x5D, 0x3A,
            0x43, 0x1F, 0x43, 0xFA, 0xF5, 0x75, 0x34, 0xC9,
            0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
        0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06 };
        
        byte[] initialisationVector = new byte[] {
            0xD5, 0xA8, 0x2A, 0x31, 0xF8, 0x46, 0x44, 0x3B,
        0x9B, 0x85, 0xFA, 0xED, 0x9A, 0xB1, 0x75, 0x70 };
        
        var cipher = new AesCbcCipher(key, initialisationVector);
        var play = Play.PlayFile("welcome_encrypted.wav", cipher);
        actions.Add(play);
        
      • Play a file from the web allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.PlayFile("http://badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1");
        actions.Add(play);
        
      • Play some digits allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.PlayDigits("1234");
        
        actions.Add(play);
        
      • Play some text, allowing barge in on any recognised words but not on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.SayText("Hello, good evening and welcome.");
        play.BargeInOnSpeech = true;
        play.BargeInOnDigit = false;
        
        actions.Add(play);
        
      • Play some text, allowing barge in on certain words and on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var speechBargeInOptions = new SpeechBargeInOptions();
        speechBargeInOptions.BargeInPhrases.Add("cancel");
        speechBargeInOptions.BargeInPhrases.Add("stop");
        
        var play = Play.SayText("Hello, good evening and welcome.");
        play.BargeInOnSpeech = true;
        play.BargeInOnSpeechOptions = speechBargeInOptions;
        
        actions.Add(play);
        
      • Play a file, some text, some text using a specific voice followed by some digits, with barge in disabled:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.PlayFile("welcome.wav");
        play.AddText("Good morning.");
        play.AddText("And now for something completely different.", "English US Male Polly Joey");
        play.AddDigits("1234");
        play.BargeInOnDigit = false;
        
        actions.Add(play);
        
      • Say some private text allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        var play = Play.SayText("Your test results are negative.", textIsPrivate : true);
        actions.Add(play);
        
    • public class Play : TelephonyAction
      {
          // Static Members
          public static Play SayText(string textToSay, string ttsVoice = null, bool? textIsPrivate = null);
          public static Play PlayFile(string encryptedFileToPlay, Cipher decryptionCipher = null);
          public static Play PlayFile(Uri fileToPlay);
          public static Play PlayDigits(string digitsToPlay);
      
          // Constructors
          public Play();
      
          // Members
          public void AddText(string textToSay, string ttsVoice = null, bool? textIsPrivate = null);
          public void AddFile(string fileToPlay);
          public void AddFile(string encryptedFileToPlay, Cipher decryptionCipher);
          public void AddFile(Uri fileToPlay);
          public void AddDigits(string digitsToPlay);
          [Obsolete] public bool BargeIn;
          public bool BargeInOnDigit;
          public bool BargeInOnSpeech;
          public SpeechBargeInOptions BargeInOnSpeechOptions;
      }
      

      Examples:

      • Play some text allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        actions.Add(Play.SayText("Hello, good evening and welcome."));
        
      • Play a file from your Aculab Cloud media file store disabling barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.PlayFile("welcome.wav");
        play.BargeInOnDigit = false;
        actions.Add(play);
        
      • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file, allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        byte[] key = new byte[] {
            0x41, 0x9E, 0xEA, 0x86, 0xDF, 0x59, 0x5D, 0x3A,
            0x43, 0x1F, 0x43, 0xFA, 0xF5, 0x75, 0x34, 0xC9,
            0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
        0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06 };
        
        byte[] initialisationVector = new byte[] {
            0xD5, 0xA8, 0x2A, 0x31, 0xF8, 0x46, 0x44, 0x3B,
        0x9B, 0x85, 0xFA, 0xED, 0x9A, 0xB1, 0x75, 0x70 };
        
        var cipher = new AesCbcCipher(key, initialisationVector);
        var play = Play.PlayFile("welcome_encrypted.wav", cipher);
        actions.Add(play);
        
      • Play a file from the web allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.PlayFile("http://badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1");
        actions.Add(play);
        
      • Play some digits allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.PlayDigits("1234");
        
        actions.Add(play);
        
      • Play some text, allowing barge in on any recognised words but not on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.SayText("Hello, good evening and welcome.");
        play.BargeInOnSpeech = true;
        play.BargeInOnDigit = false;
        
        actions.Add(play);
        
      • Play some text, allowing barge in on certain words and on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var speechBargeInOptions = new SpeechBargeInOptions();
        speechBargeInOptions.BargeInPhrases.Add("cancel");
        speechBargeInOptions.BargeInPhrases.Add("stop");
        
        var play = Play.SayText("Hello, good evening and welcome.");
        play.BargeInOnSpeech = true;
        play.BargeInOnSpeechOptions = speechBargeInOptions;
        
        actions.Add(play);
        
      • Play a file, some text, some text using a specific voice followed by some digits, with barge in disabled:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.PlayFile("welcome.wav");
        play.AddText("Good morning.");
        play.AddText("And now for something completely different.", "English US Male Polly Joey");
        play.AddDigits("1234");
        play.BargeInOnDigit = false;
        
        actions.Add(play);
        
      • Say some private text allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        var play = Play.SayText("Your test results are negative.", textIsPrivate : true);
        actions.Add(play);
        
    • public class Play : TelephonyAction
      {
          // Static Members
          public static Play SayText(string textToSay, string ttsVoice = null, bool? textIsPrivate = null);
          public static Play PlayFile(string encryptedFileToPlay, Cipher decryptionCipher = null);
          public static Play PlayFile(Uri fileToPlay);
          public static Play PlayDigits(string digitsToPlay);
      
          // Constructors
          public Play();
      
          // Members
          public void AddText(string textToSay, string ttsVoice = null, bool? textIsPrivate = null);
          public void AddFile(string fileToPlay);
          public void AddFile(string encryptedFileToPlay, Cipher decryptionCipher);
          public void AddFile(Uri fileToPlay);
          public void AddDigits(string digitsToPlay);
          [Obsolete] public bool BargeIn;
          public bool BargeInOnDigit;
          public bool BargeInOnSpeech;
          public SpeechBargeInOptions BargeInOnSpeechOptions;
      }
      

      Examples:

      • Play some text allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        actions.Add(Play.SayText("Hello, good evening and welcome."));
        
      • Play a file from your Aculab Cloud media file store disabling barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.PlayFile("welcome.wav");
        play.BargeInOnDigit = false;
        actions.Add(play);
        
      • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file, allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        byte[] key = new byte[] {
            0x41, 0x9E, 0xEA, 0x86, 0xDF, 0x59, 0x5D, 0x3A,
            0x43, 0x1F, 0x43, 0xFA, 0xF5, 0x75, 0x34, 0xC9,
            0x1F, 0x2D, 0xEB, 0x2E, 0x50, 0x2A, 0x4C, 0x8C,
        0xBA, 0x58, 0xAB, 0x50, 0x18, 0xBD, 0x15, 0x06 };
        
        byte[] initialisationVector = new byte[] {
            0xD5, 0xA8, 0x2A, 0x31, 0xF8, 0x46, 0x44, 0x3B,
        0x9B, 0x85, 0xFA, 0xED, 0x9A, 0xB1, 0x75, 0x70 };
        
        var cipher = new AesCbcCipher(key, initialisationVector);
        var play = Play.PlayFile("welcome_encrypted.wav", cipher);
        actions.Add(play);
        
      • Play a file from the web allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.PlayFile("http://badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1");
        actions.Add(play);
        
      • Play some digits allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.PlayDigits("1234");
        
        actions.Add(play);
        
      • Play some text, allowing barge in on any recognised words but not on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.SayText("Hello, good evening and welcome.");
        play.BargeInOnSpeech = true;
        play.BargeInOnDigit = false;
        
        actions.Add(play);
        
      • Play some text, allowing barge in on certain words and on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var speechBargeInOptions = new SpeechBargeInOptions();
        speechBargeInOptions.BargeInPhrases.Add("cancel");
        speechBargeInOptions.BargeInPhrases.Add("stop");
        
        var play = Play.SayText("Hello, good evening and welcome.");
        play.BargeInOnSpeech = true;
        play.BargeInOnSpeechOptions = speechBargeInOptions;
        
        actions.Add(play);
        
      • Play a file, some text, some text using a specific voice followed by some digits, with barge in disabled:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        
        var play = Play.PlayFile("welcome.wav");
        play.AddText("Good morning.");
        play.AddText("And now for something completely different.", "English US Male Polly Joey");
        play.AddDigits("1234");
        play.BargeInOnDigit = false;
        
        actions.Add(play);
        
      • Say some private text allowing barge in on a digit press:

        List<TelephonyAction> actions = new List<TelephonyAction>();
        var play = Play.SayText("Your test results are negative.", textIsPrivate : true);
        actions.Add(play);
        
  • Play Class
    Namespace: Aculab.Cloud.RestAPIWrapper
    Assembly: Aculab.Cloud.RestAPIWrapper.dll

    An action to play one or more media objects to a call. A media object can be some TTS text, some digits (played as tones), or a wav file in the Aculab media file store or hosted on the web.

    • Public Class Play
          Inherits TelephonyAction
      
          ' Shared Members
          Public Static Function SayText(textToSay As String, Optional ttsVoice As String = Nothing, Optional textIsPrivate As Bool? = Nothing) As Play
          Public Static Function PlayFile(encryptedFileToPlay As String, Optional decryptionCipher As Cipher = Nothing) As Play
          Public Static Function PlayFile(fileToPlay As Uri) As Play
          Public Static Function PlayDigits(digitsToPlay As String) As Play
      
          ' Constructors
          Public Sub New ()
      
          ' Members
          Public Function AddText(textToSay As String, Optional ttsVoice As String = Nothing, Optional textIsPrivate As Bool? = Nothing) As Void
          Public Function AddFile(fileToPlay As String) As Void
          Public Function AddFile(encryptedFileToPlay As String, decryptionCipher As Cipher) As Void
          Public Function AddFile(fileToPlay As Uri) As Void
          Public Function AddDigits(digitsToPlay As String) As Void
          [Obsolete] Public Property BargeIn As Bool
          Public Property BargeInOnDigit As Bool
          Public Property BargeInOnSpeech As Bool
          Public Property BargeInOnSpeechOptions As Speechbargeinoptions
      End Class
      

      Examples:

      • Play some text allowing barge in on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        actions.Add(Play.SayText("Hello, good evening and welcome."))
        
      • Play a file from your Aculab Cloud media file store disabling barge in on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim playAction = Play.PlayFile("welcome.wav")
        playAction.BargeInOnDigit = False
        actions.Add(playAction)
        
      • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file, allowing barge in on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim key As Byte() = { _
            &H41, &H9E, &HEA, &H86, &HDF, &H59, &H5D, &H3A, _
            &H43, &H1F, &H43, &HFA, &HF5, &H75, &H34, &HC9, _
            &H1F, &H2D, &HEB, &H2E, &H50, &H2A, &H4C, &H8C, _
        &HBA, &H58, &HAB, &H50, &H18, &HBD, &H15, &H6}
        
        Dim initialisationVector As Byte() = { _
            &HD5, &HA8, &H2A, &H31, &HF8, &H46, &H44, &H3B, _
        &H9B, &H85, &HFA, &HED, &H9A, &HB1, &H75, &H70}
        
        Dim cipher = New AesCbcCipher(key, initialisationVector)
        Dim playAction = Play.PlayFile("welcome_encrypted.wav", cipher)
        actions.Add(playAction)
        
      • Play a file from the web allowing barge in on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim playAction = Play.PlayFile("http://badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1")
        actions.Add(playAction)
        
      • Play some digits allowing barge in on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim playAction = Play.PlayDigits("1234")
        
        actions.Add(playAction)
        
      • Play some text, allowing barge in on any recognised words but not on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim playAction = Play.SayText("Hello, good evening and welcome.")
        playAction.BargeInOnSpeech = True
        playAction.BargeInOnDigit = False
        
        actions.Add(playAction)
        
      • Play some text, allowing barge in on certain words and on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim speechBargeInOptions = New SpeechBargeInOptions()
        speechBargeInOptions.BargeInPhrases.Add("cancel")
        speechBargeInOptions.BargeInPhrases.Add("stop")
        
        Dim playAction = Play.SayText("Hello, good evening and welcome.")
        playAction.BargeInOnSpeech = True
        playAction.BargeInOnSpeechOptions = speechBargeInOptions
        
        actions.Add(playAction)
        
      • Play a file, some text, some text using a specific voice followed by some digits, with barge in disabled:

        Dim actions = New List(Of TelephonyAction)
        
        Dim playAction = Play.PlayFile("welcome.wav")
        playAction.AddText("Good morning.")
        playAction.AddText("And now for something completely different.", "English US Male Polly Joey")
        playAction.AddDigits("1234")
        playAction.BargeInOnDigit = False
        
        actions.Add(playAction)
        
      • Say some private text allowing barge in on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim playAction = Play.SayText("Your test results are negative.", textIsPrivate:=True)
        
        actions.Add(playAction)
        
    • Public Class Play
          Inherits TelephonyAction
      
          ' Shared Members
          Public Static Function SayText(textToSay As String, Optional ttsVoice As String = Nothing, Optional textIsPrivate As Bool? = Nothing) As Play
          Public Static Function PlayFile(encryptedFileToPlay As String, Optional decryptionCipher As Cipher = Nothing) As Play
          Public Static Function PlayFile(fileToPlay As Uri) As Play
          Public Static Function PlayDigits(digitsToPlay As String) As Play
      
          ' Constructors
          Public Sub New ()
      
          ' Members
          Public Function AddText(textToSay As String, Optional ttsVoice As String = Nothing, Optional textIsPrivate As Bool? = Nothing) As Void
          Public Function AddFile(fileToPlay As String) As Void
          Public Function AddFile(encryptedFileToPlay As String, decryptionCipher As Cipher) As Void
          Public Function AddFile(fileToPlay As Uri) As Void
          Public Function AddDigits(digitsToPlay As String) As Void
          [Obsolete] Public Property BargeIn As Bool
          Public Property BargeInOnDigit As Bool
          Public Property BargeInOnSpeech As Bool
          Public Property BargeInOnSpeechOptions As Speechbargeinoptions
      End Class
      

      Examples:

      • Play some text allowing barge in on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        actions.Add(Play.SayText("Hello, good evening and welcome."))
        
      • Play a file from your Aculab Cloud media file store disabling barge in on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim playAction = Play.PlayFile("welcome.wav")
        playAction.BargeInOnDigit = False
        actions.Add(playAction)
        
      • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file, allowing barge in on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim key As Byte() = { _
            &H41, &H9E, &HEA, &H86, &HDF, &H59, &H5D, &H3A, _
            &H43, &H1F, &H43, &HFA, &HF5, &H75, &H34, &HC9, _
            &H1F, &H2D, &HEB, &H2E, &H50, &H2A, &H4C, &H8C, _
        &HBA, &H58, &HAB, &H50, &H18, &HBD, &H15, &H6}
        
        Dim initialisationVector As Byte() = { _
            &HD5, &HA8, &H2A, &H31, &HF8, &H46, &H44, &H3B, _
        &H9B, &H85, &HFA, &HED, &H9A, &HB1, &H75, &H70}
        
        Dim cipher = New AesCbcCipher(key, initialisationVector)
        Dim playAction = Play.PlayFile("welcome_encrypted.wav", cipher)
        actions.Add(playAction)
        
      • Play a file from the web allowing barge in on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim playAction = Play.PlayFile("http://badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1")
        actions.Add(playAction)
        
      • Play some digits allowing barge in on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim playAction = Play.PlayDigits("1234")
        
        actions.Add(playAction)
        
      • Play some text, allowing barge in on any recognised words but not on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim playAction = Play.SayText("Hello, good evening and welcome.")
        playAction.BargeInOnSpeech = True
        playAction.BargeInOnDigit = False
        
        actions.Add(playAction)
        
      • Play some text, allowing barge in on certain words and on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim speechBargeInOptions = New SpeechBargeInOptions()
        speechBargeInOptions.BargeInPhrases.Add("cancel")
        speechBargeInOptions.BargeInPhrases.Add("stop")
        
        Dim playAction = Play.SayText("Hello, good evening and welcome.")
        playAction.BargeInOnSpeech = True
        playAction.BargeInOnSpeechOptions = speechBargeInOptions
        
        actions.Add(playAction)
        
      • Play a file, some text, some text using a specific voice followed by some digits, with barge in disabled:

        Dim actions = New List(Of TelephonyAction)
        
        Dim playAction = Play.PlayFile("welcome.wav")
        playAction.AddText("Good morning.")
        playAction.AddText("And now for something completely different.", "English US Male Polly Joey")
        playAction.AddDigits("1234")
        playAction.BargeInOnDigit = False
        
        actions.Add(playAction)
        
      • Say some private text allowing barge in on a digit press:

        Dim actions = New List(Of TelephonyAction)
        
        Dim playAction = Play.SayText("Your test results are negative.", textIsPrivate:=True)
        
        actions.Add(playAction)
        
  • class Play extends TelephonyAction

    Represents a play action.

    Class synopsis:

    // Constructors:
    public Play()
    
    // Static members:
    static public Play sayText(String textToSay)
    static public Play sayText(String textToSay, String ttsVoice)
    static public Play sayText(String textToSay, String ttsVoice, boolean textIsPrivate)
    static public Play playFile(String fileToPlay)
    static public Play playFile(String encryptedFileToPlay, Cipher decryptionCipher)
    static public Play playFile(URI fileToPlay)
    static public Play playFile(WebPageRequest fileToPlay)
    static public Play playDigits(String digitsToPlay)
    
    // Members:
    public void addText(String textToSay)
    public void addText(String textToSay, String ttsVoice)
    public void addText(String textToSay, String ttsVoice, boolean textIsPrivate)
    public void addFile(String fileToPlay)
    public void addFile(String encryptedFileToPlay, Cipher decryptionCipher)
    public void addFile(URI fileToPlay)
    public void addFile(WebPageRequest fileToPlay)
    public void addDigits(String digitsToPlay)
    public void setBargeInOnDigit(boolean enabled)
    public void setBargeInOnSpeech(boolean enabled)
    public void setBargeInOnSpeechOptions(SpeechBargeInOptions options)
    

    Examples:

    • Play some text allowing barge in on a digit press:

      List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
      
      Play playAction = Play.sayText("Hello, good evening and welcome.");
      
      actions.add(playAction);
      
    • Play a file from your Aculab Cloud media file store disabling barge in on a digit press:

      List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
      
      Play playAction = Play.playFile("welcome.wav");
      playAction.setBargeInOnDigit(false);
      
      actions.add(playAction);
      
    • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file, allowing barge in on a digit press:

      //Specify the 256 bit cipher to be used to decrypt the media file
      List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
      
      byte[] key = new byte[] {
          (byte)0x41, (byte)0x9E, (byte)0xEA, (byte)0x86, (byte)0xDF, (byte)0x59, (byte)0x5D, (byte)0x3A,
          (byte)0x43, (byte)0x1F, (byte)0x43, (byte)0xFA, (byte)0xF5, (byte)0x75, (byte)0x34, (byte)0xC9,
          (byte)0x1F, (byte)0x2D, (byte)0xEB, (byte)0x2E, (byte)0x50, (byte)0x2A, (byte)0x4C, (byte)0x8C,
          (byte)0xBA, (byte)0x58, (byte)0xAB, (byte)0x50, (byte)0x18, (byte)0xBD, (byte)0x15, (byte)0x06 };
                        
      byte[] initialisationVector = new byte[] {
          (byte)0xD5, (byte)0xA8, (byte)0x2A, (byte)0x31, (byte)0xF8, (byte)0x46, (byte)0x44, (byte)0x3B,
          (byte)0x9B, (byte)0x85, (byte)0xFA, (byte)0xED, (byte)0x9A, (byte)0xB1, (byte)0x75, (byte)0x70 };
      
      Cipher decryptionCipher = new AesCbcCipher(key, initialisationVector);
      Play playAction = Play.playFile("welcome_encrypted.wav", decryptionCipher);
      
      actions.add(playAction);
      
    • Play a file from the web allowing barge in on a digit press:

      List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
      
      Play playAction = Play.playFile(new URI("http://badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1"));
      
      actions.add(playAction);
      
    • Play some digits allowing barge in on a digit press:

      List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
      
      Play playAction = Play.playDigits("1234");
      
      actions.add(playAction);
      
    • Play some text, allowing barge in on any recognised words but not on a digit press:

      List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
      
      Play playAction = Play.sayText("Hello, good evening and welcome.");
      playAction.setBargeInOnSpeech(true);
      playAction.setBargeInOnDigit(false);
      
      actions.add(playAction);
      
    • Play some text, allowing barge in on certain words and on a digit press:

      List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
      
      List<String> phrases = new ArrayList<String>();
      phrases.add("cancel");
      phrases.add("stop");
      SpeechBargeInOptions options = new SpeechBargeInOptions();
      options.setBargeInPhrases(phrases);
      
      Play playAction = Play.sayText("Hello, good evening and welcome.");
      playAction.setBargeInOnSpeech(true);
      playAction.setBargeInOnSpeechOptions(options);
      
      actions.add(playAction);
      
    • Play a file, some text, some text using a specific voice followed by some digits, with barge in disabled:

      List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
      
      Play playAction = new Play();
      playAction.addFile("welcome.wav");
      playAction.addText("Good morning.");
      playAction.addText("And now for something completely different.", "English US Male Polly Joey");
      playAction.addDigits("1234");
      playAction.setBargeInOnDigit(false);
      
      actions.add(playAction);
      
    • Play some private text allowing barge in on a digit press:

      List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
      
      Play playAction = Play.sayText("Your test results are negative.", null, true);
      
      actions.add(playAction);
      
  • class Play

    Represents a play action.

    Class synopsis:

    # Play object:
    Play(file_to_play=None,
         digits_to_play=None,
         text_to_say=None,
         tts_voice=None,
         barge_in_on_digit=None,
         decryption_cipher=None,
         text_is_private=None)
    
    # Instance methods:
    Play.set_barge_in_on_digit(barge_in_on_digit)
    Play.set_barge_in_on_speech(barge_in_on_speech)
    Play.set_barge_in_on_speech_options(barge_in_on_speech_options)
    Play.append_file(file_to_play, decryption_cipher=None)
    Play.append_text(text_to_say, tts_voice=None, text_is_private=None)
    Play.append_digits(digits_to_play)
    

    Examples:

    • Play some text allowing barge in on a digit press:

      # Create a list of actions that will be passed to the TelephonyResponse constructor
      list_of_actions = []
      
      play_action = Play(text_to_say='Hello, good evening and welcome.')
      
      list_of_actions.append(play_action)
      
    • Play a file from your Aculab Cloud media file store disabling barge in on a digit press:

      # Create a list of actions that will be passed to the TelephonyResponse constructor
      list_of_actions = []
      
      play_action = Play(file_to_play='welcome.wav')
      play_action.set_barge_in_on_digit(False)
      
      list_of_actions.append(play_action)
      
    • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file, allowing barge in on a digit press:

      # Create a list of actions that will be passed to the TelephonyResponse constructor
      list_of_actions = []
      
      my_cipher = AESCBCCipher(key='419EEA86DF595D3A431F43FAF57534C91F2DEB2E502A4C8CBA58AB5018BD1506', 
                               initialisation_vector='D5A82A31F846443B9B85FAED9AB17570')
      play_action = Play(file_to_play='welcome.wav', decryption_cipher=my_cipher)
      
      list_of_actions.append(play_action)
      
    • Play a file from the web allowing barge in on a digit press:

      # Create a list of actions that will be passed to the TelephonyResponse constructor
      list_of_actions = []
      
      play_action = Play(file_to_play=WebPage(url='http://Badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1'))
      
      list_of_actions.append(play_action)
      
    • Play some digits allowing barge in on a digit press:

      # Create a list of actions that will be passed to the TelephonyResponse constructor
      list_of_actions = []
      
      play_action = Play(digits_to_play='1234')
      
      list_of_actions.append(play_action)
      
    • Play some text, allowing barge in on any recognised words but not on a digit press:

      # Create a list of actions that will be passed to the TelephonyResponse constructor
      list_of_actions = []
      
      play_action = Play(text_to_say='Hello, good evening and welcome.')
      play_action.set_barge_in_on_speech(True)
      play_action.set_barge_in_on_digit(False)
      
      list_of_actions.append(play_action)
      
    • Play some text, allowing barge in on certain words and on a digit press:

      # Create a list of actions that will be passed to the TelephonyResponse constructor
      list_of_actions = []
      
      speech_barge_in_opts = SpeechBargeInOptions()
      speech_barge_in_opts.set_barge_in_phrases(["cancel","stop"])
      
      play_action = Play(text_to_say='Hello, good evening and welcome.')
      play_action.set_barge_in_on_speech(True)
      play_action.set_barge_in_on_speech_options(speech_barge_in_opts)
      
      list_of_actions.append(play_action)
      
    • Play a file, some text, some text using a specific voice followed by some digits, with barge in disabled:

      # Create a list of actions that will be passed to the TelephonyResponse constructor
      list_of_actions = []
      
      play_action = Play(file_to_play='welcome.wav')
      play_action.append_text(text_to_say='Good morning.')
      play_action.append_text(text_to_say='And now for something completely different.', 
                              tts_voice='English US Male Polly Joey')
      play_action.append_digits(digits_to_play='1234')
      play_action.set_barge_in_on_digit(False)
      
      list_of_actions.append(play_action)
      
    • Play some private text allowing barge in on a digit press:

      # Create a list of actions that will be passed to the TelephonyResponse constructor
      list_of_actions = []
      
      play_action = Play(text_to_say='Your test results are negative.', text_is_private=True)
      
      list_of_actions.append(play_action)
      
  • The Play class

    Introduction

    Represents a list of text to say, files to play or digit tones to generate.

    Class synopsis

    class Play extends ActionBase {
    
        /* methods */
        public __construct()
        public self addText(string $text_to_say, string $tts_voice = '', boolean $text_is_private = null)
        public static Play sayText(
            string $text_to_say,
            string $tts_voice = '',
            boolean $text_is_private = null
        )
        public self addFile(string $file_to_play, Cipher $cipher = null)
        public static Play playFile(string $file_to_play, Cipher $cipher = null)
        public self addFileUrl(WebPageRequest|string $url_to_play, string $method = null)
        public static Play playFileUrl(WebPageRequest|string $url_to_play, string $method = null)
        public self addDigits(string $digits_to_play)
        public static Play playDigits(string $digits_to_play)
        public self setBargeInOnDigit(boolean $barge_in_on_digit)
        public self setBargeInOnSpeech(boolean $barge_in_on_speech)
        public self setBargeInOnSpeechOptions(SpeechBargeInOptions $speech_barge_in_options)
    }
    

    Examples:

    • Play some text allowing barge in on a digit press:

      $response->addAction(\Aculab\TelephonyRestAPI\Play::sayText('Hello, good evening and welcome.'));
      
    • Play a file from your Aculab Cloud media file store disabling barge in on a digit press:

      $play = \Aculab\TelephonyRestAPI\Play::playFile('welcome.wav');
      $play->setBargeInOnDigit(false);
      $response->addAction($play);
      
    • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file, allowing barge in on a digit press:

      $cipher = new \Aculab\TelephonyRestAPI\AesCbcCipher(
          "419EEA86DF595D3A431F43FAF57534C91F2DEB2E502A4C8CBA58AB5018BD1506",
          "D5A82A31F846443B9B85FAED9AB17570"
      );
      $response->addAction(\Aculab\TelephonyRestAPI\Play::playFile('welcome_encrypted.wav', $cipher));
      
    • Play a file from the web allowing barge in on a digit press:

      $response->addAction(\Aculab\TelephonyRestAPI\Play::playFileUrl('http://badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1'));
      
    • Play some digits allowing barge in on a digit press:

      $response->addAction(\Aculab\TelephonyRestAPI\Play::playDigits('1234'));
      
    • Play some text, allowing barge in on any recognised words but not on a digit press:

      $play = \Aculab\TelephonyRestAPI\Play::sayText('Hello, good evening and welcome.');
      $play->setBargeInOnSpeech(true)
          ->setBargeInOnDigit(false);
      
      $response->addAction($play);
      
    • Play some text, allowing barge in on certain words and on a digit press:

      $options = new \Aculab\TelephonyRestAPI\SpeechBargeInOptions();
      $options->setBargeInPhrases(["cancel", "stop"]);
      
      $play = \Aculab\TelephonyRestAPI\Play::sayText('Hello, good evening and welcome.');
      $play->setBargeInOnSpeech(true)
          ->setBargeInOnSpeechOptions($options);
      
      $response->addAction($play);
      
    • Play a file, some text, some text using a specific voice followed by some digits, with barge in disabled:

      $play = new \Aculab\TelephonyRestAPI\Play();
      $play->addFile('welcome.wav')
          ->addText('Good morning.')
          ->addText('And now for something completely different.', 'English US Male Polly Joey')
          ->addDigits('1234')
          ->setBargeInOnDigit(false);
      $response->addAction($play);
      
    • Play some private text allowing barge in on a digit press:

      $response->addAction(\Aculab\TelephonyRestAPI\Play::sayText('Your test results are negative.', '', true));