Voicemail Implementation Guide

This guide helps you select and deploy the right voicemail solution for your client. Understanding the difference between Base Experiences and Add-ons is critical for making the right choice.

Key Concept

Email notifications and transcription are add-ons, not voicemail types. They can be enabled on top of ANY base experience.

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                      VOICEMAIL ARCHITECTURE                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  STEP 1: Choose Base Experience (pick ONE)                         │
│  ┌─────────────────────┐    ┌─────────────────────────────────┐    │
│  │   Voicemail Only    │    │   Callback + Wait Experience    │    │
│  │                     │    │                                 │    │
│  │ Caller → Greeting   │    │ Caller → Queue → Options Menu   │    │
│  │       → Record      │    │       → (callback/voicemail/    │    │
│  │       → Hang up     │    │          stay) → Resolution     │    │
│  └─────────────────────┘    └─────────────────────────────────┘    │
│                                                                     │
│  STEP 2: Add Features (optional, can apply to EITHER base)         │
│  ┌─────────────────────┐    ┌─────────────────────────────────┐    │
│  │ Email Notifications │    │       Transcription             │    │
│  │                     │    │                                 │    │
│  │ Audio attachment    │    │ Audio → Text conversion         │    │
│  │ sent to staff email │    │ Appears in Flex + email         │    │
│  └─────────────────────┘    └─────────────────────────────────┘    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Step 1: Select Your Base Experience

Decision Chart

Question	Answer	Your Base Experience
Does the caller need options while waiting?	NO - Direct to voicemail	→ Voicemail Only
Does the caller need options while waiting?	YES - Queue with callback option	→ Callback + Wait

Base Experience: Voicemail Only

What callers experience:

Call comes in → Greeting plays → Record message → Hang up
No hold queue, no callback option, no waiting

Best for:

Dedicated voicemail lines (e.g., after-hours)
Overflow handling when all agents busy
Internal support lines (like Connie Care Team 877)
Organizations without real-time queue capability

Codebase feature:

voicemail-only-with-email/ (dedicated feature)
OR callback-and-voicemail-with-email?voicemailOnly=true (parameter approach)

Setup guide: → Voicemail-Only Configuration

Base Experience: Callback + Wait

What callers experience:

Call comes in → Enter queue with hold music
Press * anytime → Options menu (callback / voicemail / stay on hold)
Professional wait experience with caller choice

Best for:

Full-service lines where callers may want to wait
Organizations with agents available to take callbacks
High-volume lines needing caller options
Crisis hotlines with overflow needs

Codebase feature:

callback-and-voicemail/ (without email)
callback-and-voicemail-with-email/ (with email add-on)

Setup guide: → Callback + Wait Setup

Step 2: Select Your Add-ons

Add-ons enhance the base experience. They are independent of which base you choose.

Decision Chart: Email Notifications

Question	Answer	Action
Does staff need email alerts with audio attachment?	YES	→ Enable Email Add-on
Does staff need email alerts with audio attachment?	NO	→ Skip (voicemails in Flex only)

What it provides:

Instant email when voicemail recorded
Audio attachment (MP3) in email
Caller info (number, timestamp, duration)
Transcription in email body (if transcription add-on enabled)

Requirements:

Mailgun account and API key
DNS configuration for sending domain

Setup guide: → Email Notifications Add-on

Decision Chart: Transcription

Question	Answer	Action
Do you need voicemail audio converted to text?	YES	→ Enable Transcription
Do you need voicemail audio converted to text?	NO	→ Skip

What it provides:

Automatic audio-to-text conversion
Transcription appears in Flex task
Transcription included in email (if email add-on enabled)
Searchable message content

Requirements:

Twilio's built-in transcription (no additional account needed)
Proper transcribeCallback URL configuration

Setup guide: → Transcription Add-on

Common Configurations

Configuration Matrix

Use Case	Base Experience	Email	Transcription	Feature Directory
After-hours line, email alerts	Voicemail Only	Yes	Optional	`voicemail-only-with-email/`
After-hours line, Flex only	Voicemail Only	No	Optional	`callback-and-voicemail?voicemailOnly=true`
Full-service with email	Callback + Wait	Yes	Optional	`callback-and-voicemail-with-email/`
Full-service, Flex only	Callback + Wait	No	Optional	`callback-and-voicemail/`

Real-World Use Cases

Example 1: Nonprofit After-Hours Line

Scenario: Community food bank needs after-hours voicemail for donation inquiries

