Quick Installation

Quick Installation

Deploy ACSforMCS to Azure in minutes using either the Deploy to Azure button or release packages. This guide provides the fastest path to get your telephony integration running.

Installation Options

Option 1: Deploy to Azure (Recommended)

The easiest way to deploy ACSforMCS with an interactive Azure Portal interface:

What gets created:

• App Service Plan and Web App
• Key Vault with secure configuration
• Azure Communication Services
• Azure Cognitive Services (Speech)
• Application Insights (optional)

Prerequisites:

1. Microsoft Entra ID Object ID (required for Key Vault access):

   # Get your Object ID
   az ad signed-in-user show --query id -o tsv

   Note: The objectId property has been renamed to id in newer Azure CLI versions

2. Azure subscription with appropriate permissions

Configuration during deployment:

• Project Name: Base name for resources (3-15 characters)
• Environment: dev, test, stage, or prod
• Region: Choose optimal Azure region
• SKU: Free F1 (testing) or Standard S1 (production recommended)
• Phone Number: E.164 format (optional, can configure later)
• DirectLine Secret: From Copilot Studio (optional, can configure later)

Post-deployment steps:

1. Configure phone number and Event Grid (see Phone Number Configuration section below):

   • Get a phone number from Azure Communication Services
   • Configure Event Grid subscription to route calls to your web app
   • Set up webhook endpoint: https://your-app-name.azurewebsites.net/api/incomingCall

2. Configure Copilot Studio integration (see Copilot Studio Integration):

   • Get DirectLine secret from Settings → Security → Web Channel Security
   • Add DirectLine secret to Azure Key Vault
   • Design voice-friendly conversation topics

3. Use release package for Application Deployment:

   • Download the latest release package
   • Extract and run .\scripts\setup-configuration.ps1 to configure phone number and DirectLine secret
   • Run .\scripts\deploy-application.ps1 to deploy your application code

Optional Need detailed configuration guidance? See ARM Template Reference for complete technical details.

Option 2: Release Package Deployment

Download and deploy using pre-built packages with PowerShell automation:

Step 1: Download Release Package

1. Go to GitHub Releases
2. Download the latest release ZIP file
3. Extract to a local folder

Step 2: Create Azure Resources (if needed)

If you don't have Azure resources yet:

# Create all required Azure resources
.\scripts\create-azure-resources.ps1 -ApplicationName "myproject"

Step 3: Configure and Deploy

# Initialize configuration
.\scripts\setup-configuration.ps1

# Deploy application
.\scripts\deploy-application.ps1

Post-Deployment Configuration

After deployment, complete these essential steps:

Configure Phone Number and Event Grid

Get a phone number from your Azure Communication Services resource and configure event routing:

Get a Phone Number

1. Azure Portal → Communication Services → Your ACS resource
2. Phone Numbers → Get a number
3. Choose options:
   • Country/Region: Select your region
   • Number Type: Local or Toll-free
   • Use Case: Application-to-Person (A2P) for bot interactions
   • Calling: Enable "Make calls" and "Receive calls"
4. Search for available numbers and Add to cart
5. Purchase the selected number

Configure Event Grid Subscription

Route incoming calls to your ACSforMCS application:

1. Azure Portal → Communication Services → Your ACS resource
2. Events → Event Subscriptions → Create
3. Configure subscription:
   • Name: IncomingCallSubscription
   • Event Schema: Event Grid Schema
   • Event Types: Select only Microsoft.Communication.IncomingCall
   • Endpoint Type: Web Hook
   • Endpoint: https://your-app-name.azurewebsites.net/api/incomingCall
4. Create the subscription

Important Event Grid Settings

• Retry Policy: Set Max Event Delivery Attempts to 2
• Event Time to Live: Set to 1 minute (calls only ring for 30 seconds)
• Enable Logging: Configure diagnostic settings for troubleshooting

2. Set Up Copilot Studio Integration

Configure your bot for telephony:

1. Get DirectLine Secret from your Copilot Studio agent:
   • Go to Settings → Security → Web Channel Security
   • Copy one of the Secret Keys
2. Configure in Key Vault:

   az keyvault secret set --vault-name "your-keyvault" --name "DirectLineSecret" --value "your-secret"

See DirectLine Secret Configuration for detailed bot configuration.

3. Update Phone Number Configuration

Add your phone number to the application:

