Live Text Chat Analysis and Enrichment (Experimental API)
Overview
Hyperia supports live text chat stream analysis and NLP enrichment. You may stream text chats data to Hyperia directly over a secure websocket connection. Many forms of NLP enrichment are provided including dialog labeling, sentiment analysis, topic and named entity extraction, and intent + action identification.
Live Chat Enrichments
Hyperia outputs utterance-level transcriptions and NLP enrichments for analyzed live audio streams. Below is an example of the JSON message format:
{
"dialog_label": {
"confidence": DIALOG_LABEL_CONFIDENCE,
"label": "DIALOG_TYPE_LABEL"
},
"dialog_sentiment": {
"confidence": SENTIMENT_CONFIDENCE,
"sentiment": "SENTIMENT_POLARITY"
},
"document_type": "h:fm:ChatMessage",
"id": SEQUENCE_ID,
"primary_value": "transcript",
"printableStartTime": "START_TIME_IN_MM:SS_FORMAT",
"startTime": START_TIME_IN_SECONDS,
"topics": [
{
"score": TOPIC_SCORE,
"text": "TOPIC_NAME",
"type": "TOPIC_TYPE"
}
],
"transcript": "TRANSCRIPT_TEXT",
"tags": [
{
"tag_id": "TAG_GUID",
"tag_name": "TAG_NAME"
}
],
"chat_id": "GUID_OF_CHAT_STREAM"
}Dialog Label Enrichments
Dialog labels are generated for each transcribed utterance indicating the type of expression (fact, opinion, question, etc). A list of supported dialog labels is provided below:
| agreement |
| command |
| fact |
| opinion |
| pleasantries |
| question |
| task |
| uncertain |
| unknown |
Sentiment Enrichments
Sentiment extraction is performed on each transcribed utterance indicating the type of expression (positive, negative). Confidence values are provided to show the intensity of sentiment expression. To leverage sentiment enrichments, choose a threshold value for each polarity such as 0.3 - 0.5 depending on the intensity of expressions you desire.
Topic Enrichments
Topic and named entity extraction is performed on each transcribed utterance indicating specific topics or entities that are being discussed (people, companies, locations, etc). Supported topic types include:
| Affiliation |
| Cardinal |
| Date |
| Location |
| Organization |
| Percent |
| Person |
| Product |
| Quantity |
| Time |
| Topic |
Intent Tagging Enrichments
Hyperia performs intent analysis and tagging on utterances, identifying intents and actions such as Follow-ups, Next-steps, Requests-for-information, and so on. Dozens of intents and actions are supported, with new ones being added on a regular basis. Currently supported intents and actions include:
| Agenda |
| Action Item |
| Apology |
| Appreciation |
| Cannot Login |
| Commitments |
| Company About |
| Company Background |
| Concern |
| Confusion |
| Customers |
| Decision |
| Difficulty |
| Disapproval |
| Expensive |
| Frustration |
| Interest |
| Lateness |
| Make An Intro |
| Next Steps |
| Not Interested |
| Options |
| Personal Background |
| Pricing |
| Problems |
| Recommendation |
| Request for Information |
| Screen Sharing |
| Skepticism |
| Slowness |
| Something broken |
| System Problems |
| Timeline |
| Uncertainty |
| Want to Cancel |
| Want to Return |
Create Chat Processing Stream
Creates an text chat processing websocket stream for performing streaming speech recognition and natural language processing. This endpoint provisions 2 websockets: One that can be used for streaming text chat data (JSON format -- see schema below), and another that can be used to receive streaming JSON events (NLP enrichments, intents, live insights, etc). Websockets are automatically closed if a connection is not made to the text chat endpoint within 120 seconds of provisioning. Streams may be active for a maximum of 3 hours.
Endpoint:
/v1/chat/create
HTTP Method:
PUT
URI Parameters:
None
Returns:
If successful: HTTP 200
Return Payload:
{
"status": "ok",
"result": {
"stream_id": "ID_OF_CREATED_REALTIME_CHAT_STREAM",
"audio_socket": "HTTPS_URI_OF_CREATED_TEXT_CHAT_WEBSOCKET",
"event_socket": "HTTPS_URI_OF_CREATED_JSON_EVENT_WEBSOCKET"
}
}Code Sample:
from __future__ import print_function
from hyperia import Hyperia
import json
import sys
import websocket
import time
import threading
import json
import requests
def sender_thread(ws, file):
print("Starting sender loop.")
lines = file.readlines()
for line in lines:
line = line.rstrip()
ws.send(line)
time.sleep(5.0)
print("Finished sending")
def receiver_thread(ws):
print("Starting receiver loop.")
while True:
message = ws.recv()
json_message = json.loads(message)
if 'transcript' in json_message:
print(json_message['transcript'])
print(message)
else:
print(message)
print("")
print("Receiver exiting")
def open_websockets(socket_id, chat_socket, event_socket, file_path):
print(f"Connencting to socket {socket_id}")
ws_send = websocket.WebSocket()
socket_url = chat_socket
print(socket_url)
ws_send.connect(socket_url)
ws_recv = websocket.WebSocket()
socket_url = event_socket
print(socket_url)
ws_recv.connect(socket_url)
print("Connected..")
file = open(file_path, "r")
send_thread = threading.Thread(target=sender_thread, args=(ws_send, file))
recv_thread = threading.Thread(target=receiver_thread, args=(ws_recv,))
print("Starting receiver.")
recv_thread.start()
print("Starting sender.")
send_thread.start()
send_thread.join()
if len(sys.argv) < 2:
print("Error! Usage: chat_create_and_transcribe.py FILENAME")
exit(-1)
file_path = sys.argv[1]
# Create the Hyperia Object
hyperia = Hyperia()
print('')
print('')
print('############################################')
print('# Create Streaming Chat Example #')
print('############################################')
print('')
print('')
response = hyperia.chat_create()
print('## Response Object ##')
print(json.dumps(response, indent=4))
print('')
print('')
print('')
chat_id = response['result']['chat_id']
print(f"Created chat {chat_id}")
time.sleep(1)
chat_socket = response['result']['chat_socket']
event_socket = response['result']['event_socket']
open_websockets(chat_id, chat_socket, event_socket, file_path)List Active Chat Streams
Lists text chat streams that are currently active.
Endpoint:
/v1/chat/list
HTTP Method:
GET
URI Parameters:
None
Returns:
If successful: HTTP 200
Return Payload:
{
"status": "ok",
"results": [
{
"stream_id": "ID_OF_CREATED_REALTIME_CHAT_STREAM"
}
]
}Code Sample:
from hyperia import Hyperia
import json
import sys
import time
# Create the Hyperia Object
hyperia = Hyperia()
response = hyperia.chat_list()
for stream in response['results']:
print(f"Active stream {stream['stream_id']}")Check For Chat Stream Existence
Checks to see if an active realtime chat stream exists using a stream ID.
Endpoint:
/v1/chat/id/<chat_id>/exists
HTTP Method:
GET
URI Parameters:
None
Returns:
If successful: HTTP 200
Return Payload:
{
"status": "ok",
"exists": true | false
}Code Sample:
from hyperia import Hyperia
import json
import sys
import time
stream_id = "SOME_STREAM_ID"
# Create the Hyperia Object
hyperia = Hyperia()
response = hyperia.chat_exists(stream_id)
print(response['exists'])