altervoice-asterisk-callbot/README.md

Jovo plugin for Altervoice asterisk integration

# Altervoice Asterisk Callbot

Altervoice Asterisk Callbot

* [About](#About)
* [Installation ](#installation)
* [Prerequisite ](#prerequisite)
* [Jovo Integration](#jovo-integration)
 * [Actions to Telephony platform](#actions-to-telephony-platform)
 * [Jovo Model](#jovo-model)
 * [Data from Telephony platform](#data-from-telephony-platform)
 * [Events from Telephony platform](#events-from-telephony-platform)
* [Support](#support)

# About
Altervoice Asterisk Callbot is a plugin of [JOVO](https://www.jovo.tech/) framework.
It works with telephony platform such as Asterisk and the Altervoice Speech Controller module developed by Altervoice

# Installation
```sh
npm install altervoice-asterisk-callbot
```

# Prerequisite
To use the plugin, you must deploy and properly configure the following systems :
- [Asterisk server](https://www.asterisk.org/)  16.6.0+,
- [Altervoice Speech controller](https://bitbucket.org/altervoice_team/)

The plugin works with  [Dialogflow](https://dialogflow.cloud.google.com/) NUL engine

Additionally the Altervoice Speech Controller must be connected with STT and TTS engines
- STT  :  [Google Cloud Speech-To-Text](https://cloud.google.com/speech-to-text?hl=fr)
- TTS  :  [Google Cloud Text-To-Speech](https://cloud.google.com/text-to-speech)

# Jovo Integration
## Setup
Import Dialogflow and altervoice-asterisk-callbot plugins.
Install middlewares as shown in this example.

```javascript
const { App } = require('jovo-framework');
const { Dialogflow } = require('jovo-platform-dialogflow');
const { AltervoiceAsteriskCallbot } = require('altervoice-asterisk-callbot');
const app = new App();
app.use(
	new Dialogflow().use(
		new AltervoiceAsteriskCallbot()
		)
})
app.setHandler({
    LAUNCH() {
        this.tell("Hello callbot");
      }
})
```
The tell() method disable the voice recognition during the prompt. Then the call hang up.
Use ask() method to maintain the call.
More [JOVO Basic concepts](https://www.jovo.tech/docs/basic-concepts)

## Actions to Telephony platform
The Jovo handler has new method to send actions to Asterisk
```javascript
app.setHandler({
    LAUNCH() {
        this.addActions({telephonyHangup:true, setMode : 'AFTER_PLAY'}});
      }
})
```
*In this example, the application hangup the call after playing the prompt*

The first attribut of object define the action type that can be :
- **telephonyDtmf** : {grammar:string}
> to set allowed dtmf regex. Setting is maintained active until new regex or "" string
- **telephonyMaxCall** : {duration:number, prompt: string|SpeechBuilder }
> to set the maximum duration of call. *duration* is in seconds. *prompt* is the ssml content. When the max duration is riched, the prompt is played back and call hangup
- **telephonyInact** : {duration:number, prompt: string|SpeechBuilder, max_count:number }
> to set the user inactivity. *duration* is maximum duration of user inactivity in seconds. *prompt* is the ssml content to be play back. *max_count* is the number of prompt is played. When the user inactivity occurs all prompt and reprompt defined in ask() method are played, until the max_count is riched. If the max_count is bigger than number of prompt and reprompt defined in ask() method, the warning prmpt is played.
- **telephonyCallTransfer** : {phoneNumber: string}
> to transfer the call to an other destination number.
- **telephonyCallCancel** : true
> to cancel the call transfer .
- **telephonyHangup** : boolean
> to hangup the call
- **telephonyError** : string| SpeechBuilder;
 > to set ssml content when any error occurs


SetMode attribut defines when the action must be applied. It can be:
- **BEFORE_PLAY** : the action is applied before the prompt is played back (ex: DTMf grammar change).
- **AFTER_PLAY** : the action is applied after playing is complete (ex: call transfer)
- **AFTER_INACT** : the action is applied after the inactivity delay is over (ex: hangup)

## Jovo Model
Use the jovo model to associate the event and the Intent
```json
"intents": [
  { "name": "dtmfIntent",
    "dialogflow": {"events": [{"name": "TELEPHONY_DTMF"}]}
  }
]
```
*In this example : intent "dtmfIntent" is associated with TELEPHONY_DTMF event.*

## Data from Telephony platform
Asterisk Speech Controller send events when the user or call change.

The Jovo handler has new method to get data from Asterisk, such as getDtmf().
```javascript
app.setHandler({
    dtmfIntent() {
        const digits = this.getDtmf();
      }
})
```
*In this example : getDtmf() method is used to get the DTMF sequence when dtmfIntent is run by the jovo handler.*

## Events from Telephony platform
Here are the list of events and associated methods to get data from the Telephony platform :
- **TELEPHONY_DTMF** : sent when user press key on the phone and the sequence matches the active regex.
   >getDtmf(void) return an object {digits:string}
- **TELEPHONY_HANGUP** : sent when call has hangup.
  >getResult(void) return an object {cause_txt :string, cause_code: number}
- **TELEPHONY_RESULT** : sent when the call status has changed. Example when a call transfer is in progress.
  >getResult(void) return an object {cause_txt :string, cause_code: number}


# Support
support@altervoice.com

Visit Altervoice website https://www.altervoice.com