Switchvox PBX Webhook Integration

This document describes the integration between Switchvox PBX Event Triggers and the Heatwave CRM.

Overview

Switchvox can send HTTP POST requests (webhooks) when certain PBX events occur. We use this for:

1. Voicemail Transcription - When a voicemail is left, we receive notification and transcribe it
2. Future: Screen Pop - When a call arrives, pop the customer record in CRM
3. Future: Call Analytics - Track call metrics and outcomes

Architecture

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  Switchvox PBX  │──────│  Webhook/Email  │──────│   Heatwave CRM  │
└─────────────────┘      └─────────────────┘      └─────────────────┘
        │                        │                        │
        │  Event Trigger         │                        │
        │  (On New Voicemail)    │                        │
        ├───────────────────────►│                        │
        │  POST /webhooks/v1/    │  WebhookLog + Worker   │
        │  switchvox             ├───────────────────────►│
        │                        │                        │
        │  Email with WAV        │                        │
        ├───────────────────────►│  Action Mailbox        │
        │  voicemail@wy.com      ├───────────────────────►│
        │                        │                        │
        │                        │   CallRecord created   │
        │                        │   + Transcription      │
        │                        │   queued               │
        └────────────────────────┴────────────────────────┘

Voicemail Flow

1. Caller leaves voicemail on employee’s extension
2. Switchvox sends webhook to /webhooks/v1/switchvox with metadata (caller ID, duration, mailbox)
3. Switchvox emails voicemail with WAV attachment to voicemail@warmlyyours.com
4. Action Mailbox (VoicemailsMailbox) receives email, extracts WAV
5. CallRecord created with call_outcome: :voicemail
6. Transcription queued via CallRecordTranscriptionWorker
7. AI analysis runs: transcription → summary → embeddings

Setup Instructions

1. Configure Switchvox Event Triggers

In Switchvox Admin UI:

1. Go to Setup → Event Triggers
2. You can set a System Default URL or configure individual event URLs
3. Use the URL Variables dropdown and Append button to add variables using %VARIABLE_NAME% syntax

Available Variables

Variable	Description
CALLER_ID_NAME	Caller’s name
CALLER_ID_NUMBER	Caller’s phone number
DIALED_NUMBER	Number that was dialed
EVENT_TYPE	Type of event
EXTENSION	Extension number
EXTENSION_TYPE	Type of extension
FEATURE_DATA	Additional feature data
INCOMING_DID	DID number called
JOB_ID	Unique job identifier
QUEUES	Queue IDs
VM_DATE	Voicemail timestamp
VM_DUR	Voicemail duration (seconds)
VM_MAILBOX	Mailbox/extension number
VM_MSGNUM	Voicemail message number

Recommended URL for “On New Voicemail Event URL”

https://api.warmlyyours.com/webhooks/v1/switchvox?token=YOUR_TOKEN&EVENT_TYPE=new_voicemail&VM_MAILBOX=%VM_MAILBOX%&VM_DUR=%VM_DUR%&VM_MSGNUM=%VM_MSGNUM%&VM_DATE=%VM_DATE%&CALLER_ID_NUMBER=%CALLER_ID_NUMBER%&CALLER_ID_NAME=%CALLER_ID_NAME%

Or use the URL Variables dropdown to append each variable one by one.

Other Useful Event URLs (Future)

On Incoming Call Event URL (for screen pop):

https://api.warmlyyours.com/webhooks/v1/switchvox?token=YOUR_TOKEN&EVENT_TYPE=incoming_call&CALLER_ID_NUMBER=%CALLER_ID_NUMBER%&CALLER_ID_NAME=%CALLER_ID_NAME%&EXTENSION=%EXTENSION%&INCOMING_DID=%INCOMING_DID%&QUEUES=%QUEUES%

On Call Hangup Event URL (for analytics):

https://api.warmlyyours.com/webhooks/v1/switchvox?token=YOUR_TOKEN&EVENT_TYPE=call_hangup&CALLER_ID_NUMBER=%CALLER_ID_NUMBER%&EXTENSION=%EXTENSION%&JOB_ID=%JOB_ID%

