Visual Voicemail (VVM)

OmniSEP provides a Visual Voicemail server implementing the OMTP VVM Specification v1.3 and GSMA TS.46. The VVM service enables smartphones to manage voicemail messages through an IMAP interface, with provisioning handled via SMS.

Architecture Overview

Provisioning Flow

VVM provisioning follows the OMTP specification state machine. When a device activates VVM, it sends an ACTIVATE SMS, receives credentials via STATUS SMS, then connects via IMAP.

Provisioning States

The VVM service tracks subscriber provisioning state per the OMTP specification:

State	Code	Description
Unknown	U	Initial state, no provisioning attempted
New	N	Account created, awaiting first client connection
Ready	R	Fully provisioned and operational
Provisioned	P	Credentials sent, awaiting client verification
Blocked	B	Service deactivated or suspended

SMS Protocol

STATUS Message (Server to Client)

Sent after activation to provide IMAP credentials:

//VVM:STATUS:st=R;rc=0;srv=vvm.example.com;ipt=993;spt=587;u=505010000000001@ims.example.com;pw=SecretPass123;tui=*86;dn=+61400000000;lang=eng.1;g_len=60;vs_len=60;pw_len=4-15;pm=N;gm=N;vtc=A

Field	Description
st	Provisioning state (R=Ready, B=Blocked, N=New, P=Provisioned, U=Unknown)
rc	Return code (0=success)
srv	IMAP server hostname
ipt	IMAP port
spt	SMTP port (if applicable)
u	Username (IMSI-based)
pw	Password
tui	TUI access number
dn	SMS destination number (for client replies)
lang	Language code
g_len	Maximum greeting length in seconds
vs_len	Maximum voice signature length in seconds
pw_len	PIN length range
pm	PIN required (Y/N)
gm	Greeting reset mode (G=greeting, V=voice signature, B=both, N=none)
vtc	Transcription capability (A=automatic, D=on-demand, B=both, N=none)

SYNC Message (Server to Client)

Sent when mailbox content changes:

//VVM:SYNC:ev=NM;id=123;c=5;t=v;s=+61400123456;dt=15/01/2024 10:30 +0000;l=30

Field	Description
ev	Event type (NM=new message, MBU=mailbox update, GU=greeting update)
id	Message ID
c	Unread message count
t	Message type (v=voice, o=video, f=fax, i=infotainment, e=ECC)
s	Sender number
dt	Deposit timestamp
l	Message length in seconds

ACTIVATE Message (Client to Server)

Sent by device to enable VVM:

Activate:pv=11;ct=samsung.SM-A536E.13

Field	Description
pv	Protocol version
ct	Client type (vendor.model.os_version)

DEACTIVATE Message (Client to Server)

Sent by device to disable VVM:

Deactivate:pv=11

IMAP Server

The VVM IMAP server implements a subset of IMAP4rev1 (RFC 3501) tailored for voicemail:

Supported Commands

Command	Description
CAPABILITY	List server capabilities
LOGIN	Authenticate with username/password
LOGOUT	End session
SELECT	Open mailbox (INBOX, Trash, Saved)
EXAMINE	Open mailbox read-only
LIST	List available mailboxes
STATUS	Get mailbox status (message counts)
FETCH	Retrieve message content
UID FETCH	Retrieve by UID
STORE	Update message flags
UID STORE	Update flags by UID
SEARCH	Search messages
UID SEARCH	Search by UID
COPY	Copy messages between mailboxes
EXPUNGE	Permanently delete flagged messages
CLOSE	Close mailbox and expunge
GETQUOTAROOT	Get storage quota
NOOP	Keep-alive

Capabilities

IMAP4rev1 AUTH=PLAIN AUTH=LOGIN UIDPLUS MOVE QUOTA

Mailbox Structure

Mailbox	Description
INBOX	New and read voicemail messages
Trash	Messages marked for deletion
Saved	Archived messages

Message Format

