right  Talk To Us!

play Action

Plays one or more media objects to the call. A media object can be some TTS text, a wav file or some digits (played as tones). When specifying a wav file, the media object can contain the name of a file in the Aculab media file store or the URL of a remote file.


The play properties are:

PropertyRequired/OptionalDefaultDescription
play list required - An array of media objects to play.
barge in optional true Whether a digit pressed during the play will interrupt the action.
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 that immediately precedes a run menu or get number action will skip that action's prompt if that also has barge in enabled.
Barge in is not supported on hold media and any of the conference participant nested plays.

The media object properties for TTS text are:

PropertyRequired/OptionalDefaultDescription
text to say required - The text to say. This must be in ASCII or UTF-8 format.
tts voice optional set in the service configuration The TTS voice to use. See the Text-To-Speech (TTS) page for a list of the available voices.

See Text-To-Speech (TTS) for advanced TTS features.

The media object properties for a media file in the Aculab media file store are:

PropertyRequired/OptionalDefaultDescription
file to play required - The wav file to play. This can be the file name or a web page request. If a file name is given the file must be present in the Aculab media file store.
decryption cipher optional null The cipher object to be used to decrypt the file to play, if it is encrypted. Cannot be used if file to play is a web page request.

The wav file encodings supported are:
  • G.711 A-law, 8 bits per sample
  • G.711 mu-law, 8 bits per sample
  • OKI ADPCM, 4 bit coding scheme
  • 8-bit unsigned linear coding, an unsigned value (0 to 255)
  • 16-bit signed linear coding, a signed value (-32768 to 32767)
  • 4-bit coding scheme standardised by the Interactive Multimedia Association (IMA)

The wav file must be mono at 8000 samples per second.


web page request defines how a specific web page is requested:

PropertyRequired/OptionalDefaultDescription
url required - The address of the web page to request.
method optional GET Only "GET" is supported when uploading a file. The HTTP request method to use when requesting the url.

If a web page request is given, the URL supplied should point to a page that will upload a wav file. The URL can be a relative or full path.

When the URL is accessed, Aculab Cloud will expect to receive audio data. No information will be sent to the URL, i.e., instance info will NOT be sent, and no actions can be returned from the URL. Aculab Cloud implements cacheing, so HTTP cache-control headers will be honoured. The maximum size of a file to be uploaded is five megabytes, which is about 10 minutes of 8 bit audio or 5 minutes of 16 bit audio. If your file has been cached and you need it to be refreshed immediately you can force a refresh by changing the url. An easy way to do this is to add a version number to your url. For example, if your URL is http://Badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1 it will be easy to change version to 2 and force a refresh.


The media object properties for digits are:

PropertyRequired/OptionalDefaultDescription
digits to play required - A string of digits to play. Valid digits are 0123456789ABCD#*.

Note that the DTMF digits you play may be eliminated by some parts of the telephone network. If you would like to play a general purpose beep to the far end, consider playing a wav file that contains a suitable tone.

decryption cipher contains the details of a cipher used to decrypt media files:

PropertyRequired/OptionalDescription
type required The cipher type, currently only "aescbc" (AES algorithm, CBC mode) is supported.

For the aescbc cipher the following properties must be supplied in the cipher object:

PropertyRequired/OptionalDescription
key required The cipher key as a string, either 128, 192 or 256 bits represented as 16, 24 or 32 hexadecimal bytes.
initialisation vector required The initialisation vector as a string, 128 bits represented as 16 hexadecimal bytes.

