Playing audio files

At any stage of the conversation the bot can play a pre-recorded audio file to the user.

The audio file should be located on a web server (URL) that is accessible to VoiceAI Connect, and should be in one of the supported formats.

How do I use it?

For playing a pre-recorded audio file, the bot should send a playURL event.

See Sending activities page for instructions on how to send events using your bot framework.

The URL of audio file should be specified on the playUrlUrl parameter.

When handling the event, VoiceAI Connect will issue an HTTP GET request to retrieve the audio file from this location. In case the URL uses the HTTPS schema, TLS will be used for securing the connection, and the VoiceAI Connect will verify the certificate of the server.

For Version 3.8 and earlier: The media format of the file must match the format specified by the playUrlMediaFormat parameter; otherwise, the audio is played corruptly. See below for the supported formats.

Example:

AudioCodes Bot API

{
  "type": "event",
  "name": "playUrl",
  "activityParams": {
    "playUrlUrl": "https://example.com/my-file.wav",
    "playUrlMediaFormat": "wav/lpcm16"
  }
}

Microsoft Bot Framework

{
  "type": "event",
  "name": "playUrl",
  "channelData": {
    "activityParams": {
      "playUrlUrl": "https://example.com/my-file.wav",
      "playUrlMediaFormat": "wav/lpcm16"
    }
  }
}

Microsoft Copilot Studio

Send event named playUrl (see Sending event to VoiceAI Connect Enterprise)

{
  "activityParams": {
    "playUrlUrl": "https://example.com/my-file.wav",
    "playUrlMediaFormat": "wav/lpcm16"
  }
}

Microsoft Copilot Studio legacy

[Activity
  "type": "event",
  "name": "playUrl",
  "channelData": ${json(`
  {
    "activityParams": {
      "playUrlUrl": "https://example.com/my-file.wav",
      "playUrlMediaFormat": "wav/lpcm16"
      }
    }
  `)}
]

Dialogflow CX

For Dialogflow CX, add the "Play pre-recorded audio" fulfillment, as shown in the following example of configuration through the Dialogflow CX user interface:

Using the "Play pre-recorded audio" fulfillment assumes that the file is in wav/lpcm16 format. If the file is in a different format, you can set it by adding a Custom Payload fulfillment with the following content:

{
  "sessionParams": {
    "playUrlMediaFormat": "raw/lpcm16"
  }
}

As an alternative to using the "Play pre-recorded audio" fulfillment, you can also use the VoiceAI Connect playURL event, by adding a Custom Payload fulfillment with the following content:

{
  "activities": [{
    "type": "event",
    "name": "playUrl",
    "activityParams": {
      "playUrlUrl": "https://example.com/my-file.wav",
      "playUrlMediaFormat": "wav/lpcm16"
    }
  }]
}

Dialogflow ES

Add a Custom Payload response with the following content:

{
  "activities": [{
    "type": "event",
    "name": "playUrl",
    "activityParams": {
      "playUrlUrl": "https://example.com/my-file.wav",
      "playUrlMediaFormat": "wav/lpcm16"
    }
  }]
}

Amazon Lex

{
  "type": "event",
  "name": "playUrl",
  "activityParams": {
    "playUrlUrl": "https://example.com/my-file.wav",
    "playUrlMediaFormat": "wav/lpcm16"
  }
}

Tips

A similar functionality can be achieved using the SSML <audio> element, if the text-to-speech engine supports it. See Playing text to the user for more details.

Event parameters

The following table lists the parameters associated with this event:

See Changing call settings for details on how these parameters can be applied.

Parameter	Type	Description
`playUrlUrl`	String	URL of where the audio file is located.
`playUrlCaching`	Boolean	Control caching of the pre-recorded audio. Possible values: `true`: Enables caching `false`: (Default) Disables caching
`playUrlMediaFormat`	String	Defines the format of the pre-recorded audio file. You must encode your prerecorded audio file with the selected media format. Possible values: `raw/mulaw`: Mu-Law encoded (8 bit, 8 kHz) without a header `wav/mulaw`: Mu-Law encoded (8 bit, 8 kHz) with a WAV header `raw/lpcm16`: Linear PCM (16 bit, 16 kHz) without a header `wav/lpcm16`: (Default) Linear PCM (16 bit, 16 kHz) with a WAV header `raw/lpcm16_8`: Linear PCM (16 bit, 8 kHz) without a header `wav/lpcm16_8`: Linear PCM (16 bit, 8 kHz) with a WAV header `raw/lpcm16_24`: Linear PCM (16 bit, 24 kHz) without a header `wav/lpcm16_24`: Linear PCM (16 bit, 24 kHz) with a WAV header Note: `raw/lpcm16_24` and `wav/lpcm16_24` are applicable only to Azure speech services and AudioCodes Bot API (Streaming mode). VoiceAI Connect Enterprise supports `raw/lpcm16_24` and `wav/lpcm16_24` from Version 3.24.1 and later.
`playUrlAltText`	String	Defines the text to display in the transcript page of the user interface while the pre-recorded audio is played.
`playUrlFailureHandling`	String	Defines the behavior to be taken in case of failure playing the audio. Possible values: `disconnect`: (Default) Disconnects the call. `notify-bot`: Sends a playUrlFailed event to the bot. See Receiving audio playback failure notification for more information. `ignore`: Ignores the failure and moves on to the next action. VoiceAI Connect Enterprise supports this parameter from Version 3.8 and later.