Callback + Wait Experience Setup

This guide covers implementing Callback + Wait - the base experience where callers enter a queue and can choose between callback, voicemail, or staying on hold.

Base Experience

This is a base experience, not an add-on. Email notifications and transcription can be added to this experience. See Implementation Guide for the full architecture.

What Callers Experience

Caller → Queue with Hold Music
         ↓
     Press * anytime
         ↓
┌────────────────────────────────────────┐
│         Options Menu                   │
├────────────────────────────────────────┤
│ 1. Request callback (keep place)       │
│ 2. Leave voicemail                     │
│ 3. Stay on hold                        │
└────────────────────────────────────────┘
         ↓
     Resolution (agent, callback, or voicemail)

Choose Your Feature

Need Email/Transcription?	Feature Directory	Use This
No - Flex only	`callback-and-voicemail/`	Simpler setup
Yes - Email notifications	`callback-and-voicemail-with-email/`	Full features

Setup: callback-and-voicemail (No Email)

For Human Developers

Step 1: Prepare Environment

Navigate to serverless-functions/ directory

Create or update .env file with:

ACCOUNT_SID=AC...
AUTH_TOKEN=...
TWILIO_FLEX_CALLBACK_WORKFLOW_SID=WW...

Step 2: Enable Feature

Open serverless-functions/src/assets/features/features.json

Ensure callback_and_voicemail is enabled:

{
  "callback_and_voicemail": {
    "enabled": true,
    "allow_requeue": true,
    "max_attempts": 3,
    "auto_select_task": false
  }
}

Step 3: Deploy

Open terminal in serverless-functions/
Deploy to your account:
```
./deploy.sh <account-name>
```
Note the deployed domain

Step 4: Configure Studio Flow

Navigate to Twilio Console → Studio → Flows
Open your voice flow (or create new)

In the Send to ConnieRTC widget:

Hold Music TwiML URL:

https://[YOUR-DOMAIN]/features/callback-and-voicemail/studio/wait-experience

Step 5: Test

Call the number
Verify you hear hold music
Press * to hear options
Test each option (callback, voicemail, stay on hold)

For AI Agents

Prerequisites Check

# Verify directory
pwd
# Expected: /path/to/connieRTC-basecamp

# Check environment
cat serverless-functions/.env | grep -E "ACCOUNT_SID|WORKFLOW"

Deploy

cd serverless-functions

# Enable feature in features.json
cat src/assets/features/features.json | jq '.callback_and_voicemail.enabled = true' > tmp.json && mv tmp.json src/assets/features/features.json

# Deploy
./deploy.sh <account-name>

# Get deployed domain
DEPLOYED_DOMAIN=$(twilio serverless:list --properties domainName -o json | jq -r '.[0].domainName')
echo "Deployed: $DEPLOYED_DOMAIN"

Update Studio Flow

# Get current flow
FLOW_SID="FW..."

# Update flow with new hold music URL
# (This typically requires updating the flow JSON and re-publishing)

Setup: callback-and-voicemail-with-email (Full Features)

For Human Developers

Step 1: Prepare Environment

Navigate to serverless-functions/ directory

Create or update .env file with all variables:

ACCOUNT_SID=AC...
AUTH_TOKEN=...
TWILIO_FLEX_CALLBACK_WORKFLOW_SID=WW...
MAILGUN_API_KEY=...  (must be SENDING key, not private key)
MAILGUN_DOMAIN=voicemail.yourorg.com
NOTIFICATION_EMAIL=admin@yourorg.com

Step 2: Set Up Mailgun

Follow the detailed Mailgun setup in Email Notifications Add-on:

Create Mailgun account
Add sending domain (e.g., voicemail.yourorg.com)
Configure DNS records
Get domain-specific sending key (NOT the private API key)
Test API connectivity

Step 3: Enable Feature

Open serverless-functions/src/assets/features/features.json

Enable the feature:

{
  "callback_and_voicemail": {
    "enabled": true,
    "allow_requeue": true,
    "max_attempts": 3,
    "auto_select_task": false
  }
}

Step 4: Deploy

./deploy.sh <account-name>

Step 5: Configure Studio Flow

In your Studio Flow's Send to ConnieRTC widget:

Hold Music TwiML URL:

https://[YOUR-DOMAIN]/features/callback-and-voicemail-with-email/studio/wait-experience

Step 6: Test

Call the number
Press * and select voicemail option
Leave a test message
Verify:
- Task appears in Flex
- Email received with audio attachment
- Transcription appears (if enabled)

For AI Agents

Prerequisites Check

# Verify Mailgun configuration
cat serverless-functions/.env | grep MAILGUN

# Test Mailgun API
MAILGUN_API_KEY=$(grep MAILGUN_API_KEY serverless-functions/.env | cut -d= -f2)
MAILGUN_DOMAIN=$(grep MAILGUN_DOMAIN serverless-functions/.env | cut -d= -f2)

curl -s -w "\nHTTP Status: %{http_code}\n" \
  --user "api:$MAILGUN_API_KEY" \
  "https://api.mailgun.net/v3/$MAILGUN_DOMAIN/messages" \
  -F from="test@$MAILGUN_DOMAIN" \
  -F to="test@example.com" \
  -F subject="API Test" \
  -F text="Test message"

Deploy

cd serverless-functions

# Verify features enabled
cat src/assets/features/features.json | jq '.callback_and_voicemail'

# Deploy with email feature
./deploy.sh <account-name>