Voicemail messages are presented as RFC 5322 email with multipart MIME structure:

From: +61400123456 <voicemail@vvm.local>
To: 505010000000001@ims.example.com
Date: Sat, 25 Jan 2025 10:30:00 +0000
Subject: Voicemail from +61400123456
Message-ID: <123@vvm.omnisep>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----=_Part_0"
X-VVM-MsgType: voice
X-VVM-Duration: 30
X-VVM-Sender: +61400123456

------=_Part_0
Content-Type: text/plain; charset="UTF-8"

Voicemail from: +61400123456
Duration: 30 seconds

Transcription:
Hello, this is a test voicemail message.

------=_Part_0
Content-Type: audio/amr
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="voicemail.amr"

[Base64 encoded audio]
------=_Part_0--

Custom Headers

Header	Description
X-VVM-MsgType	Message type (voice, video, fax, infotainment, ecc)
X-VVM-Duration	Message duration in seconds
X-VVM-Sender	Original caller number

Configuration

Enabling VVM

# config/config.exs
config :omni_sep, :vvm,
  enabled: true,

  # IMAP server settings
  imap_port: 993,
  imap_ssl: true,
  imap_server: "vvm.example.com",
  imap_cert: "priv/cert/server.crt",
  imap_key: "priv/cert/server.key",

  # TUI (Traditional User Interface) number
  tui_number: "*86",

  # SMS settings
  sms_source_number: "+61400000000",
  sms_gateway: "https://sms-gateway.example.com/api/send",

  # PIN settings
  min_pin_length: 4,
  max_pin_length: 15,

  # Subscriber limits
  default_max_messages: 100,
  default_storage_limit_kb: 50_000,
  default_max_greeting_seconds: 60

Configuration Parameters

Parameter	Type	Required	Default	Description
enabled	Boolean	No	false	Enable VVM services
imap_port	Integer	No	993	IMAP server port
imap_ssl	Boolean	No	true	Enable TLS for IMAP connections
imap_server	String	Yes	-	IMAP server hostname (sent in STATUS SMS)
imap_cert	String	No	priv/cert/server.crt	Path to TLS certificate
imap_key	String	No	priv/cert/server.key	Path to TLS private key
smtp_port	Integer	No	587	SMTP port (future use)
tui_number	String	No	*86	TUI access number for legacy voicemail
sms_source_number	String	Yes	-	Source number for VVM SMS messages
sms_gateway	String	No	nil	SMS gateway HTTP endpoint
min_pin_length	Integer	No	4	Minimum PIN length
max_pin_length	Integer	No	15	Maximum PIN length
default_max_messages	Integer	No	100	Default message limit per subscriber
default_storage_limit_kb	Integer	No	50000	Default storage quota in KB
default_max_greeting_seconds	Integer	No	60	Maximum greeting duration

Development Configuration

For development, use plain IMAP (no TLS) for easier testing:

# config/dev.exs
config :omni_sep, :vvm,
  enabled: true,
  imap_port: 1430,
  imap_ssl: false,
  imap_server: "localhost",
  tui_number: "*86",
  sms_source_number: "+61400000000"

Production Configuration

# config/prod.exs
config :omni_sep, :vvm,
  enabled: true,
  imap_port: 993,
  imap_ssl: true,
  imap_server: "vvm.carrier.example.com",
  imap_cert: "/etc/omnisep/certs/vvm.crt",
  imap_key: "/etc/omnisep/certs/vvm.key",
  tui_number: "*86",
  sms_source_number: "+61400000001",
  sms_gateway: "https://smsc.carrier.example.com/api/v1/send"

Metrics

IMAP Session Metrics

Metric: vvm_imap_sessions_total Type: Counter Description: Total number of VVM IMAP sessions Labels:

• result - Session outcome: success, auth_failed, timeout

Metric: vvm_imap_active_sessions Type: Gauge Description: Number of currently active IMAP sessions