2. Configure Voicemail Email Forwarding

In Switchvox Admin UI for each extension:

1. Go to User Suite → Voicemail & Fax → Notifications
2. Enable Email Notification for new voicemails
3. Set email to: voicemail@warmlyyours.com (or voicemail+{extension}@warmlyyours.com)
4. Enable Attach Voicemail as WAV file

Or configure globally via Admin → Voicemail Settings.

3. Configure Heatwave Credentials

The webhook token is stored in Rails credentials under switchvox.webhook_token:

# In credentials.yml.enc (edit with: rails credentials:edit)
switchvox:
  host: 'p.lz.warmlyyours.net'
  username: 'admin'
  password: 'your_password'
  webhook_token: 'your_secure_token'  # Generate with: SecureRandom.hex(32)

Access via: Heatwave::Configuration.fetch(:switchvox, :webhook_token)

Optionally, configure IP whitelist as an alternative to token auth:

# In Rails console - supports individual IPs and CIDR notation
Setting.switchvox_webhook_ips = ['127.0.0.1', '144.202.57.170', '10.0.0.0/8']

# Initial values seeded via migration (db/migrate/*_seed_switchvox_webhook_ips.rb):
# ['127.0.0.1', '144.202.57.170']

# Validate IPs before saving
invalid = Setting.validate_switchvox_webhook_ips(['192.168.1.1', 'invalid'])
# => ["invalid"]

# Check if IP is in whitelist (used by controller)
Setting.ip_in_switchvox_whitelist?('144.202.57.170')  # => true
Setting.ip_in_switchvox_whitelist?('10.0.0.5')        # => true (if 10.0.0.0/8 in list)

# Empty whitelist = no IP restriction (allows all IPs, rely on token auth)
Setting.switchvox_webhook_ips = []
Setting.ip_in_switchvox_whitelist?('8.8.8.8')         # => true

Note: This setting requires admin role to modify (enforced via CanCanCan).

4. Configure SendGrid Inbound Parse

Ensure voicemail@warmlyyours.com is routed to Action Mailbox:

1. In SendGrid → Settings → Inbound Parse
2. Add domain/subdomain if not already configured
3. URL: https://api.warmlyyours.com/rails/action_mailbox/sendgrid/inbound_emails

Event Variables by Event Type

On New Voicemail

Variable	Description	Example
VM_MAILBOX	Extension/mailbox number	801
VM_DUR	Duration in seconds	45
VM_MSGNUM	Message sequence number	15
VM_DATE	Timestamp	2025-01-21 14:30:00
CALLER_ID_NUMBER	Caller’s phone number	+18005551234
CALLER_ID_NAME	Caller’s name (if available)	John Doe

On Incoming Call

Variable	Description
CALLER_ID_NUMBER	Caller’s phone number
CALLER_ID_NAME	Caller’s name
DIALED_NUMBER	Number the caller dialed
EXTENSION	Destination extension
EXTENSION_TYPE	Type of extension (sip, queue, ivr, etc.)
INCOMING_DID	DID number called
QUEUES	Queue IDs if routed to queue
JOB_ID	Unique call identifier

On Call Answered / On Call Hangup

Variable	Description
CALLER_ID_NUMBER	Caller’s phone number
CALLER_ID_NAME	Caller’s name
EXTENSION	Extension that handled the call
JOB_ID	Unique call identifier
FEATURE_DATA	Additional call data

On Agent Logged In / Out

Variable	Description
EXTENSION	Agent’s extension
QUEUES	Queue IDs agent logged into/out of

Testing

Test Webhook Endpoint

Note: Switchvox sends GET requests with parameters in the URL. The endpoint accepts both GET and POST.

# With token auth (GET - how Switchvox sends it)
curl "https://api.warmlyyours.me:3000/webhooks/v1/switchvox?token=YOUR_TOKEN&EVENT_TYPE=agent_login&EXTENSION=801&QUEUES=1280"