az keyvault secret set --vault-name "your-keyvault" --name "AgentPhoneNumber" --value "+1234567890"

Verification Steps

Test Basic Functionality

1. Check application status:

   • Visit: https://your-app-name.azurewebsites.net
   • Should see: "Hello Azure Communication Services, here is Copilot Studio!"

2. Verify configuration (Development mode):

   • Visit: https://your-app-name.azurewebsites.net/swagger
   • Use API key from Key Vault secret HealthCheckApiKey

3. Test phone integration:

   • Call your Azure Communication Services phone number
   • Should connect to your Copilot Studio agent

Monitor Call Activity

In Development mode, monitor active calls:

curl -H "X-API-Key: your-api-key" https://your-app-name.azurewebsites.net/health/calls

Environment Configuration

Development Mode (Default)

• Swagger documentation enabled at /swagger
• Health monitoring endpoints enabled
• Detailed logging for debugging
• API key protection for all monitoring endpoints

Production Mode

Switch to production for optimal performance:

.\scripts\switch-to-production.ps1
.\scripts\deploy-application.ps1

Production mode:

• Disables Swagger documentation
• Disables monitoring endpoints
• Optimizes logging for performance
• Reduces attack surface

Quick Command Reference

For New Projects

# 1. Create Azure resources
.\scripts\create-azure-resources.ps1 -ApplicationName "myapp"

# 2. Configure application
.\scripts\setup-configuration.ps1

# 3. Deploy
.\scripts\deploy-application.ps1

For Existing Resources

# 1. Configure with existing Key Vault
.\scripts\setup-configuration.ps1 -KeyVaultName "your-keyvault"

# 2. Deploy application
.\scripts\deploy-application.ps1

Environment Management

# Check current status
.\scripts\show-environment.ps1

# Switch to development (enables monitoring)
.\scripts\switch-to-development.ps1

# Switch to production (optimizes performance)  
.\scripts\switch-to-production.ps1

# Deploy after changes
.\scripts\deploy-application.ps1

Troubleshooting

Common Issues

"Unauthorized" accessing Swagger:

• Get API key: az keyvault secret show --vault-name "your-kv" --name "HealthCheckApiKey" --query value -o tsv
• Add header: X-API-Key: your-api-key

Phone calls not connecting:

• Verify Event Grid subscription: Check that subscription is active and pointing to correct endpoint
• Check webhook endpoint URL: Ensure URL format is https://your-app-name.azurewebsites.net/api/incomingCall
• Verify phone number capabilities: Ensure "Receive calls" is enabled for your phone number
• Test Event Grid delivery: Check Event Grid delivery logs in Azure portal
• Validate DirectLine secret: Ensure DirectLine secret is configured correctly in Key Vault

Phone number issues:

• Number not receiving calls: Verify number capabilities include "Receive calls"
• Event Grid delivery failures: Check diagnostic logs in Communication Services Events
• Webhook validation errors: Ensure your application handles EventGrid subscription validation

Configuration errors:

# Validate configuration
.\scripts\setup-configuration.ps1 -ValidateOnly

# Force reconfiguration
.\scripts\setup-configuration.ps1 -Force

Key Vault access denied:

# Get your Object ID and fix access
$objectId = az ad signed-in-user show --query id -o tsv
.\scripts\fix-keyvault-access.ps1 -KeyVaultName "kv-yourproject-prod" -UserObjectId $objectId

Azure CLI authentication:

az login
az account show

Performance Recommendations

For Production

• Use Standard S1 App Service Plan or higher
• Enable Application Insights for monitoring
• Use Production mode for optimal performance
• Configure auto-scaling based on call volume

For Development

• Basic B1 plan minimum for testing
• Keep Development mode enabled for debugging
• Use health endpoints for monitoring
• Enable detailed logging for troubleshooting

Security Considerations

• All sensitive configuration stored in Azure Key Vault
• RBAC permissions for Key Vault access
• API key protection for monitoring endpoints
• HTTPS only communication
• Managed Identity for Azure service authentication

Next Steps

1. Copilot Studio Integration: Configure your bot agents
2. Azure Development: Full development workflow
3. Local Development: Development with tunnels
4. Code Documentation: Technical implementation details

Support

• GitHub Issues
• Azure Communication Services Documentation
• Microsoft Copilot Studio Documentation

Ready to configure your bot? Proceed to DirectLine Secret Setup.