Audiocodes VoiceAI Connect

You are viewing documentation for our open source project which is maintained by the community. If you want to get started building assistants with Rasa please check out our latest documentation here.

Getting Credentials

To get credentials, create a bot on the VoiceAI connect portal.

  1. Select Bots in the left sidebar.
  2. Click on the + sign to create a new bot.
  3. Select Rasa as the Bot Framework.
  4. Set the bot URL and choose a token value.

Setting the bot URL with a tunneling solution when testing locally

Visit this section to learn how to generate the required bot URL when testing the channel on your local machine.

Setting credentials

The token value chosen above will be used in the credentials.yml:

rasa_plus.channels.audiocodes.AudiocodesInput:
  token: <token>

You can also specify optional parameters:

Parameter Default value Description
token No default value The token to authenticate calls between your Rasa assistant and VoiceAI connect
use_websocket true If true, Rasa will send messages through a web socket. If set to false, Rasa will send messages through http API calls.
keep_alive 120 In seconds. For each ongoing conversation, VoiceAI Connect will periodically verify the conversation is still active on the Rasa side.

Then restart your Rasa server to make the new channel endpoint available.

Usage

Receiving messages from a user

When a user speaks on the phone, VoiceAI Connect will send a text message (after it is processed by the speech-to-text engine) to your assistant like any other channel. This message will be interpreted by the NLU and you can then drive the conversation with rules, stories and forms.

Sending messages to a user

Your bot will respond with text messages like with any other channel. The text-to-speech engine will convert the text and deliver it as a voice message to the user.

Here is an example:

utter_greet:
  - text:'Hello! isn’t every life and every work beautiful?'

Note

Only text messages are allowed. Images, attachments, and buttons cannot be used with a voice channel.

Handling conversation events

Non-voice events can also be handled by the bot. Here are a few examples:

Event intent Description
start vaig_event_start VoiceAI will send this intent when it picks-up a phone call. In general, the response to that intent is a welcome or greeting message. Call context will be provided through entities
end vaig_event_end VoiceAI will send this intent when a call ends. You can use that to call an action that updates the call information.
DTMF vaig_event_DTMF VoiceAI will send this intent when receiving a DTMF tone (i.e user presses digit on the keyboard of the phone). The digit(s) sent will be passed in the value entity

The general pattern is that for every event sent, the bot will receive the vaig_event_<event> intent, with context information in entities.

Here is a simple rule to send a greeting message when a call to the bot is initiated:

- rule: New call
  steps:
  - intent: vaig_event_start
  - action: utter_greet

Check the VoiceAI Connect documentation for an exhaustive list of events.

Configuring calls

You can send events from Rasa to VoiceAI Connect to make changes to the current call configuration. For example, you might want to receive a notification when the user stays silent for more than 5 seconds, or you might need to customize how DTMF digits are sent by VoiceAI Connect.

Call configuration events are sent with custom messages and are specific to the current conversation (sometimes to a message). Which means they must be part of your stories or rules so the same behaviour is applied to all conversations.

Those Rasa responses don't utter anything, they just configure the voice gateway. It is a good practice naming them differently, for example prefixing them with utter_config_<what_it_does>.

All the supported events are exhaustively documented in the VoiceAI Connect documentation. We will look at one example here to illustrate the use of custom messages and events.

Example: changing a pin code

In this example we create a flow to allow a user to change a pin code.

- rule: Set pin code
  steps:
  # User says "I want to change my pin code"
  - intent: set_pin_code
  # Send the noUserInput configuration event
  - action: utter_config_no_user_input
  # Send the DTMF format configuration event
  - action: utter_config_dtmf_pin_code
  # A standard Rasa form to collect the pin code from the user
  - action: pin_code_form
  - ...

In the domain, we can add the utter_config_<config_event> responses:

utter_config_no_user_input:
  - custom:
      type: event
      name: config
      sessionParams:
        # If user stays silent for 5 seconds or more, the notification will be sent
        userNoInputTimeoutMS:5000
        # If you want to allow for more than one notification during a call
        userNoInputRetries:2
        # Enable the noUserInput notification
        userNoInputSendEvent:true

utter_config_dtmf_pin_code:
  - custom:
      type: event
      name: config
      sessionParams:
        # Enable grouped collection (i.e will send all digits in a single payload)
        dtmfCollect:true
        # If more than 5 secs have passed since a digit was pressed,
        # the input is considered completed and will be sent to the bot
        dtmfCollectInterDigitTimeoutMS:5000
        # If 6 digits are collected, VoiceAI will send those 6 digits
        # even if the user keeps pressing buttons
        dtmfCollectMaxDigits:6
        # If the user presses '#' the input is considered complete
        dtmfCollectSubmitDigit:"#"

Now you can configure the pin_code slot in the pin_code_form to extract the pin code from the value entity with the vaig_event_DTMF intent:

pin_code:
  type: text
  influence_conversation:false
  mappings:
  - type: from_entity
    entity: value
    intent: vaig_event_DTMF
    not_intent: vaig_event_noUserInput
    conditions:
      - active_loop: pin_code_form
        requested_slot: pin_code

Notice how vaig_event_noUserInput was declared in the not_intent field.

Since the vaig_event_noUserInput intent is sent by VoiceAI Connect when the user stays silent as per our configuration, we must deactivate the form so we can pick up the conversation from a rule or a story and gracefully handle the failure.

In the following example, we simply cancel the current flow if we receive the vaig_event_noUserInput intent (i.e. user stays silent) while the pin_code_form loop is active.

- rule: Set pin code - happy path
  steps:
  - intent: set_pin_code
  - action: utter_config_no_user_input
  - action: utter_config_dtmf_pin_code
  - action: pin_code_form
  - active_loop: pin_code_form
  - active_loop:null
  - slot_was_set:
    - requested_slot:null
  - action: utter_pin_code_changed
  - action: action_pin_code_cleanup

- rule: Set pin code - no response - cancel.
  condition:
  - active_loop: pin_code_form
  steps:
  - intent: vaig_event_noUserInput
  - action: utter_cancel_set_pin_code
  - action: action_deactivate_loop
  - active_loop:null