Encrypted media files need to be validated before they can be played back on a call. This occurs automatically as part of the Play action when the file is decrypted for playback. If you receive an error in your REST logs, 'Creating audio action: could not validate encrypted file to play: Format error' you should be sure to check the decryption details provided, as we are unable to validate the file format of an incorrectly decrypted file.

 See also: Simple Connect, Simple Connect To Conference, Simple Get Number, Simple Get Input, Simple Play, Simple Play With Interrupt, Simple Record, Simple Run Menu, Simple Run Speech Menu, Voice Broadcast, Voicemail

  • Examples:

    • Play some text:

      "play" :
{
    "play_list" :
    [
        {
            "text_to_say" : "Hello, good evening and welcome."
        }
    ]
}

    • Play a file from Aculab Cloud media file store:

      "play" :
{
    "play_list" :
    [
        {
            "file_to_play" : "welcome.wav"
        }
    ]
}

    • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file:

      "play" :
{
    "play_list" :
    [
        {
            "file_to_play" : "welcome_encrypted.wav",
            "decryption_cipher": 
            {
                "type" : "aescbc",
                "key" : "419EEA86DF595D3A431F43FAF57534C91F2DEB2E502A4C8CBA58AB5018BD1506",
                "initialisation_vector" : "D5A82A31F846443B9B85FAED9AB17570"
            }
        }
    ]
}

    • Play a file from the web:

      "play" :
{
    "play_list" :
    [
        {
            "file_to_play":
            { 
                "url" : "http://badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1" 
            }
        }
    ]
}

    • Play some digits:

      "play" :
{
    "play_list" :
    [
        {
            "digits_to_play" : "1234"
        }
    ]
}

    • Play a file, some text, some text using a specific voice followed by some digits, all 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" : false
}

  • API Reference:

    class Play : TelephonyAction

    Represents a play action.

    Constructors:

      Play();

    Members:

      static Play SayText(String textToSay);
  static Play SayText(String textToSay, String ttsVoice);
  static Play PlayFile(String fileToPlay);
  static Play PlayFile(String encryptedFileToPlay, Cipher decryptionCipher);
  static Play PlayFile(System.Uri fileToPlay);
  static Play PlayDigits(String digitsToPlay);

  AddText(String textToSay);
  AddText(String textToSay, String ttsVoice);
  AddFile(String fileToPlay);
  AddFile(String encryptedFileToPlay, Cipher decryptionCipher);
  AddFile(System.Uri fileToPlay);
  AddDigits(String digitsToPlay);

  bool BargeIn;
    class Cipher

    Represents a cipher to be used for file encryption/decryption.

    Members:

    String Type;
    class AesCbcCipher : Cipher

    Represents the AES cipher in CBC mode.

    Constructors:

    AesCbcCipher(byte[] key, byte[] initialisationVector);

    Members:

    byte[] InitialisationVector;

    Examples:

    • Play some text:

        actions.Add(Play.SayText("Hello, good evening and welcome."));

    • Play a file from Aculab Cloud media file store:

        actions.Add(Play.PlayFile("welcome.wav"));

    • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file:

        // Specify the 256 bit cipher to be used to decrypt the media file
  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 };

  Cipher decryptionCipher = new AesCbcCipher(key, initialisationVector);
  
  actions.Add(Play.PlayFile("welcome_encrypted.wav", decryptionCipher));

    • Play a file from the web:

        actions.Add(Play.PlayFile(new Uri("http://badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1")));

    • Play some digits:

        actions.Add(Play.PlayDigits("1234"));

    • Play a file, some text, some text using a different voice followed by some digits:

        Play 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.BargeIn = false;
  actions.Add(playAction);

  • API Reference:

    class Play Inherits TelephonyAction

    Represents a play action.

    Constructors:

    New()

    Members:

    Shared SayText(textToSay As String) As RestAPIWrapper.Play
Shared SayText(textToSay As String, ttsVoice As String) As RestAPIWrapper.Play
Shared PlayFile(fileToPlay As String) As RestAPIWrapper.Play
Shared PlayFile(encryptedFileToPlay As String, Cipher decryptionCipher) As RestAPIWrapper.Play
Shared PlayFile(fileToPlay As System.Uri) As RestAPIWrapper.Play
Shared PlayDigits(digitsToPlay As String) As RestAPIWrapper.Play

AddText(textToSay As String)
AddText(textToSay As String, ttsVoice As String)
AddFile(fileToPlay As String)
AddFile(encryptedFileToPlay As String, Cipher decryptionCipher)
AddFile(fileToPlay As System.Uri)
AddDigits(digitsToPlay As String)

