Merge pull request #49 from fixie-ai/ben-expand-inactivitymessages

Ben expand inactivitymessages

docs/src/content/docs/api/calls.mdx

@@ -3,7 +3,7 @@ title: "Calls"
 sidebar:
   order: 10
 ---
-import { Badge, Tabs, TabItem } from '@astrojs/starlight/components';
+import { Badge, Tabs, TabItem, Steps } from '@astrojs/starlight/components';
 import CallOut from '@components/CallOut.astro';
 
 <CallOut
@@ -151,10 +151,15 @@ An optional query parameter called `priorCallId` can be provided to continue a p
         <td>string</td>
         <td>Who should talk first when the call starts. Typically set to FIRST_SPEAKER_USER for outgoing calls and left as the default (FIRST_SPEAKER_AGENT) otherwise.</td>
       </tr>
+      <tr>
+        <td class="font-mono">inactivityMessages</td>
+        <td>array</td>
+        <td>Messages spoken by the agent when the user is inactive for the specified duration. See [below](#inactivitymessages) for more information.</td>
+      </tr>
       <tr>
         <td class="font-mono">initialMessages</td>
         <td>array</td>
-        <td>The conversation history to start from for this call. See [below](#more-info) for more information.</td>
+        <td>The conversation history to start from for this call. See [below](#initialmessages) for more information.</td>
       </tr>
        <tr>
         <td class="font-mono">initialOutputMedium</td>
@@ -537,6 +542,83 @@ Call recordings are only generated if you add `"recordingEnabled": true` to the
 
 This section contains additional details for some properties.
 
+### inactivityMessages
+Inactivity messages  allow your agent to gracefully handle periods of user silence and end the call after a period of user inactivity. This feature helps maintain engagement and ensures calls don't remain open indefinitely when users have disconnected or finished their interaction.
+
+* **Messages are Ordered** → Messages are delivered by the agent in the order provided.
+* **Message Durations are Cumulative** → The first message is delivered when the user has been inactive for its duration. Each subsequent message m is delivered its duration after message m-1 (provided the user remains inactive).
+* **User Interactions Reset** → Any activity from the user will reset the message sequence.
+* **Different Behaviors** → Messages can have different end behaviors and can terminate the call.
+
+##### Best Practices
+* Keep messages concise and natural-sounding.
+* Start with friendly check-in messages before moving to call termination.
+* Provide clear context in messages if the call will be terminated.
+
+
+##### Message Format
+When creating a new call, `inactivityMessages` are an array of message objects. Each message must provide the following:
+
+<dl class="space-y-4">
+  <div>
+    <dt class="font-mono">duration</dt>
+    <dd class="ml-4"><span class="text-gray-600">string</span> - The duration (in seconds) after which the message should be spoken.</dd>
+    <dd class="ml-4"><span class="text-gray-600">pattern</span> - `^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$`</dd>
+    <dd class="ml-4"><span class="text-gray-600">examples</span> - "60s", "5.5s"</dd>
+  </div>
+  <div>
+    <dt class="font-mono">message</dt>
+    <dd class="ml-4"><span class="text-gray-600">string</span> - The message to speak.</dd>
+    <dd class="ml-4"><span class="text-gray-600">examples</span> - "Are you still there?", "If there's nothing else, I will end the call now."</dd>
+  </div>
+  <div>
+    <dt class="font-mono">endBehavior</dt>
+    <dd class="ml-4"><span class="text-gray-600">string</span> - The behavior to exhibit when the message is finished being spoken. Must be one of the enumerated values.</dd>
+    <dd class="ml-4"><span class="text-gray-600">enum</span></dd>
+    <dd class="ml-8">
+      <ul class="list-disc space-y-2">
+        <li><code>END_BEHAVIOR_UNSPECIFIED</code> - Default. The system will continue to wait for user input.</li>
+        <li><code>END_BEHAVIOR_HANG_UP_SOFT</code> - Will end the call unless the user interacts while the agent is delivering the message.</li>
+        <li><code>END_BEHAVIOR_HANG_UP_STRICT</code> - Will end the call after speaking the message, regardless of whether the user interrupts.</li>
+      </ul>
+    </dd>
+  </div>
+</dl>
+
+##### Example
+
+```js
+{
+  "systemPrompt": "You are a helpful assistant.",
+  "inactivityMessages": [
+    {
+      "duration": "30s",
+      "message": "Are you still there?"
+    },
+    {
+      "duration": "15s",
+      "message": "If there's nothing else, may I end the call?"
+    },
+    {
+      "duration": "10s",
+      "message": "Thank you for calling. Have a great day. Goodbye.",
+      "endBehavior": "END_BEHAVIOR_HANG_UP_SOFT"
+    }
+  ]
+}
+```
+
+Here's what would happen based on the example above:
+
+<Steps>
+1. Call starts.
+1. After 30 seconds of no user interaction, agent says "Are you still there?".
+1. If user interacts, call continues. If no user interaction occurs for another 15 seconds, agent says "If there's nothing else, may I end the call?".
+1. If no user interaction occurs for another 10 seconds, agent says the provided message and the call ends unless the agent is interrupted during this final message.
+</Steps>
+
+
+
 ### initialMessages
 When creating a new call or a new call stage, you can provide messages to the agent via `initialMessages`. By default, new calls don't have initial messages and call stages inherit the prior stage's messages. New calls will inherit messages if `priorCallId` is set.
 
@@ -561,10 +643,14 @@ Here's an example:
 ```
 
 #### Using Mistral
-If you are using `fixie-ai/ultravox-mistral-nemo-12B` as your model, you need to do the following when creating the call:
-1. **Empty System Prompt** → Set `systemPrompt` to an empty string.
-1. **Prompt in Initial Messages** → Add a single user message to `initialMessages` that contains the system prompt.
-1. **Proper Turns** → Make sure that you follow Mistral's strict, alternating, user > agent > user message ordering.
+:::caution[Important Note]
+Mistral requires a simplified prompt structure.
+:::
+
+When using `fixie-ai/ultravox-mistral-nemo-12B`:
+1. **Empty System Prompt** → Set `systemPrompt` to an empty string (`""`).
+1. **Prompt in Initial Messages** → Add system prompt instructions as the first user message in `initialMessages`.
+1. **Proper Turns** → Maintain strict user > agent > user message alternation.
 
 Here's an example of what the request body for creating the call might look like: