actionHookDelay (#91)

markdown/docs/supporting-articles/conferencing-coach-mode.md

@@ -4,7 +4,7 @@ The conferencing feature supports a coaching feature whereby designated particip
 
 The classic example of this is a manager listening in on a call between an agent and a customer and being able to "whisper" to the agent without the customer hearing.  This feature is not limited to a single participant receiving the audio, it could be any subset of the conference participants.
 
->> Coach mode is only supported on version 0.9.0 and above
+>> Coach mode is only supported on version 0.9.1 and above
 
 ## Enabling coach mode
 

markdown/docs/supporting-articles/handling-action-hook-delays.md

@@ -0,0 +1,73 @@
+# Handling delays in bots
+
+When the [gather verb](/docs/webhooks/gather) collects a user utterance and submits it to the jambonz webhook or websocket application for processing, there may be a noticeable delay depending on what the back-end logic needs to do.  
+
+For instance, it may need to update a CRM system, make an http request, or feed an LLM and wait for a response etc.  Some of these operations may take a while to complete, and you want to be able to provide a user with some cue that this is normal system processing.
+
+In addition to these normal delays, there could also be situations where the backend has failed in some unexpected way (e.g. crashed, gone offline, restarted) and in this case the user would be left listening to dead air.
+
+For both of these cases, jambonz provides a way to pre-program instructions on what to say or play something when these sorts of delays are experienced.  This feature is enabled by the `actionHookDelayAction` property in either the gather or [config](/docs/webhooks/config) verbs. It is an object with the following properties:
+
+| property      | description | required  |
+| ------------- |-------------| -----|
+| enabled | boolean; enable or disable the actionHookDelayAction feature | yes |
+| noResponseTimeout | length of delay (in secs) which triggers an action | no (default: 0) |
+| actions | array of actions (jambonz verbs) to take when noResponseTimeout is triggered | yes |
+| retries | number of times to perform actions, with a noResponseTimeout between each retry | no (default: 1) |
+| noResponseGiveUpTimeout | length of time (in secs) to give up and stop performing actions | no (default: none) |
+
+## Examples
+#### Providing filler noise
+
+A simple use case is to provide filler noise when a back end operation takes a long time.  Here, if the response takes longer than two seconds we play some typing sounds to the caller.
+
+```json
+{
+  "verb": "gather",
+  "actionHook": "/processUserUtterance",
+  "actionHookDelayAction" : {
+    "enabled": true,
+    "noResponseTimeout": 2,
+    "actions": [
+      {
+        "verb": "play",
+        "url": "http://adfads/typing-sounds.mp3"
+      }
+    ]
+  }
+}
+```
+
+#### Providing a series of prompts
+
+A more complex use case would be to prompt multiple times as the delay gets longer, and then hang up the call if the bot does not respond in 20 seconds.
+
+```json
+{
+  "verb": "config",
+  "actionHookDelayAction" : {
+    "enabled": true,
+    "retries": 2,
+    "noResponseTimeout": 5,
+    "noResponseGiveupTimeout": 20,
+    "actions": [
+      {
+        "verb": "say",
+        "text": "Please hold while we complete your transaction"
+      },
+      {
+        "verb": "say",
+        "text": "Please continue to hold."
+      }
+    ]
+  }
+},
+{
+  "verb": "gather",
+  "say": "Would you like us to book your flight now?",
+  "input": ["speech"],
+  "actionHook": "/processUserUtterance"
+}
+```
+
+Note in the above that we have an array with two prompts.  The first is played after 5 seconds of delay and a different prompt is played if the user is still waiting for a response after 10 seconds.  If the delay reaches 20 seconds, then the call is terminated.

markdown/docs/webhooks/conference.md

@@ -21,7 +21,7 @@ You can use the following attributes in the `conference` command:
 | enterHook | A webhook to retrieve something to play or say to the caller just before they are put into a conference after waiting for it to start| no |
 | joinMuted | if true, this caller will join th conference with their audio muted | no |
 | maxParticipants | maximum number of participants that will be allowed in the conference | no |
-| memberTag | a way to classify participants for the "coach" feature; see related speakOnlyTo attribute below (0.9.0 and above)| no |
+| memberTag | a way to classify participants for the "coach" feature; see related speakOnlyTo attribute below (0.9.1 and above)| no |
 | name | name of the conference | yes |
 | speakOnlyTo | a tag value that will cause this members audio to be heard only by members that were assigned that tag; see [this article](/docs/supporting-articles/conferencing-coach-mode) for details | no |
 | startConferenceOnEnter | if true, start the conference only when this caller enters.  This also designates this caller as a moderator of the conference (default: true) | no |

markdown/docs/webhooks/config.md

@@ -28,6 +28,7 @@ You can use the following attributes in the `config` command:
 | option        | description | required  |
 | ------------- |-------------| -----|
 |amd|enable answering machine detection; see [answering machine detection](/docs/supporting-articles/answering-machine-detection) for details.|no|
+|actionHookDelayAction|object, see [here](/docs/supporting-articles/handling-action-hook-delays) for details.|no|
 |bargein|this object contains properties that are used to instantiate a 'background' [gather verb](/docs/webhooks/gather).|no|
 | bargeIn.enable| if true, begin listening for speech or dtmf input while the session is executing other verbs.  This is known as a "background gather" and an application to capture user input outside of a [gather verb](/docs/webhooks/gather).  If false, stop any background listening task that is in progress.| no|
 | bargeIn.sticky | If true and bargeIn.enable is true, then when the background gather completes with speech or dtmf detected, it will automatically start another background gather.|no|

markdown/docs/webhooks/gather.md

@@ -33,6 +33,7 @@ You can use the following options in the `gather` command:
 | option        | description | required  |
 | ------------- |-------------| -----|
 | actionHook | Webhook POST to invoke with the collected digits or speech. The payload will include a 'speech' or 'dtmf' property along with the standard attributes.  See below for more detail.| yes |
+|actionHookDelayAction|object, see [here](/docs/supporting-articles/handling-action-hook-delays) for details.|no|
 | bargein | allow speech bargein, i.e. kill audio playback if caller begins speaking | no |
 | dtmfBargein | allow dtmf bargein, i.e. kill audio playback if caller enters dtmf | no |
 | finishOnKey | Dmtf key that signals the end of input | no |