BargeIn As Boolean
    class Cipher

    Represents a cipher to be used for file encryption/decryption.

    Members:

      Type As String
    class AesCbcCipher : Cipher

    Represents the AES cipher in CBC mode.

    Constructors:

      AesCbcCipher(ByVal key As Byte(), ByVal initialisationVector As Byte())

    Members:

      InitialisationVector As Byte()

    Examples:

    • Play some text:

      actions.Add(Play.SayText("Hello, good evening and welcome."))

    • Play a file from Aculab Cloud media file store:

      actions.Add(Play.PlayFile("welcome.wav"))

    • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file:

        ' Specify the 256 bit cipher to be used to decrypt the media file
  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, &H06 }
	
  Dim initialisationVector as Byte() = {
    &HD5, &HA8, &H2A, &H31, &HF8, &H46, &H44, &H3B,
    &H9B, &H85, &HFA, &HED, &H9A, &HB1, &H75, &H70 }

  Dim decryptionCipher As Cipher = New AesCbcCipher(key, initialisationVector)
  
  actions.Add(Play.PlayFile("welcome_encrypted.wav", decryptionCipher))

    • Play a file from the web:

      actions.Add(Play.PlayFile(New Uri("http://badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1")))

    • Play some digits:

      actions.Add(Play.PlayDigits("1234"))

    • Play a file, some text, some text using a different voice followed by some digits:

      Dim playAction As Play = 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.BargeIn = False
actions.Add(playAction)

  • API Reference:

    class Play extends TelephonyAction

    Represents a play action.

    Members:

    static Play.sayText(String textToSay);
static Play.sayText(String textToSay, String ttsVoice);
static Play.sayText(String textToSay, String ttsVoice, String ttsEngine);
static Play.playFile(String fileToPlay);
static Play.playFile(String encryptedFileToPlay, Cipher decryptionCipher);
static Play.playFile(URI fileToPlay);
static Play.playDigits(String digitsToPlay);

addText(String textToSay);
addText(String textToSay, String ttsVoice);
addText(String textToSay, String ttsVoice, String ttsEngine);
addFile(String fileToPlay);
addFile(String encryptedFileToPlay, Cipher decryptionCipher);
addFile(URI fileToPlay);
addDigits(String digitsToPlay);

setBargeIn(boolean enabled);
    class Cipher

    Represents a cipher to be used for file encryption/decryption.

    Members:

    String getType();
    class AesCbcCipher extends Cipher

    Represents the AES cipher in CBC mode.

    Constructors:

    AesCbcCipher(byte[] key, byte[] initialisationVector);

    Members:

    byte[] getInitialisationVector();
setInitialisationVector(byte[] iv);

    Examples:

    • Play some text:

      actions.add(Play.sayText("Hello, good evening and welcome."));

    • Play a file from Aculab Cloud media file store:

      actions.add(Play.playFile("welcome.wav"));

    • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file:

        // Specify the 256 bit cipher to be used to decrypt the media file
  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 };

  Cipher decryptionCipher = new AesCbcCipher(key, initialisationVector);
  
  actions.add(Play.playFile("welcome_encrypted.wav", decryptionCipher));

    • Play a file from the web:

      actions.add(Play.playFile(new URI("http://badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1")));

    • Play some digits:

      actions.add(Play.playDigits("1234"));

    • Play a file, some text, some text using a different voice followed by some digits:

      Play 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.setBargeIn(false);
actions.add(playAction);

  • API Reference:

    class Play

    Represents a play action.

    Constructors:

    Play(file_to_play=None, 
     digits_to_play=None, 
     text_to_say=None, 
     tts_voice=None, 
     barge_in=None,
     decryption_cipher=None)

    Members:

    def set_barge_in(barge_in)
def append_file(file_to_play, decryption_cipher=None)
def append_text(text_to_say, tts_voice=None)
def append_digits(digits_to_play)

    Examples:

    • Play some text:

      from aculab.telephony_rest_api import Actions, Play

my_actions = Actions('Usage example 1: Play.')

play_action = Play(text_to_say='Hello, good evening and welcome.')
my_actions.add(play_action)

response_body = my_actions.get_json()

    • Play a file:

      from aculab.telephony_rest_api import Actions, Play

my_actions = Actions('Usage example 2: Play.')

play_action = Play(file_to_play='welcome.wav')
my_actions.add(play_action)

response_body = my_actions.get_json()

    • Play a file and supply a cipher to decrypt it:

      from aculab.telephony_rest_api import Actions, Play, AESCBCCipher

my_actions = Actions('Usage example 3: Play.')

