Fix ENG-1400: Better docs (#15)

structurely · Sep 28, 2023 · 0c3d163 · 0c3d163
1 parent 5b355ef
commit 0c3d163
Show file tree

Hide file tree

Showing 4 changed files with 24 additions and 24 deletions.
diff --git a/Makefile b/Makefile
@@ -1,6 +1,6 @@
 .PHONY: pull
 pull:
-	docker pull slatedocs/slate
+	docker pull slatedocs/slate || echo "Issue pulling latest image"
 
 .PHONY: build
 build: pull

diff --git a/build/index.html b/build/index.html
@@ -402,7 +402,7 @@
             <a href="#live-transfer" class="toc-h1 toc-link" data-title="Live Transfer">Live Transfer</a>
               <ul class="toc-list-h2">
                   <li>
-                    <a href="#live-transfer-flow" class="toc-h2 toc-link" data-title="Live Transfer Flow">Live Transfer Flow</a>
+                    <a href="#live-transfer-control-flow" class="toc-h2 toc-link" data-title="Live Transfer Control Flow">Live Transfer Control Flow</a>
                   </li>
                   <li>
                     <a href="#schema" class="toc-h2 toc-link" data-title="Schema">Schema</a>
@@ -496,7 +496,7 @@ <h1 id='introduction'>Introduction</h1>
 <h1 id='authentication'>Authentication</h1>
 <p>All requests to the API in must include the header X-Api-Authorization with your API key. To get an API key please contact us.</p>
 <h1 id='overview'>Overview</h1>
-<p>You can now configure <a href="#live-transfer">Live Transfer</a> to trigger the AI to automatically bridge the gap between SMS and Voice.  When the AI detects the lead needs to be on a phone call, it will <code>POST</code> a request to the <code>liveTransferUrl</code>, with the intent that a call is created between an Agent and the same Lead.</p>
+<p>You can configure <a href="#live-transfer">Live Transfer</a> to enable the AI to automatically bridge the gap between the Conversational AI and Voice.  When the AI detects the lead needs to be on a phone call, it will <code>POST</code> a request to the <code>liveTransferUrl</code>.  This enables your systems to broker a call between an Agent and the Lead.</p>
 <h2 id='endpoints'>Endpoints</h2>
 <p>All endpoints are hosted by the domain <code>api.structurely.com</code>. All requests must use <code>https</code>. Any request with the protocol <code>http</code> will be redirected to <code>https</code> with the status code 301. The path for the api will always start with <code>/v1</code>. Every resource endpoint will start with <code>https://api.structurely.com/v1</code>.</p>
 <h2 id='types'>Types</h2>
@@ -2228,15 +2228,15 @@ <h3 id='stages'>Stages</h3>
 <h3 id='domains'>Domains</h3>
 <p>To use domains other than the default real_estate domain, the domains have to be enabled in the settings and an appropriate lead type has to be selected in the lead_type slot. An example of using the mortgage scripts for a new home loan buyer would be to set the <code>allowedDomains</code> settings value to <code>[&quot;real_estate&quot;, &quot;mortgage&quot;]</code> and setting the lead_type slot to the values <code>&quot;buyer&quot;</code> and <code>&quot;new_home_loan&quot;</code>.</p>
 <h1 id='live-transfer'>Live Transfer</h1>
-<p>Live Transfer is in early access <strong>beta</strong>, there are no restrictions on it&#39;s use, but the API may change as we learn how Live Transfer is used in by each of our partners.</p>
+<p>Live Transfer is in <strong>early access beta</strong>, there are no restrictions on it&#39;s use, but the API may change as we learn how Live Transfer is used by each of our partners.</p>
 
-<p>When Conversations are created with Live Transfer, the AI is allowed to make live callbacks to a partner&#39;s system when it detects that a Lead needs to be on the phone.  Enable the feature by setting the following fields on <a href="#conversationsettings">ConversationSettings</a>.</p>
+<p>When Conversations have Live Transfer enabled, the AI is allowed to make live callbacks into a partner&#39;s system, when it detects that a Lead needs to be on the phone.  This feature is enabled by setting the following fields on <a href="#conversationsettings">ConversationSettings</a>, when creating a conversation.</p>
 
 <ul>
 <li><code>liveTransferUrl</code>: Enables the feature in the AI, this endpoint will recieve a <code>POST</code> request when the AI detects that a call is needed.</li>
 <li><code>liveTransferStatusUpdateUrl</code>: Enables status updates from the AI when processing the live transfer.</li>
 </ul>
-<h2 id='live-transfer-flow'>Live Transfer Flow</h2>
+<h2 id='live-transfer-control-flow'>Live Transfer Control Flow</h2>
 <p>When a Live Transfer is initiated, the AI will POST a <a href="#livetransferrequest">LiveTransferRequest</a> to the configured <code>liveTransferUrl</code>.  </p>
 <div class="highlight"><pre class="highlight json tab-json"><code><span class="err">//</span><span class="w"> </span><span class="err">LiveTransferRequest</span><span class="w"> </span><span class="err">(AI</span><span class="w"> </span><span class="err">POST</span><span class="w"> </span><span class="err">to</span><span class="w"> </span><span class="err">liveTransferUrl)</span><span class="w">
 </span><span class="p">{</span><span class="w">
@@ -2268,18 +2268,18 @@ <h2 id='live-transfer-flow'>Live Transfer Flow</h2>
     </span><span class="p">}</span><span class="w">
 </span><span class="p">}</span><span class="w">
 </span></code></pre></div>