# Or with POST
curl -X POST "https://api.warmlyyours.me:3000/webhooks/v1/switchvox?token=YOUR_TOKEN" \
  -d "EVENT_TYPE=new_voicemail" \
  -d "VM_MAILBOX=801" \
  -d "VM_DUR=30" \
  -d "VM_MSGNUM=1" \
  -d "CALLER_ID_NUMBER=+18005551234" \
  -d "CALLER_ID_NAME=Test Caller"

Test Action Mailbox

1. Go to: https://api.warmlyyours.me:3000/rails/conductor/action_mailbox/inbound_emails
2. Create new inbound email
3. Set recipient to voicemail@warmlyyours.com
4. Attach a WAV file
5. Submit and verify CallRecord is created

Verify Processing

# Check recent webhook logs
WebhookLog.where(provider: 'switchvox').recent.order(created_at: :desc)

# Check recent voicemail call records
CallRecord.where(call_outcome: :voicemail).recent.order(created_at: :desc)

# Check transcription status
CallRecord.where(call_outcome: :voicemail).transcription_eligible

Troubleshooting

Webhook Not Received

1. Check Switchvox Event Trigger is enabled
2. Verify URL is accessible from Switchvox server
3. Check webhook token matches Setting.switchvox_webhook_token
4. Check WebhookLog for failed entries: WebhookLog.where(provider: 'switchvox', state: 'exception')

Email Not Processed

1. Check Action Mailbox inbound emails: ActionMailbox::InboundEmail.recent
2. Verify SendGrid Inbound Parse is configured
3. Check for failed mailbox processing: ActionMailbox::InboundEmail.failed
4. Reprocess failed: VoicemailsMailbox.new(ActionMailbox::InboundEmail.find(ID)).process

Transcription Not Running

1. Check CallRecord has audio: call_record.upload.present?
2. Check duration: call_record.duration_secs >= 30 (minimum for transcription)
3. Manually queue: CallRecordTranscriptionWorker.perform_async(call_record_id: ID)
4. Check Sidekiq for errors in ai_embeddings queue

Files

File	Purpose
app/mailboxes/voicemails_mailbox.rb	Action Mailbox for voicemail emails
app/controllers/webhooks/v1/switchvox_controller.rb	Webhook endpoint
app/services/webhook_processors/switchvox_processor.rb	Webhook processing logic
app/services/call_record_processing/transcription_service.rb	AI transcription
app/workers/call_record_transcription_worker.rb	Background transcription worker
app/controllers/crm/phone_popup_controller.rb	Call Pop Up screen pop
app/views/crm/phone_popup/show.html.erb	Call Pop Up view

Call Pop Up (Screen Pop)

The Switchvox phone client can open a URL when a call rings, showing caller information in the CRM.

Configuration in Switchvox

1. Go to Admin → Phone System → Event Triggers → Call Pop Up Settings
2. Enable Call Pop Up
3. Set Pop Up When to “Ringing Call”
4. Set the URL:

https://crm.warmlyyours.com/phone/popup?number=%CALLER_ID_NUMBER%&name=%CALLER_ID_NAME%&did=%INCOMING_DID%

For local testing:

https://crm.warmlyyours.me:3000/phone/popup?number=%CALLER_ID_NUMBER%&name=%CALLER_ID_NAME%&did=%INCOMING_DID%

Available Variables

Variable	Description
%CALLER_ID_NUMBER%	Caller’s phone number
%CALLER_ID_NAME%	Caller’s name (if available)
%INCOMING_DID%	The DID that was called (e.g., 1-800-875-5285)

What the Pop Up Shows

• Caller Information - Name, phone number, incoming DID
• CRM Matches - Customers/contacts matching the phone number
• Quick Actions - Open customer, start new quote
• Recent Orders - Last 5 orders for matched customer
• Recent Quotes - Last 5 quotes for matched parties
• Call History - Recent calls from this number

Endpoint

GET https://crm.warmlyyours.com/phone/popup

Controller: Crm::PhonePopupController#show

Future Enhancements

1. WebSocket Screen Pop - Use incoming_call webhook + ActionCable to push notification even when CRM isn’t focused
2. Call Analytics - Track call_hangup events for duration, queue wait times
3. Agent Status Sync - Sync agent login/logout with EmployeePhoneStatus
4. Realtime API - WebSocket integration for live call status dashboard