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.
You can now configure 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 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.
All endpoints are hosted by the domain api.structurely.com. All requests must use https. Any request with the protocol http will be redirected to https with the status code 301. The path for the api will always start with /v1. Every resource endpoint will start with https://api.structurely.com/v1.
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 allowedDomains settings value to ["real_estate", "mortgage"] and setting the lead_type slot to the values "buyer" and "new_home_loan".
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.
+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, 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.When a Live Transfer is initiated, the AI will POST a LiveTransferRequest to the configured liveTransferUrl.
// LiveTransferRequest (AI POST to liveTransferUrl)
{
@@ -2268,18 +2268,18 @@ Live Transfer Flow
}
}
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 schema.
The response to this API request must be a HTTP 200 with a JSON body that conforms to the 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:
// LiveTransferResponse
+// LiveTransferResponse (partner response to AI)
{
"slots": {
"live_transfer_call_id": "7915a28266d24462457cd8d6",
@@ -2357,13 +2357,13 @@ Live Transfer Flow
intent_slots
-Map[String, Slot]Map[String, Array[String]]A map of slots tied to the intent, (only populated when triggered by an intent)
No
all_slots
-Map[String, Slot]Map[String, Array[String]]A map of all slots in this conversation
Yes
diff --git a/source/includes/_liveTransfer.md b/source/includes/_liveTransfer.md
index 1ebda23815d..5ebb4a3b5bb 100644
--- 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
index dea79d10bae..55669ae9a83 100644
--- 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