-<p>The recieving system must respond in a timely manner.  At a high level this controller&#39;s responsibility is to detect if a call is possible, initiate that call, and then respond to the AI, indicate to the AI that a call was started (or not).  </p>
+<p>The recieving system must respond in a timely manner.  At a high level this controller&#39;s responsibility is to detect if a call is possible, initiate that call, and then respond to the AI. <strong>Future work</strong> will enable a partner to POST a transcription and recording at call completion, enabling the AI to set slots and intents, thus closing the circle between the Voice Call and the Conversational AI.</p>
 
-<p>The response to this API request must be a <code>HTTP 200</code> with a body that conforms to the <a href="#livetransferresponse">LiveTransferResponse</a> schema.  </p>
+<p>The response to this API request must be a <code>HTTP 200</code> with a JSON body that conforms to the <a href="#livetransferresponse">LiveTransferResponse</a> schema, this response&#39;s slot settings indicate to the AI that a call was started (or not).</p>
 
-<p>There is a wide set of states that a call could end up in, the response schema allows the endpoint to respond appropriately.  Live Transfer requests generally end up in three buckets:</p>
+<p>There are a wide set of states that a call could end up in, the response schema allows the endpoint to respond appropriately.  Live Transfer requests generally end up in three buckets:</p>
 
 <ol>
 <li>Attempt to start call was successful.</li>
-<li>Attempt to start call was not successful, retry at some point in the future.</li>
+<li>Attempt to start call was not successful, <strong>future (modeled but not active)</strong> retry the live transfer after a specified delay.</li>
 <li>Some pre-condition was not met, send a response to the lead.</li>
 </ol>
