machine detection docs

vocodedev · Sep 6, 2023 · f9814bf · f9814bf
1 parent ad3d852
commit f9814bf
Show file tree

Hide file tree

Showing 4 changed files with 155 additions and 9 deletions.
diff --git a/docs/machine-detection.mdx b/docs/machine-detection.mdx
@@ -0,0 +1,69 @@
+---
+title: "[Beta] Answering machine detection"
+description: "Define the behavior of the bot when no one answers the phone"
+---
+
+The Vocode API allows you to configure your outbound call agent's behavior when the other end of a
+phone call is an answerphone as well as subscribe to events relating to machine detection.
+
+# Example 1: Hang up the call if it goes to voicemail
+
+The `on_machine_answer` parameter defines what should happen if a machine answers the phone.
+
+```python
+from vocode import CreateCallAgentParams
+
+vocode_client.calls.create_call(
+    from_number="<YOUR VOCODE NUMBER>",
+    to_number="15555555555",
+    agent=CreateCallAgentParams(
+        prompt=Prompt(
+            content="Ask Ajay if his refrigerator is running"
+        ),
+    ),
+    on_machine_answer="hangup"
+)
+```
+
+# Example 2: Hook into when a call goes to voicemail
+
+If you'd like the bot to stay on the call and leave a voicemail, set `on_machine_answer` to `"continue"`. You can
+also configure a webhook to be fired when the answering machine detection status
+
+```python
+from vocode import CreateCallAgentParams, PromptParams
+
+vocode_client.calls.create_call(
+    from_number="<YOUR VOCODE NUMBER>",
+    to_number="15555555555",
+    agent=CreateCallAgentParams(
+        prompt=PromptParams(
+            content="Ask Ajay if his refrigerator is running"
+        ),
+        webhook=WebhookParams(
+            url="<YOUR WEBHOOK URL>",
+            subscriptions=["event_machine_detection"]
+        )
+    ),
+    on_machine_answer="continue"
+)
+```
+
+Once the call is picked up, the webhook URL configured above will get the following POST request:
+
+```
+{
+  "type": "event_machine_detection",
+  "call_id": "<some UUID>",
+  "payload": {
+    "result": "machine" # or "human"
+  }
+}
+```
+
+# On the horizon
+
+Stay tuned for more features here, for example:
+
+- Instructing your agent to leave a particular voicemail
+- Routing the call to a human when a human picks up, otherwise leave a voicemail
diff --git a/docs/mint.json b/docs/mint.json
@@ -171,7 +171,8 @@
         "using-actions",
         "vectordb",
         "multilingual",
-        "injecting-context"
+        "injecting-context",
+        "machine-detection"
       ]
     }
   ],

diff --git a/docs/openapi.json b/docs/openapi.json
@@ -1422,7 +1422,18 @@
             "allOf": [{ "$ref": "#/components/schemas/InterruptSensitivity" }],
             "default": "high"
           },
-          "context_endpoint": { "type": "string", "title": "Context Endpoint" }
+          "context_endpoint": { "type": "string", "title": "Context Endpoint" },
+          "noise_suppression": {
+            "type": "boolean",
+            "title": "Noise Suppression",
+            "default": false
+          },
+          "endpointing_sensitivity": {
+            "type": "string",
+            "enum": ["auto", "relaxed"],
+            "title": "Endpointing Sensitivity",
+            "default": "auto"
+          }
         },
         "type": "object",
         "required": ["id", "user_id", "prompt", "actions", "voice"],
@@ -1508,7 +1519,18 @@
             "allOf": [{ "$ref": "#/components/schemas/InterruptSensitivity" }],
             "default": "high"
           },
-          "context_endpoint": { "type": "string", "title": "Context Endpoint" }
+          "context_endpoint": { "type": "string", "title": "Context Endpoint" },
+          "noise_suppression": {
+            "type": "boolean",
+            "title": "Noise Suppression",
+            "default": false
+          },
+          "endpointing_sensitivity": {
+            "type": "string",
+            "enum": ["auto", "relaxed"],
+            "title": "Endpointing Sensitivity",
+            "default": "auto"
+          }
         },
         "type": "object",
         "required": ["prompt", "voice"],
@@ -1613,6 +1635,20 @@
               { "$ref": "#/components/schemas/Undefined" }
             ],
             "title": "Context Endpoint"
+          },
+          "noise_suppression": {
+            "anyOf": [
+              { "type": "boolean" },
+              { "$ref": "#/components/schemas/Undefined" }
+            ],
+            "title": "Noise Suppression"
+          },
+          "endpointing_sensitivity": {
+            "anyOf": [
+              { "type": "string", "enum": ["auto", "relaxed"] },
+              { "$ref": "#/components/schemas/Undefined" }
+            ],
+            "title": "Endpointing Sensitivity"
           }
         },
         "type": "object",
