Usage Guide
The examples on this page run in order, in one Python session.
Building a vCon
A core-05 vCon has parties, sessions and dialog. A Session groups the dialog of
one conversation, and its parties are the receivers. A Dialog’s parties
are only its contributors.
from datetime import datetime, timezone
from vcon import Vcon, Session, Dialog
from vcon.party import Party
now = datetime.now(timezone.utc)
vcon = Vcon.build_new() # writes "vcon": "0.5.0"
vcon.add_party(Party(tel="+15551230001", name="Alice", role="customer"))
vcon.add_party(Party(tel="+15551230002", name="Bob", role="agent"))
session = vcon.add_session(Session(start=now, parties=[0, 1]))
first = vcon.add_dialog(Dialog(
type="text",
start=now,
parties=[0],
body="Hello, I need help with my account.",
encoding="none",
mediatype="text/plain",
), session=session)
is_valid, errors = vcon.is_valid()
print(is_valid, errors) # True []
vcon.save_to_file("conversation.vcon.json")
add_session(), add_dialog() and add_event() return the index of the
new object. add_dialog(..., session=i) also lists the Dialog in Session
i.
Dialog types
Core-05 has three Dialog types: recording, text and incomplete.
Audio and video are both recording Dialogs, told apart by mediatype.
Dialog(type="audio") and Dialog(type="video") still work, but they
raise a DeprecationWarning and build a recording.
vcon.add_dialog(Dialog(
type="recording",
start=now,
parties=[0, 1],
url="https://example.com/call.wav",
mediatype="audio/x-wav",
duration=95,
), session=session)
# A call that was not answered: no content, only a disposition
vcon.add_incomplete_dialog(start=now, disposition="no-answer", parties=[0])
# An empty Dialog Object keeps a position so no other index moves
vcon.add_dialog(Dialog.placeholder()) # serializes as {}
Parties
from vcon.civic_address import CivicAddress
vcon.add_party(Party(
name="Carol",
tel="+15551230003",
sip="sip:carol@example.com",
did="did:example:123456789abcdef",
timezone="America/New_York",
civicaddress=CivicAddress(country="US", a1="CA", a3="San Francisco"),
))
Sessions and Events
Events record what happened during a Session: joins, drops, holds, mutes, key
presses, call transfers and channel contributors. Each Event applies to the
Sessions in sessions.
from vcon import Event, SessionReference
vcon.add_event(Event(type="join", time=now, sessions=session, party=0))
vcon.add_event(Event(type="hold", time=now, sessions=session, party=0))
vcon.add_event(Event(type="keydown", time=now, sessions=session, party=1, button="5"))
# A blind transfer: `sessions` is the original call, `target_session` the
# call to the transfer target.
target = vcon.add_session(Session(start=now, parties=[1, 2]))
vcon.add_event(Event(type="blind-transfer", time=now, sessions=session, party=1,
transferee=0, transfer_target=2, target_session=target))
# Sessions can reference each other: child, peer, precursor or breakout
vcon.sessions[session]["sessions"] = [SessionReference(target, "peer").to_dict()]
Each Event type has a parameter table (core-05 section 4.3.1.5). Event(...)
raises ValueError when a required parameter is missing or a forbidden one is
present, and Vcon.is_valid() checks the same table for Events read from
JSON.
Attachments and analysis
An attachment needs party plus dialog or session. When you give
neither dialog nor session, the library uses the only Session if the
vCon has exactly one and raises ValueError otherwise.
vcon.add_attachment(
purpose="invoice",
body={"amount": 42},
encoding="json",
party=0,
session=session,
)
vcon.add_analysis(
type="sentiment",
vendor="example-vendor",
body={"sentiment": "positive"},
encoding="json",
dialog=first,
)
Tags are whole-vCon metadata. add_tag() lists every Session, and adds an
empty placeholder Session when the vCon has none. The tags attachment needs a
valid party (default 0, or pass party=), so add a party first; on a
vCon with no parties add_tag() warns, and from 1.1 it will raise.
vcon.add_tag("department", "billing")
print(vcon.get_tag("department")) # billing
Extensions
extensions must list every extension the vCon uses, and critical the
ones a reader must understand. The lawful basis and WTF helpers add their own
extension names.
from datetime import timedelta
vcon.add_lawful_basis_attachment(
lawful_basis="consent",
expiration=(now + timedelta(days=365)).isoformat(),
purpose_grants=[
{"purpose": "recording", "granted": True, "granted_at": now.isoformat()},
],
party_index=0,
session_index=session,
)
print(vcon.check_lawful_basis_permission("recording", party_index=0)) # True
print(vcon.get_extensions()) # ['lawful_basis']
Reading and validating
loaded = Vcon.load("conversation.vcon.json") # a path or an https URL
print(loaded.vcon) # 0.5.0
is_valid, errors = vcon.is_valid() # MUST-level rules
warnings = vcon.get_validation_warnings() # SHOULD-level findings
is_valid, errors = Vcon.validate_file("conversation.vcon.json")
Besides the structure and references, is_valid() checks that every
content_hash has the form <algorithm>-<unpadded base64url digest> and
the body of every lawful_basis attachment. A url without a
content_hash is reported by get_validation_warnings() in 1.0.x and
will be an error from 1.1. Loading keeps every value as written, including
timestamps, so an invalid created_at is reported by is_valid() rather
than raised.
Signing
sign() uses RS256 by default and accepts RSA, EC and Ed25519 keys (RS*,
PS*, ES* and EdDSA), as cryptography key objects or PEM. sign() and verify() reject the JWS
alg value "none" with AlgorithmNotPermittedError.
private_key, public_key = Vcon.generate_key_pair()
vcon.sign(private_key)
print(vcon.verify(public_key)) # True