-<div class="highlight"><pre class="highlight json tab-json"><code><span class="err">//</span><span class="w"> </span><span class="err">LiveTransferResponse</span><span class="w">
+<div class="highlight"><pre class="highlight json tab-json"><code><span class="err">//</span><span class="w"> </span><span class="err">LiveTransferResponse</span><span class="w"> </span><span class="err">(partner</span><span class="w"> </span><span class="err">response</span><span class="w"> </span><span class="err">to</span><span class="w"> </span><span class="err">AI)</span><span class="w">
 </span><span class="p">{</span><span class="w">
     </span><span class="nl">"slots"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
         </span><span class="nl">"live_transfer_call_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"7915a28266d24462457cd8d6"</span><span class="p">,</span><span class="w">
@@ -2357,13 +2357,13 @@ <h2 id='live-transfer-flow'>Live Transfer Flow</h2>
 </tr>
 <tr>
 <td>intent_slots</td>
-<td><code>Map[String, Slot]</code></td>
+<td><code>Map[String, Array[String]]</code></td>
 <td>A map of slots tied to the intent, (only populated when triggered by an intent)</td>
 <td>No</td>
 </tr>
 <tr>
 <td>all_slots</td>
-<td><code>Map[String, Slot]</code></td>
+<td><code>Map[String, Array[String]]</code></td>
 <td>A map of all slots in this conversation</td>
 <td>Yes</td>
 </tr>

diff --git a/source/includes/_liveTransfer.md b/source/includes/_liveTransfer.md
@@ -1,13 +1,13 @@
 # Live Transfer
 
-Live Transfer is in early access **beta**, there are no restrictions on it's use, but the API may change as we learn how Live Transfer is used in by each of our partners.
+Live Transfer is in **early access beta**, there are no restrictions on it's use, but the API may change as we learn how Live Transfer is used by each of our partners.
 
-When Conversations are created with Live Transfer, the AI is allowed to make live callbacks to a partner's system when it detects that a Lead needs to be on the phone.  Enable the feature by setting the following fields on [ConversationSettings](#conversationsettings).
+When Conversations have Live Transfer enabled, the AI is allowed to make live callbacks into a partner's system, when it detects that a Lead needs to be on the phone.  This feature is enabled by setting the following fields on [ConversationSettings](#conversationsettings), when creating a conversation.
 
 - `liveTransferUrl`: Enables the feature in the AI, this endpoint will recieve a `POST` request when the AI detects that a call is needed.
 - `liveTransferStatusUpdateUrl`: Enables status updates from the AI when processing the live transfer.
 
-## Live Transfer Flow
+## Live Transfer Control Flow
 
 When a Live Transfer is initiated, the AI will POST a [LiveTransferRequest](#livetransferrequest) to the configured `liveTransferUrl`.  
 
@@ -43,18 +43,18 @@ When a Live Transfer is initiated, the AI will POST a [LiveTransferRequest](#liv
 }
 ```
 
-The recieving system must respond in a timely manner.  At a high level this controller's responsibility is to detect if a call is possible, initiate that call, and then respond to the AI, indicate to the AI that a call was started (or not).  
+The recieving system must respond in a timely manner.  At a high level this controller's responsibility is to detect if a call is possible, initiate that call, and then respond to the AI. **Future work** will enable a partner to POST a transcription and recording at call completion, enabling the AI to set slots and intents, thus closing the circle between the Voice Call and the Conversational AI.
 
-The response to this API request must be a `HTTP 200` with a body that conforms to the [LiveTransferResponse](#livetransferresponse) schema.  
+The response to this API request must be a `HTTP 200` with a JSON body that conforms to the [LiveTransferResponse](#livetransferresponse) schema, this response's slot settings indicate to the AI that a call was started (or not).
 
-There is a wide set of states that a call could end up in, the response schema allows the endpoint to respond appropriately.  Live Transfer requests generally end up in three buckets:
+There are a wide set of states that a call could end up in, the response schema allows the endpoint to respond appropriately.  Live Transfer requests generally end up in three buckets:
 
 1. Attempt to start call was successful.
-1. Attempt to start call was not successful, retry at some point in the future.
+1. Attempt to start call was not successful, **future (modeled but not active)** retry the live transfer after a specified delay.
 1. Some pre-condition was not met, send a response to the lead.
 
 ```json
-// LiveTransferResponse
+// LiveTransferResponse (partner response to AI)
 {
     "slots": {
         "live_transfer_call_id": "7915a28266d24462457cd8d6",
@@ -122,8 +122,8 @@ Field | Type | Description | Required |
 ----- | ---- | ----------- | -------- |
 conversation_id | `ObjectId` | The unique ID for this conversation | Yes
 intent_name | `String` | The name of the intent that triggered the transfer (only populated when triggered by an intent) | No
-intent_slots | `Map[String, Slot]` | A map of slots tied to the intent, (only populated when triggered by an intent) | No
-all_slots | `Map[String, Slot]` | A map of all slots in this conversation | Yes
+intent_slots | `Map[String, Array[String]]` | A map of slots tied to the intent, (only populated when triggered by an intent) | No
+all_slots | `Map[String, Array[String]]` | A map of all slots in this conversation | Yes
 
 
 ### LiveTransferResponse

diff --git a/source/index.html.md b/source/index.html.md
@@ -36,7 +36,7 @@ All requests to the API in must include the header X-Api-Authorization with your
 
 # Overview
 
-You can now configure [Live Transfer](#live-transfer) to trigger the AI to automatically bridge the gap between SMS and Voice.  When the AI detects the lead needs to be on a phone call, it will `POST` a request to the `liveTransferUrl`, with the intent that a call is created between an Agent and the same Lead.
+You can configure [Live Transfer](#live-transfer) to enable the AI to automatically bridge the gap between the Conversational AI and Voice.  When the AI detects the lead needs to be on a phone call, it will `POST` a request to the `liveTransferUrl`.  This enables your systems to broker a call between an Agent and the Lead.
 
 ## Endpoints