Decision	Choice	Reason
Base Experience	Voicemail Only	No agents available after-hours to receive callbacks
Email Add-on	Yes	Morning staff sees overnight messages in email
Transcription	Optional	Nice-to-have but not required

Result: Callers hear greeting → leave message → task created in Flex → email sent to admin

Example 2: Crisis Hotline Overflow

Scenario: Mental health org needs overflow when all counselors busy

Decision	Choice	Reason
Base Experience	Callback + Wait	Callers may want to wait for next available counselor
Email Add-on	Yes	Ensure no messages missed
Transcription	Yes	Quick triage without listening to full audio

Result: Caller enters queue → can request callback, leave voicemail, or stay on hold → all options documented

Example 3: Internal Support Line (Connie Care Team 877)

Scenario: Internal support for child accounts

Decision	Choice	Reason
Base Experience	Voicemail Only	All inquiries should be documented, no real-time queue needed
Email Add-on	Yes	Team needs immediate notification
Transcription	Yes	Quick review and routing

Result: Direct to voicemail → transcription in Flex task → email with audio and transcript

Example 4: Adding Second Line to Existing Account

Scenario: NSS already has callback-and-voicemail deployed, wants to add voicemail-only line

Decision	Choice	Reason
Approach	Parameter (`?voicemailOnly=true`)	Zero additional deployment, reuses existing infrastructure
Email Add-on	Uses existing	Same Mailgun configuration
Transcription	Uses existing	Same transcription setup

Result: New phone number → new Studio Flow → add parameter to URL → done

Deployment Checklist

Full Deployment Guide

For complete deployment instructions including troubleshooting and account setup, see the Account-Specific Deployment Guide.

For All Configurations

# 1. Ensure you're in the correct account directory
cd /path/to/connieRTC-basecamp/serverless-functions

# 2. Deploy serverless functions (CRITICAL: use deploy.sh, not npm run deploy)
./deploy.sh <account-name>

# 3. Verify deployment
twilio serverless:list --properties functionSid,friendlyName

Available accounts: nss, conniecareteam, hhovv, devsandbox

Account-Specific Deployment

WRONG: npm run deploy (uses default .env, may deploy to wrong account)

RIGHT: ./deploy.sh <account> (loads account-specific .env)

See Why This Matters for the incident that created this protocol.

Critical Technical Notes

When creating Studio Flows with TwiML redirect widgets:

// WRONG - This type doesn't exist
"type": "twiml-redirect"

// RIGHT - Use the correct type
"type": "add-twiml-redirect"

Workflow SID Variable

The environment variable for workflow is:

# CORRECT
TWILIO_FLEX_CALLBACK_WORKFLOW_SID=WW...

# NOT this (doesn't exist)
VOICEMAIL_WORKFLOW_SID=WW...

TranscriptionText Fetch

Twilio's transcribeCallback doesn't always include TranscriptionText in the payload. Your function must fetch it:

// If TranscriptionText is missing, fetch from TranscriptionUrl
if (!transcriptionText && event.TranscriptionUrl) {
  const response = await axios.get(event.TranscriptionUrl + '.json', {
    auth: {
      username: context.ACCOUNT_SID,
      password: context.AUTH_TOKEN
    }
  });
  transcriptionText = response.data.transcription_text;
}

Next Steps

Choose your base experience using the decision chart above
Select your add-ons based on client requirements
Follow the specific setup guide for your configuration
Test thoroughly before production deployment
Document the configuration for future reference

Quick Reference Links

Base Experiences

Add-ons

Email Provider Setup

Troubleshooting

Voice Troubleshooting

Professional Services

If you prefer to have our team handle the implementation, professional services are available for all voicemail configurations. Contact your Connie representative for details.

Architecture Overview​

Step 1: Select Your Base Experience​

Decision Chart​

Base Experience: Voicemail Only​

Base Experience: Callback + Wait​

Step 2: Select Your Add-ons​

Decision Chart: Email Notifications​

Decision Chart: Transcription​

Common Configurations​

Configuration Matrix​

Real-World Use Cases​

Example 1: Nonprofit After-Hours Line​

Example 2: Crisis Hotline Overflow​

Example 3: Internal Support Line (Connie Care Team 877)​

Example 4: Adding Second Line to Existing Account​

Deployment Checklist​

For All Configurations​

Critical Technical Notes​

Studio Flow Widget Type​

Workflow SID Variable​

TranscriptionText Fetch​

Next Steps​

Quick Reference Links​

Base Experiences​

Add-ons​

Email Provider Setup​

Troubleshooting​