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 for to_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.
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.
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']}")