my_cipher = AESCBCCipher(key='407e4cc1a732cb2ac1b84395488f3322404e414ffeba8a8d692c034d608d9cc8', 
                         initialisation_vector='3bfd048ecaad5515f1ca7b9b58302c04')
play_action = Play(file_to_play='welcome.wav', decryption_cipher=my_cipher)
my_actions.add(play_action)

response_body = my_actions.get_json()

    • Play a remote file:

      from aculab.telephony_rest_api import Actions, Play

my_actions = Actions('Usage example 4: Play.')

# A WebPage object, see Redirect() for details
play_action = Play(file_to_play=WebPage(url='http://Badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1'))
my_actions.add(play_action)

response_body = my_actions.get_json()

    • Play some digits:

      from aculab.telephony_rest_api import Actions, Play

my_actions = Actions('Usage example 5: Play.')

play_action = Play(digits_to_play='1234')
my_actions.add(play_action)

response_body = my_actions.get_json()

    • Play a file, some text, some text using a different voice followed by some digits:

      from aculab.telephony_rest_api import Actions, Play

my_actions = Actions('Usage example 6: Play.')

play_action = Play(file_to_play='welcome.wav', barge_in=False)
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')

my_actions.add(play_action)

response_body = my_actions.get_json()

  • API Reference:

    The Play class

    Introduction

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

    Class synopsis

    class Play extends ActionBase {

    /* methods */
    public __construct()
    public static Play sayText(string $text_to_say, string $tts_voice = '')
    public static Play playFile(string $file_to_play, Cipher $cipher = null)
    public static Play playFileUrl(string $url_to_play, string $method = null)
    public static Play playDigits(string $digits_to_play)
    public void addText(string $text_to_say, string $tts_voice = '')
    public void addFile(string $file_to_play, Cipher $cipher = null)
    public void addFileUrl(string $url_to_play, string $method = null)
    public void addDigits(string $digits_to_play)
    public void setBargeIn(boolean $bargeIn)
}

    The Cipher class

    Introduction

    An abstract class to represent ciphers.

    Class synopsis

    abstract class Cipher {

    /* methods */
    public __construct(string $type)
}
    The AesCbcCipher class

    Introduction

    A class to represent a cipher using AES in CBC mode.

    Class synopsis


    $key and $initialisation_vector are strings of hexadecimal bytes. 
    class AesCbcCipher extends Cipher{

    /* methods */
    public __construct(string $key, string $initialisation_vector)
}

    Examples:

    • Play some text:

      $actions->add(Aculab\TelephonyRestAPI\Play::sayText('Hello, good evening and welcome.'));

    • Play a file from the media file store:

      $actions->add(Aculab\TelephonyRestAPI\Play::playFile('welcome.wav'));

    • Play an encrypted file from Aculab Cloud media file store, supplying the cipher required to decrypt the file:

      $cipher = new Aculab\TelephonyRestAPI\AesCbcCipher(
    "419EEA86DF595D3A431F43FAF57534C91F2DEB2E502A4C8CBA58AB5018BD1506",
    "D5A82A31F846443B9B85FAED9AB17570"
);
$actions->add(Aculab\TelephonyRestAPI\Play::playFile('welcome_encrypted.wav', $cipher));

    • Play a file from the web:

      $actions->add(Aculab\TelephonyRestAPI\Play::playFileUrl('http://badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1'));

    • Play some digits:

      $actions->add(Aculab\TelephonyRestAPI\Play::playDigits('1234'));

    • Play a file, some text, some text using a specific voice followed by some digits, all with barge in disabled:

      $play = new Aculab\TelephonyRestAPI\Play();
$play->addFile('welcome.wav');
$play->addText('Good morning.');
$play->addText('And now for something completely different.', 'English US Male Polly Joey');
$play->addDigits('1234');
$play->setBargeIn(false);
$actions->add($play);
  • Twitter
  • Linkedin
  • Facebook
  • Blog

Contact Aculab

+44 (0) 1908 273800 (UK)

+1 (781) 352 3550 (USA)

This email address is being protected from spambots. You need JavaScript enabled to view it.

This email address is being protected from spambots. You need JavaScript enabled to view it.

This email address is being protected from spambots. You need JavaScript enabled to view it.