Skip to content
This repository has been archived by the owner on Jan 15, 2025. It is now read-only.

chore: Complete call recording extensions package mini-spec #1211

Merged
merged 1 commit into from
Jul 10, 2021
Merged

chore: Complete call recording extensions package mini-spec #1211

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 68 additions & 35 deletions packages/Telephony/Readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,73 +6,106 @@ The Microsoft.Bot.Components.Telephon package contains pre-built actions for bui
- [Call Recording](#Call-Recording)
- [DTMF Batching ](#DTMF-Batching)

## Call Transfer
## **Call Transfer**
Like any other channel, Telephony channel allows you to transfer call to an agent over a phone number. Learn more at [Telephony Advanced Features - Call Transfer](https://github.com/microsoft/botframework-telephony/blob/main/TransferCallOut.md).

_Parameters_
#### Parameters
* PhoneNumber

_Usage_
#### Usage
* Phone Number is not empty and in the E.164 format.
* The call transfer action is only valid when called in a conversation on the Telephony channel. The action can be considered a No-op for all other channels.

_Dialog Flow_
#### Dialog Flow
* Once the call transfer is completed, the bot is removed from the current conversation and control is transferred to the extenal phone nunber.
* [Open] Do we get back a handoff status on success? Should we wait for the status in our package?
* Any actions specified after call transfer will not be executed. Treat it like a call end.

_Failures_
#### Failures
* [Open] How should the package fail when Phone Number is Empty - should we throw an exception? How can we make sure that the exception message is localize properly?
* [Open] When the phone number is not in a valid E.164 format, how does the call transfer fail?
* [Open] Do we get back a handoff status on failure?


## Call Recording
The call recording commands enables bots to request that calls are recorded by the phone provider. The bot has controls to start, stop, pause and resume the recording. Learn more at [Telephony Advanced Features - Call Recording](https://github.com/microsoft/botframework-telephony/blob/main/CallRecording.md).
## **Call Recording**
The call recording commands enable bots to request that calls are recorded by the phone provider. The bot can control when to start, stop, pause and resume the recording with these commands. For more information about the call recording capabilities, see [Telephony Advanced Features - Call Recording](https://github.com/microsoft/botframework-telephony/blob/main/CallRecording.md).

### Start Recording
The recording extensions included in the Telephony package provide custom actions to take care of sending each of the call recording commands and waiting for the corresponding command result. Bot developers can also choose if interruptions are allowed when waiting for the command result.

### **Start Recording**
The Start Recording action starts recording of the conversation.

_Parameters_
* AllowInterruptions
#### Parameters
* AllowInterruptions [`true`,`false`]

_Usage_
* If a recording is started for a conversation, another recording for the same conversation cannot be started. In such case, Telephony channel returns an error indicating that the "Recording is already in progress".
* The start recording action is only valid when called in a conversation on the Telephony channel. The action can be considered a No-op for all other channels.
#### Usage
* If a recording is started for a conversation, another recording for the same conversation cannot be started. In such case, the Telephony Channel returns an error indicating that the _"Recording is already in progress"_.
* The start recording action is only valid when called in a conversation on the Telephony channel.

_Dialog Flow_
* By default AllowInterruptions is set to `true` i.e. dialog continues while the recording is started in the background
* To block the dialog when recording is started, set AllowInterruptions to `false`.
#### Dialog Flow
* By default AllowInterruptions is set to `true` i.e. dialog continues while the recording is started in the background.
* To block the dialog when a recording is started, set AllowInterruptions to `false`.
* When a start recording result is received and indicates success, the action is considered complete. If the dialog was blocked, interrruptions will be unblocked once the result is received.

_Failures_
* When a start recording result is received and indicates error, the dialog throws an ErrorResponseException.
#### Failures
* When a start recording result is received and indicates error, the dialog throws an `ErrorResponseException`.

### Pause Recording
The Pause Recording action pauses recording of the conversation. This action is typicalled used when the current dialog deals with sensitive information and must not be recorded.
### **Pause Recording**
The Pause Recording action pauses recording of the conversation. This action is typically used when the current turn/set of turns deals with sensitive information and must not be recorded.

_Parameters_
* AllowInterruptions
#### Parameters
* AllowInterruptions [`true`,`false`]

_Usage_
* If PauseRecording is called and there is no recording in progress, Telephony channel returns an error indicating that the "Recording has not started".
* The pause recording action is only valid when called in a conversation on the Telephony channel. The action can be considered a No-op for all other channels.
#### Usage
* If PauseRecording is called and there is no recording in progress, Telephony channel returns an error indicating that the _"Recording has not started"_.
* The pause recording action is only valid when called in a conversation on the Telephony channel.

_Dialog Flow_
* By default AllowInterruptions is set to `true` i.e. dialog continues while the recording is being paused in the background
* To block the dialog when recording is started, set AllowInterruptions to `false`.
#### Dialog Flow
* By default AllowInterruptions is set to `true` i.e. dialog continues while the recording is being paused in the background.
* To block the dialog when recording is paused, set AllowInterruptions to `false`.
* When a pause recording result is received and indicates success, the action is considered complete. If the dialog was blocked, interrruptions will be unblocked once the result is received.

_Failures_
* When a pause recording result is received and indicates error, the dialog throws an ErrorResponseException.
#### Failures
* When a pause recording result is received and indicates error, the dialog throws an `ErrorResponseException`.

### Resume Recording
_In progress_
### **Resume Recording**
The Resume Recording action resumes recording of the conversation. This action is used to resume a previouly paused recording.

### Stop Recording
_In progress_
#### Parameters_
* AllowInterruptions [`true`,`false`]

#### Usage
* [Open] _Add error details_
* The pause recording action is only valid when called in a conversation on the Telephony channel.

#### Dialog Flow
* By default AllowInterruptions is set to `true` i.e. dialog continues while the recording is being resumed in the background.
* To block the dialog when recording is resumed, set AllowInterruptions to `false`.
* When a resume recording result is received and indicates success, the action is considered complete. If the dialog was blocked, interrruptions will be unblocked once the result is received.

#### Failures
* When a resume recording result is received and indicates error, the dialog throws an `ErrorResponseException`.

### **Stop Recording**
The Stop Recording action stops recording of the conversation. Note that it is not required to call StopRecording explicitly. The recording is always stopped when the bot/caller ends the conversation or if the call is transferred to an external phone number.

#### Parameters
* AllowInterruptions [`true`,`false`]

#### Usage
* If StopRecording is called and there is no recording in progress, Telephony channel returns an error indicating that the _"Recording has not started"_.
* If a recording for a single conversation is stopped and started again, the recordings appear as multiple recording sessions in the storage. We do not recommend using the pattern StartRecording-StopRecording-StartRecording-StopRecording since it creates multiple recording files for a single conversation. Instead, we recommend using StartRecording-PauseRecording-ResumeRecording-EndCall/StopRecording to create a single recording file for the converastion.
* The stop recording action is only valid when called in a conversation on the Telephony channel.

#### Dialog Flow
* By default AllowInterruptions is set to `true` i.e. dialog continues while the recording is being stopped in the background.
* To block the dialog when recording is stopped, set AllowInterruptions to `false`.
* When a stop recording result is received and indicates success, the action is considered complete. If the dialog was blocked, interrruptions will be unblocked once the result is received.

#### Failures
* When a stop recording result is received and indicates error, the dialog throws an `ErrorResponseException`.

## DTMF Batching
## **DTMF Batching**
_In progress_

## Learn more
Expand Down