@@ -1698,6 +1734,11 @@
             "default": false
           },
           "transcript": { "type": "string", "title": "Transcript" },
+          "machine_detection_result": {
+            "type": "string",
+            "enum": ["human", "machine"],
+            "title": "Machine Detection Result"
+          },
           "to_number": { "type": "string", "title": "To Number" },
           "from_number": { "type": "string", "title": "From Number" },
           "agent": { "$ref": "#/components/schemas/Agent" },
@@ -1752,7 +1793,7 @@
         "properties": {
           "field_type": {
             "type": "string",
-            "enum": ["field_type_email", "field_type_address"],
+            "enum": ["field_type_email"],
             "title": "Field Type"
           },
           "label": { "type": "string", "title": "Label" },
@@ -1828,7 +1869,18 @@
             "allOf": [{ "$ref": "#/components/schemas/InterruptSensitivity" }],
             "default": "high"
           },
-          "context_endpoint": { "type": "string", "title": "Context Endpoint" }
+          "context_endpoint": { "type": "string", "title": "Context Endpoint" },
+          "noise_suppression": {
+            "type": "boolean",
+            "title": "Noise Suppression",
+            "default": false
+          },
+          "endpointing_sensitivity": {
+            "type": "string",
+            "enum": ["auto", "relaxed"],
+            "title": "Endpointing Sensitivity",
+            "default": "auto"
+          }
         },
         "type": "object",
         "required": ["prompt"],
@@ -1844,6 +1896,12 @@
               { "$ref": "#/components/schemas/CreateCallAgentParams" }
             ],
             "title": "Agent"
+          },
+          "on_machine_answer": {
+            "type": "string",
+            "enum": ["continue", "hangup"],
+            "title": "On Machine Answer",
+            "default": "continue"
           }
         },
         "type": "object",
@@ -1912,7 +1970,7 @@
           "api_key": { "type": "string", "title": "Api Key" }
         },
         "type": "object",
-        "required": ["id", "user_id", "type", "voice_id", "api_key"],
+        "required": ["id", "user_id", "type", "voice_id"],
         "title": "ElevenLabsVoice"
       },
       "ElevenLabsVoiceParams": {
@@ -1928,7 +1986,7 @@
           "api_key": { "type": "string", "title": "Api Key" }
         },
         "type": "object",
-        "required": ["type", "voice_id", "api_key"],
+        "required": ["type", "voice_id"],
         "title": "ElevenLabsVoiceParams"
       },
       "ElevenLabsVoiceUpdateParams": {
@@ -2031,7 +2089,8 @@
           "event_phone_call_connected",
           "event_phone_call_ended",
           "event_transcript",
-          "event_recording"
+          "event_recording",
+          "event_machine_detection"
         ],
         "title": "EventType",
         "description": "An enumeration."
@@ -2099,7 +2158,18 @@
             "allOf": [{ "$ref": "#/components/schemas/InterruptSensitivity" }],
             "default": "high"
           },
-          "context_endpoint": { "type": "string", "title": "Context Endpoint" }
+          "context_endpoint": { "type": "string", "title": "Context Endpoint" },
+          "noise_suppression": {
+            "type": "boolean",
+            "title": "Noise Suppression",
+            "default": false
+          },
+          "endpointing_sensitivity": {
+            "type": "string",
+            "enum": ["auto", "relaxed"],
+            "title": "Endpointing Sensitivity",
+            "default": "auto"
+          }
         },
         "type": "object",
         "required": ["id", "user_id", "prompt", "actions", "voice"],
@@ -2120,6 +2190,11 @@
             "default": false
           },
           "transcript": { "type": "string", "title": "Transcript" },
+          "machine_detection_result": {
+            "type": "string",
+            "enum": ["human", "machine"],
+            "title": "Machine Detection Result"
+          },
           "to_number": { "type": "string", "title": "To Number" },
           "from_number": { "type": "string", "title": "From Number" },
           "agent": { "type": "string", "format": "uuid", "title": "Agent" },

diff --git a/docs/setting-up-webhook.mdx b/docs/setting-up-webhook.mdx
@@ -57,3 +57,4 @@ The full list of `EventType` is listed here:
 - `EVENT_PHONE_CALL_ENDED`: Indicating the phone call has ended.
 - `EVENT_TRANSCRIPT`: The transcription of the entire conversation.
 - `EVENT_RECORDING`: The recording of the conversation has become available.
+- `EVENT_MACHINE_DETECTION`: Indicating whether a human or a machine has picked up the phone.