Metric: vvm_imap_commands_total Type: Counter Description: Total IMAP commands processed Labels:

• command - IMAP command: LOGIN, SELECT, FETCH, etc.
• result - Command result: ok, no, bad

Message Metrics

Metric: vvm_messages_total Type: Counter Description: Total VVM message operations Labels:

• operation - Operation type: deposit, read, delete, move

Metric: vvm_messages_stored Type: Gauge Description: Total number of voicemail messages currently stored

Metric: vvm_message_duration_seconds Type: Histogram Description: Duration of voicemail messages in seconds Buckets: 5, 10, 15, 30, 60, 120, 180, 300

SMS Metrics

Metric: vvm_sms_total Type: Counter Description: Total VVM SMS messages Labels:

• type - SMS type: status, sync, activate, deactivate
• result - Delivery result: success, failed, no_gateway

Account Metrics

Metric: vvm_accounts_total Type: Counter Description: VVM account operations Labels:

• operation - Operation: create, activate, deactivate, update
• result - Result: success, error

Metric: vvm_accounts_active Type: Gauge Description: Number of active VVM accounts

Example Prometheus Queries

# IMAP session rate
rate(vvm_imap_sessions_total[5m])

# Authentication failure rate
sum(rate(vvm_imap_sessions_total{result="auth_failed"}[5m]))
  / sum(rate(vvm_imap_sessions_total[5m]))

# Average message duration
histogram_quantile(0.5, rate(vvm_message_duration_seconds_bucket[5m]))

# SMS delivery success rate
sum(rate(vvm_sms_total{result="success"}[5m]))
  / sum(rate(vvm_sms_total[5m]))

# Active sessions over time
vvm_imap_active_sessions

Greeting Management

VVM supports multiple greeting types per subscriber:

Greeting Type	Description
normal	Standard personal greeting
busy	Played when subscriber is busy
extended_absence	Vacation or out-of-office greeting
voice_signature	Voice signature for name announcement

Greetings are stored and retrieved via the storage API. The IMAP server includes greeting metadata in the account quota response.

Troubleshooting

Client Cannot Activate VVM

Symptoms: Device shows "Visual Voicemail unavailable" or activation fails

Possible causes:

• SMS gateway not configured or unreachable
• Source number not whitelisted at SMSC
• VVM service disabled in configuration

Resolution:

1. Verify sms_gateway is configured and reachable
2. Check SMS gateway logs for delivery status
3. Confirm enabled: true in VVM configuration
4. Review metrics: vvm_sms_total{type="status"}

IMAP Authentication Failures

Symptoms: Client cannot connect after receiving STATUS SMS

Possible causes:

• Username/password mismatch
• TLS certificate issues
• Firewall blocking IMAP port

Resolution:

1. Verify credentials match between STATUS SMS and account storage
2. Check TLS certificate validity and trust chain
3. Confirm firewall allows traffic on configured IMAP port
4. Test with telnet/openssl: openssl s_client -connect vvm.example.com:993

Messages Not Syncing

Symptoms: New voicemails not appearing on device

Possible causes:

• SYNC SMS not being sent
• IMAP session disconnected
• Message deposit failing

Resolution:

1. Check vvm_sms_total{type="sync"} metrics
2. Verify SMS gateway connectivity
3. Check vvm_messages_total{operation="deposit"} for deposit failures
4. Review IMAP session metrics for disconnections

High Storage Usage

Symptoms: Subscribers hitting quota limits

Resolution:

1. Review quota settings: default_storage_limit_kb, default_max_messages
2. Check vvm_messages_stored gauge
3. Consider implementing automatic message expiration
4. Review greeting storage: get_greetings/1 returns audio sizes

References

• OMTP VVM Specification v1.3 - Visual Voicemail Interface Specification
• GSMA TS.46 - Visual Voicemail Interface Specification
• RFC 3501 - IMAP4rev1 Protocol
• RFC 5322 - Internet Message Format