# Capture domain
DEPLOYED_DOMAIN=$(twilio serverless:list --properties domainName -o json | jq -r '.[0].domainName')
echo "Wait Experience URL: https://$DEPLOYED_DOMAIN/features/callback-and-voicemail-with-email/studio/wait-experience"

Verify Deployment

# List functions to verify deployment
twilio serverless:list --properties functionSid,friendlyName | grep -i voicemail

# Check function logs for errors
twilio debugger:logs:list --log-level error

Configuration Options

Callback Behavior

{
  "callback_and_voicemail": {
    "enabled": true,
    "allow_requeue": true,      // Allow multiple callback attempts
    "max_attempts": 3,          // Maximum callback attempts
    "auto_select_task": false   // Auto-assign to available agent
  }
}

Hold Music

The default hold music plays while caller waits. To customize:

Create a custom TwiML Bin with your hold music
Update the wait-experience function to use your music URL

Enabling Add-ons

Email Notifications

Already included in callback-and-voicemail-with-email. Ensure Mailgun is configured.

For callback-and-voicemail (no email built-in), you would need to:

Add Mailgun configuration to environment
Modify the voicemail submission function

See: Email Notifications Add-on

Transcription

Enable in the recording configuration within the feature:

const recordingConfig = {
  transcribe: true,
  transcription_callback: `https://${context.DOMAIN_NAME}/features/callback-and-voicemail-with-email/studio/transcription-handler`
};

See: Transcription Add-on

Troubleshooting

Verify the wait-experience URL is correct
Check function logs for errors
Ensure the Studio Flow is using the correct widget type

Callbacks Not Working

Verify TWILIO_FLEX_CALLBACK_WORKFLOW_SID is correct
Check TaskRouter workspace is active
Ensure agents are available to receive callbacks

Voicemails Not Appearing in Flex

Check function logs for task creation errors
Verify workflow SID is correct
Ensure voice channel is configured

Emails Not Sending

See Email Notifications troubleshooting

Common issues:

Using private API key instead of sending key
DNS not verified
Domain not matching configured domain

Flow Diagram

┌─────────────────────────────────────────────────────────────────┐
│                    CALLBACK + WAIT FLOW                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────┐   ┌──────────────┐   ┌─────────────────────┐     │
│  │ Incoming │ → │ Studio Flow  │ → │ Send to ConnieRTC   │     │
│  │   Call   │   │              │   │ (Hold Music URL)    │     │
│  └──────────┘   └──────────────┘   └─────────────────────┘     │
│                                              ↓                  │
│                                    ┌─────────────────────┐     │
│                                    │  wait-experience    │     │
│                                    │  (serverless fn)    │     │
│                                    └─────────────────────┘     │
│                                              ↓                  │
│                     ┌────────────────────────┼────────────────┐ │
│                     ↓                        ↓                ↓ │
│            ┌──────────────┐        ┌──────────────┐   ┌──────┐ │
│            │   Callback   │        │   Voicemail  │   │ Wait │ │
│            │   Request    │        │   Recording  │   │      │ │
│            └──────────────┘        └──────────────┘   └──────┘ │
│                     ↓                        ↓                  │
│            ┌──────────────┐        ┌──────────────┐            │
│            │  Task in     │        │  Task +      │            │
│            │  Flex        │        │  Email       │            │
│            └──────────────┘        └──────────────┘            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Implementation Guide - Architecture overview
Voicemail-Only Configuration - Direct-to-voicemail setup
Account-Specific Deployment - Deployment protocol
Email Notifications - Email add-on
Transcription - Transcription add-on
Mailgun Setup - Detailed Mailgun configuration

What Callers Experience​

Choose Your Feature​

Setup: callback-and-voicemail (No Email)​

For Human Developers​

Step 1: Prepare Environment​

Step 2: Enable Feature​

Step 3: Deploy​

Step 4: Configure Studio Flow​

Step 5: Test​

For AI Agents​

Prerequisites Check​

Deploy​

Update Studio Flow​

Setup: callback-and-voicemail-with-email (Full Features)​

For Human Developers​

Step 1: Prepare Environment​

Step 2: Set Up Mailgun​

Step 3: Enable Feature​

Step 4: Deploy​

Step 5: Configure Studio Flow​

Step 6: Test​

For AI Agents​

Prerequisites Check​

Deploy​

Verify Deployment​

Configuration Options​

Callback Behavior​

Hold Music​

Enabling Add-ons​

Email Notifications​

Transcription​

Troubleshooting​

No Options Menu After Pressing *​

Callbacks Not Working​

Voicemails Not Appearing in Flex​

Emails Not Sending​

Flow Diagram​

Related Documentation​

What Callers Experience

Choose Your Feature

Setup: callback-and-voicemail (No Email)

For Human Developers

Step 1: Prepare Environment

Step 2: Enable Feature

Step 3: Deploy

Step 4: Configure Studio Flow

Step 5: Test

For AI Agents

Prerequisites Check

Deploy

Update Studio Flow

Setup: callback-and-voicemail-with-email (Full Features)

For Human Developers

Step 1: Prepare Environment

Step 2: Set Up Mailgun

Step 3: Enable Feature

Step 4: Deploy

Step 5: Configure Studio Flow

Step 6: Test

For AI Agents

Prerequisites Check

Deploy

Verify Deployment

Configuration Options

Callback Behavior

Hold Music

Enabling Add-ons

Email Notifications

Transcription

Troubleshooting

No Options Menu After Pressing *

Callbacks Not Working

Voicemails Not Appearing in Flex

Emails Not Sending

Flow Diagram

Related Documentation