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](/content/docs/index.html).

## Getting Credentials

To get credentials, create a bot on the [VoiceAI connect portal](https://voiceaiconnect.audiocodes.io/).

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](https://legacy-docs-oss.rasa.com/docs/rasa/next/messaging-and-voice-channels#testing-channels-on-your-local-machine) 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`:

```yaml
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:

```yaml
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](https://techdocs.audiocodes.com/voice-ai-connect/#VAIG_Combined/call-initiation.htm?TocPath=Bot%2520integration%257CBasic%2520behavior%257C_____1) 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:

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

### 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.

#### Example: changing a pin code

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

```yaml
- 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:

```yaml
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
```

```yaml
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:

```yaml
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.