Library API
Table of Contents
Attachments and Analysis
Vcon Class
The Vcon
class is the root class representing a vCon (Virtual Conversation) object.
Constructor
Vcon(vcon_dict: Optional[dict] = None) # Optional: initialize from dictionary
Note: If no dictionary is provided, an empty vCon object will be created. Use build_new()
for a properly initialized vCon object.
Class Methods
build_from_json(json_string: str) -> Vcon
: Initialize a Vcon object from a JSON string.build_new() -> Vcon
: Initialize a Vcon object with default values.generate_key_pair() -> tuple
: Generate a new RSA key pair for signing vCons.
Instance Methods
to_json() -> str
: Serialize the vCon to a JSON string.to_dict() -> dict
: Serialize the vCon to a dictionary.dumps() -> str
: Alias forto_json()
.get_tag(tag_name: str) -> Optional[str]
: Returns the value of a tag by name.add_tag(tag_name: str, tag_value: str) -> None
: Adds a tag to the vCon.find_attachment_by_type(type: str) -> Optional[dict]
: Finds an attachment by type.add_attachment(body: Union[dict, list, str], type: str, encoding: str = "none") -> None
: Adds an attachment to the vCon.find_analysis_by_type(type: str) -> Optional[dict]
: Finds an analysis by type.add_analysis(type: str, dialog: Union[list, int], vendor: str, body: Union[dict, list, str], encoding: str = "none", extra: Optional[dict] = None) -> None
: Adds analysis data to the vCon.add_party(party: Party) -> None
: Adds a party to the vCon.find_party_index(by: str, val: str) -> Optional[int]
: Find the index of a party in the vCon given a key-value pair.find_dialog(by: str, val: str) -> Optional[Dialog]
: Find a dialog in the vCon given a key-value pair.add_dialog(dialog: Dialog) -> None
: Add a dialog to the vCon.sign(private_key: Union[rsa.RSAPrivateKey, bytes]) -> None
: Sign the vCon using JWS.verify(public_key: Union[rsa.RSAPublicKey, bytes]) -> bool
: Verify the JWS signature of the vCon.
Properties
Note: Properties that are not set will not be present in the vCon object. Use hasattr()
to check for their presence.
tags: Optional[dict]
: The tags attachment.parties: list[Party]
: The list of parties.dialog: list[Dialog]
: The list of dialogs.attachments: list
: The list of attachments.analysis: list
: The list of analyses.uuid: str
: The UUID of the vCon.vcon: str
: The vCon version.subject: Optional[str]
: The subject of the vCon.created_at: str
: The creation timestamp of the vCon.updated_at: str
: The last update timestamp of the vCon.redacted: Optional[dict]
: The redacted information of the vCon.appended: Optional[dict]
: The appended information of the vCon.group: Optional[dict]
: The group information of the vCon.meta: Optional[dict]
: The metadata of the vCon.
Example Usage
# Create a new vCon
vcon = Vcon.build_new()
# Add a party
party = Party(tel="+1234567890", name="Alice", role="caller")
vcon.add_party(party)
# Add a dialog
dialog = Dialog(
type="text",
start=datetime.datetime.now(datetime.timezone.utc).isoformat(),
parties=[0],
body="Hello, I need help."
)
vcon.add_dialog(dialog)
# Add metadata
vcon.add_tag("customer_id", "12345")
# Check for optional properties
if hasattr(vcon, "subject"):
print(f"vCon subject: {vcon.subject}")
# Sign the vCon
private_key, public_key = Vcon.generate_key_pair()
vcon.sign(private_key)
# Serialize to JSON
json_str = vcon.to_json()
Dialog Class
The Dialog
class represents a dialog in the system.
Constructor
Dialog(type: str, # Required: type of dialog (e.g., "text", "audio")
start: datetime, # Required: start time of the dialog
parties: List[int], # Required: list of party indices
originator: Optional[int] = None, # Optional: index of originating party
mimetype: Optional[str] = None, # Optional: MIME type of content
filename: Optional[str] = None, # Optional: name of associated file
body: Optional[str] = None, # Optional: content of the dialog
encoding: Optional[str] = None, # Optional: encoding of the content
url: Optional[str] = None, # Optional: URL to external content
alg: Optional[str] = None, # Optional: algorithm used for signatures
signature: Optional[str] = None, # Optional: signature for verification
disposition: Optional[str] = None, # Optional: handling instructions
party_history: Optional[List[PartyHistory]] = None, # Optional: party state changes
transferee: Optional[int] = None, # Optional: party being transferred
transferor: Optional[int] = None, # Optional: party initiating transfer
transfer_target: Optional[int] = None, # Optional: transfer destination party
original: Optional[int] = None, # Optional: original dialog reference
consultation: Optional[int] = None, # Optional: consultation dialog reference
target_dialog: Optional[int] = None, # Optional: target dialog reference
campaign: Optional[str] = None, # Optional: campaign identifier
interaction: Optional[str] = None, # Optional: interaction identifier
skill: Optional[str] = None, # Optional: skill identifier
duration: Optional[float] = None, # Optional: duration in seconds
meta: Optional[dict] = None) # Optional: additional metadata
Note: Optional parameters that are set to None will not create attributes on the Dialog instance. Use hasattr()
to check for the presence of optional attributes.
Methods
to_dict()
: Returns a dictionary representation of the Dialog object.add_external_data(url: str, filename: str, mimetype: str) -> None
: Adds external data to the dialog.add_inline_data(body: str, filename: str, mimetype: str) -> None
: Adds inline data to the dialog.is_external_data() -> bool
: Checks if the dialog is an external data dialog.is_inline_data() -> bool
: Checks if the dialog is an inline data dialog.is_text() -> bool
: Checks if the dialog is a text dialog.is_audio() -> bool
: Checks if the dialog is an audio dialog.is_video() -> bool
: Checks if the dialog is a video dialog.is_email() -> bool
: Checks if the dialog is an email dialog.is_external_data_changed() -> bool
: Checks if the external data dialog's contents have changed.to_inline_data() -> None
: Converts the dialog from an external data dialog to an inline data dialog.
Example Usage
# Create a text dialog
dialog = Dialog(
type="text",
start=datetime.datetime.now(datetime.timezone.utc),
parties=[0, 1],
originator=0,
mimetype="text/plain",
body="Hello, I need help with my account."
)
# Check for optional attributes
if hasattr(dialog, "duration"):
print(f"Dialog duration: {dialog.duration}")
# Create an audio dialog with external data
audio_dialog = Dialog(
type="audio",
start=datetime.datetime.now(datetime.timezone.utc),
parties=[0, 1]
)
audio_dialog.add_external_data(
url="https://example.com/audio.mp3",
filename="conversation.mp3",
mimetype="audio/mp3"
)
Party Class
The Party
class represents a participant in a conversation.
Constructor
Party(tel: Optional[str] = None, # Optional: telephone number
stir: Optional[str] = None, # Optional: STIR/SHAKEN verification info
mailto: Optional[str] = None, # Optional: email address
name: Optional[str] = None, # Optional: display name
validation: Optional[str] = None, # Optional: validation status
gmlpos: Optional[str] = None, # Optional: geographic position
civicaddress: Optional[CivicAddress] = None, # Optional: structured address
uuid: Optional[str] = None, # Optional: unique identifier
role: Optional[str] = None, # Optional: party's role
contact_list: Optional[str] = None, # Optional: contact list reference
meta: Optional[dict] = None) # Optional: additional metadata
Note: Optional parameters that are set to None will not create attributes on the Party instance. Use hasattr()
to check for the presence of optional attributes.
Methods
to_dict() -> dict
: Returns a dictionary representation of the Party object.
Example Usage
# Create a party with basic information
party = Party(
tel="+1234567890",
name="Alice Smith",
role="caller"
)
# Create a party with address information
address = CivicAddress(
a1="US",
a2="California",
a3="San Francisco"
)
party_with_address = Party(
tel="+1987654321",
name="Bob Jones",
role="agent",
civicaddress=address
)
# Check for optional attributes
if hasattr(party, "mailto"):
print(f"Party email: {party.mailto}")
# Add custom metadata
party = Party(
tel="+1234567890",
name="Charlie Brown",
meta={
"department": "Sales",
"employee_id": "12345"
}
)
PartyHistory Class
The PartyHistory
class represents a change in a party's state during a conversation.
Constructor
PartyHistory(party: int, # Required: index of the party
event: str, # Required: type of event
time: datetime) # Required: time of the event
Methods
to_dict() -> dict
: Returns a dictionary representation of the PartyHistory object.
Example Usage
# Create a party history entry
history = PartyHistory(
party=0,
event="connected",
time=datetime.datetime.now(datetime.timezone.utc)
)
# Add to a dialog
dialog = Dialog(
type="text",
start=datetime.datetime.now(datetime.timezone.utc),
parties=[0, 1],
party_history=[history]
)
Constants
MIME_TYPES
: A list of supported MIME types for dialogs.
MIME_TYPES = [
"text/plain",
"audio/x-wav",
"audio/x-mp3",
"audio/x-mp4",
"audio/ogg",
"video/x-mp4",
"video/ogg",
"multipart/mixed",
"message/external-body",
]
Attachments and Analysis
Attachments
Attachments in vCon objects are used to store additional data related to the conversation. Common use cases include transcripts, metadata, and supplementary files.
Adding Attachments
vcon.add_attachment(
body: Union[dict, list, str], # Required: content of the attachment
type: str, # Required: type identifier for the attachment
encoding: str = "none" # Optional: encoding of the content
)
Note: The body
parameter can accept different types of data:
Strings for text content
Dictionaries for structured data
Lists for collections of data
Example Usage
# Add a transcript attachment
transcript = "Customer: Hello\nAgent: How can I help you today?"
vcon.add_attachment(
body=transcript,
type="transcript",
encoding="none"
)
# Add structured metadata
metadata = {
"queue_time": 45,
"handling_time": 180,
"satisfaction_score": 9
}
vcon.add_attachment(
body=metadata,
type="call_metrics",
encoding="none"
)
# Find an attachment
transcript = vcon.find_attachment_by_type("transcript")
if transcript:
print(transcript["body"])
Analysis
Analysis objects store the results of various types of analysis performed on the conversation, such as sentiment analysis, topic classification, or compliance checking.
Adding Analysis
vcon.add_analysis(
type: str, # Required: type of analysis
dialog: Union[list, int], # Required: dialog indices analyzed
vendor: str, # Required: analysis provider
body: Union[dict, list, str], # Required: analysis results
encoding: str = "none", # Optional: encoding of the content
extra: Optional[dict] = None # Optional: additional metadata
)
Example Usage
# Add sentiment analysis
sentiment_results = {
"overall_sentiment": "positive",
"segments": [
{
"text": "Hello, I need help with my account",
"sentiment": "neutral",
"confidence": 0.85
},
{
"text": "I'm happy to help you with that!",
"sentiment": "positive",
"confidence": 0.92
}
]
}
vcon.add_analysis(
type="sentiment",
dialog=[0, 1], # Analyzing first two dialogs
vendor="SentimentAnalyzer",
body=sentiment_results
)
# Add topic classification
topic_results = {
"primary_topic": "account_access",
"confidence": 0.88,
"secondary_topics": ["authentication", "password_reset"]
}
vcon.add_analysis(
type="topic_classification",
dialog=[0], # Analyzing first dialog only
vendor="TopicClassifier",
body=topic_results,
extra={"model_version": "2.1.0"}
)
# Find analysis results
sentiment = vcon.find_analysis_by_type("sentiment")
if sentiment:
print(f"Overall sentiment: {sentiment['body']['overall_sentiment']}")
Common Use Cases
Quality Monitoring
# Add QA scoring
qa_results = {
"overall_score": 92,
"categories": {
"greeting": 100,
"problem_solving": 85,
"closing": 90
},
"notes": "Excellent customer service, could improve problem resolution time"
}
vcon.add_analysis(
type="quality_score",
dialog=list(range(len(vcon.dialog))), # Analyze all dialogs
vendor="QATeam",
body=qa_results
)
Compliance Checking
# Add compliance analysis
compliance_results = {
"compliant": True,
"checks": [
{"type": "pci_detection", "passed": True},
{"type": "pii_detection", "passed": True},
{"type": "disclaimer_present", "passed": True}
]
}
vcon.add_analysis(
type="compliance_check",
dialog=list(range(len(vcon.dialog))),
vendor="ComplianceChecker",
body=compliance_results,
extra={"regulation": "GDPR"}
)
Conversation Analytics
# Add interaction metrics
metrics = {
"talk_time_ratio": {
"agent": 0.45,
"customer": 0.55
},
"interruptions": 2,
"silence_periods": [
{"start": 45, "duration": 3.5},
{"start": 120, "duration": 2.1}
]
}
vcon.add_analysis(
type="conversation_metrics",
dialog=list(range(len(vcon.dialog))),
vendor="InteractionAnalyzer",
body=metrics
)
Last updated
Was this helpful?