SIPHON logo

Call Data

Call Data

SIPHON can automatically capture and persist call artifacts during a call:

  • Recordings (audio)
  • Call metadata (direction, phone numbers, trunks, timing, status, etc.)
  • Call transcriptions (conversation history)

These features run inside the agent worker process, so they work for both inbound and outbound calls.

Enable / disable

Call data features are controlled by environment variables read by the agent worker.

  • CALL_RECORDING (default false)
    • When true, SIPHON starts recording (egress) and saves it to S3 compatible storage.
  • SAVE_METADATA (default false)
    • When true, SIPHON saves a per-call metadata JSON payload using the configured storage backend.
  • SAVE_TRANSCRIPTION (default false)
    • When true, SIPHON collects conversation items and saves a transcription JSON payload using the configured storage backend.
  • HANGUP_CALL (default true)
    • When false, the hangup tool becomes a no-op. Recording/metadata saving still happens on normal call exit.

Timezone

SIPHON uses the TIMEZONE environment variable to format timestamps for call artifacts.

  • If TIMEZONE is set to a valid IANA timezone name (for example Asia/Kolkata, UTC, America/New_York), SIPHON uses it when writing:
    • metadata start_time / end_time
    • transcription message timestamps
    • folder/file timestamps used for local/S3 paths
  • If TIMEZONE is not set (or invalid), SIPHON falls back to local time.

Recordings

When CALL_RECORDING=true, SIPHON starts a room composite recording shortly after the agent joins the room.

  • Output format: .ogg (audio-only)
  • Layout: speaker
  • Storage: S3-compatible object storage (AWS S3 or MinIO)

Required S3 / MinIO configuration

Set these environment variables in the environment where the agent worker runs:

  • AWS_S3_BUCKET or MINIO_BUCKET
  • AWS_S3_ACCESS_KEY_ID or MINIO_ACCESS_KEY
  • AWS_S3_SECRET_ACCESS_KEY or MINIO_SECRET_KEY

Optional:

  • AWS_S3_ENDPOINT
    • Useful for MinIO (example: http://localhost:9000)
  • AWS_S3_REGION (default us-east-1)
  • AWS_S3_FORCE_PATH_STYLE (default false)

Where recordings are written

SIPHON generates a per-call key using the room name and a timestamp:

  • Folder: <room_name>/<timestamp>/
  • File: call_<room_name>_<timestamp>.ogg

The recording is written to:

  • s3://<bucket>/<folder>/<file>

Metadata

When SAVE_METADATA=true, SIPHON writes a metadata payload for each call. This includes:

  • room_name
  • call_direction (inbound or outbound)
  • inbound_trunk_id / outbound_trunk_id (if available)
  • agent_number
  • user_number
  • Timing:
    • start_time
    • end_time
    • duration
    • timezone
  • Status:
    • answered (true / false)
    • status (for example: completed, failed, aborted, limit_reached, or unanswered reasons)
  • recording_filename (when a recording exists)

Configure metadata storage

Metadata storage is configured via:

  • METADATA_LOCATION (default Call_Metadata)

Supported values:

  • s3
    • Saves metadata JSON to the configured S3/MinIO bucket.
  • A database URL
    • MongoDB: mongodb://... or mongodb+srv://...
    • Redis: redis://... or rediss://...
    • Postgres: postgres://... or postgresql://...
    • MySQL: mysql://... or mysql+pymysql://...
  • Any other string
    • Treated as a local folder path.

Where metadata is written

  • Local: <METADATA_LOCATION>/<room_name>/<timestamp>/call_metadata_<room_name>_<timestamp>.json
  • S3: s3://<bucket>/<room_name>/<timestamp>/call_metadata_<room_name>_<timestamp>.json

If a recording exists, SIPHON will try to keep metadata alongside the recording in the same S3 “folder”.

Transcription

When SAVE_TRANSCRIPTION=true, SIPHON collects the conversation history during the call and saves it as JSON.

The payload shape is:

  • {"conversation": [{"role": "user" | "assistant", "content": "...", "interrupted": false, "timestamp": "..."}, ...]}

Configure transcription storage

Transcription storage is configured via:

  • TRANSCRIPTION_LOCATION (default Transcriptions)

Supported values match metadata storage:

  • s3
  • Database URLs (mongodb://..., redis://..., postgres://..., mysql://...)
  • Any local folder path

Where transcriptions are written

  • Local: <TRANSCRIPTION_LOCATION>/<room_name>/<timestamp>/call_transcription_<room_name>_<timestamp>.json
  • S3: s3://<bucket>/<room_name>/<timestamp>/call_transcription_<room_name>_<timestamp>.json

Unanswered calls

SIPHON treats calls that were never actually answered differently:

  • Any in-progress recording is stopped and discarded (deleted from S3/MinIO)
  • Metadata is still saved, but marked as unanswered (answered=false) and without a recording filename
  • Normal “on exit” persistence is skipped to avoid saving a second, conflicting record

Example worker .env

# Enable features
CALL_RECORDING=true
SAVE_METADATA=true
SAVE_TRANSCRIPTION=true

# Timestamp formatting
TIMEZONE=Asia/Kolkata

# Where to store call data
METADATA_LOCATION=Call_Metadata
TRANSCRIPTION_LOCATION=Transcriptions

# S3 / MinIO (for recordings, and for metadata/transcriptions when location is "s3")
AWS_S3_ENDPOINT=http://localhost:9000
AWS_S3_BUCKET=siphon
AWS_S3_ACCESS_KEY_ID=minioadmin
AWS_S3_SECRET_ACCESS_KEY=minioadmin
AWS_S3_REGION=us-east-1
AWS_S3_FORCE_PATH_STYLE=true

Next