Copilot Studio Integration

Copilot Studio Integration

This guide shows you how to configure your Microsoft Copilot Studio agents to work with ACSforMCS for voice-based phone conversations.

Overview

To enable phone calls for your Copilot Studio agent, you need to:

1. Get the DirectLine secret from Web Channel Security settings
2. Configure voice-friendly conversation topics
3. Set up call transfer functionality (optional)
4. Test the integration

Prerequisites

• A published Microsoft Copilot Studio Agent (not a classic Bot Framework bot)
• Administrative access to your Copilot Studio environment
• ACSforMCS already deployed to Azure (see Quick Installation)

Step 1: Get DirectLine Secret {#get-directline-secret}

The DirectLine secret allows ACSforMCS to communicate with your Copilot Studio agent via API.

Access Copilot Studio

1. Go to Microsoft Copilot Studio
2. Sign in with your organizational account
3. Select your environment (if prompted)

Select Your Agent

1. From the main dashboard, select Agents
2. Choose the agent you want to enable for voice calls

Get DirectLine Secret

1. In your agent, go to Settings → Security
2. Navigate to Web Channel Security section
3. In the Web Channel Security configuration:
   • Copy one of the Secret Keys (this is your DirectLine Secret)
   • You can use either of the available secret keys

Security Notes

• The Web Channel Security provides up to 2 secret keys for key rotation
• Keep the DirectLine secret secure - treat it like a password
• Consider regenerating keys periodically for security
• No additional channel configuration is required - DirectLine access is enabled by default

Step 2: Configure DirectLine Secret in Azure

Add the DirectLine secret to your Azure Key Vault so ACSforMCS can authenticate with your agent.

Using Azure CLI

az keyvault secret set \
    --vault-name "your-keyvault-name" \
    --name "DirectLineSecret" \
    --value "YOUR-COPILOT-STUDIO-DIRECTLINE-SECRET"

Using Azure Portal

1. Go to Azure Portal → Key Vaults → Your Key Vault
2. Select Secrets → Generate/Import
3. Name: DirectLineSecret
4. Value: Your DirectLine secret from Copilot Studio
5. Click Create

Using PowerShell Scripts

If using ACSforMCS deployment scripts:

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

# Or direct secret population
.\scripts\populate-keyvault-secrets.ps1 -KeyVaultName "your-kv" -DirectLineSecret "your-secret"

Step 3: Design Voice-Friendly Content

Voice conversations have different requirements than text-based chats. Design your agent topics with these considerations:

Conversation Design Best Practices

Keep Responses Concise

• Limit responses to 1-2 sentences when possible
• Long responses can lose caller attention
• Break complex information into multiple exchanges

Use Natural Speech Patterns

• Write responses as you would speak them
• Avoid technical jargon and abbreviations
• Use conversational tone and natural phrasing

Provide Clear Options

• Offer specific choices: "You can say 'billing', 'support', or 'hours'"
• Avoid long lists of options in a single response
• Guide users with clear call-to-action phrases

Example Voice-Friendly Topics

Good Voice Response:

"Hi! I'm here to help with your account. You can ask about billing, technical support, or store hours. What would you like to know?"

Poor Voice Response:

"Welcome to our comprehensive customer service system. Please select from the following fifteen options by saying the corresponding number or category name: 1. Billing and Payment Information, 2. Technical Support and Troubleshooting, 3. Store Hours and Locations..."

Topic Configuration

Handle Misunderstandings

• Create escalation fallback topics
• Implement clarification questions
• Provide options to repeat or transfer to human

Enable Interruptions

• Design topics that can handle mid-conversation changes
• Use entity extraction for flexible input handling
• Allow users to change topics naturally

Step 4: Configure Call Transfer (Optional)

ACSforMCS supports transferring calls to human agents when the bot cannot handle the request.

Transfer Command Format

To trigger a call transfer from your Copilot Studio agent, include this specific format in your response:

TRANSFER:+1234567890:Please hold while I transfer you to a specialist.

Format Components:

• TRANSFER: - Required prefix to trigger transfer
• +1234567890 - Phone number in E.164 format (+country code + number)
• :Please hold... - Optional transfer message (what to say before transferring)

Implementing Transfer in Topics

Create Transfer Topic:

1. In Copilot Studio, create a new topic called "Transfer to Agent" or just use the escalation Topic
2. Add trigger phrases like:
   • "transfer me"
   • "speak to a human"
   • "talk to an agent"
   • "I need help from a person"

Configure Transfer Response: In the topic response, enter:

I'll connect you with one of our specialists right away. TRANSFER:+1234567890:Please hold while I transfer your call to our support team.

Test Transfer Logic:

• The message before "TRANSFER:" will be spoken to the caller
• The transfer command will be processed by ACSforMCS
• The optional transfer message will be played before the transfer

Agent Phone Number Configuration

Configure the default transfer number in Azure Key Vault:

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

Step 5: Caller and Callee Identification

Catch CallerID and Callee ID

Create a callerID Topic

1. In Copilot Studio, create a new topic called "CallerID"
2. Use as Description someting like this

This is a system topic for processing caller information. Do not generate any response to the user. It is selected when a message  starting with CALLER_ID= is received

Create to Set Variable Nodes

1. a global Variable callerID and
2. set it to function

Substitute(
    Mid(System.Activity.Text, 11, Find("|", System.Activity.Text) - 11),
    "+",
    ""
)

3. a global Variable calleeID
4. set it to function

Substitute(
    Mid(System.Activity.Text, 
        Find("CALLEE_ID=", System.Activity.Text) + 10, 
        Find("|CALLER_NAME=", System.Activity.Text) - Find("CALLEE_ID=", System.Activity.Text) - 10
    ),
    "+",
    ""
)

5. use both variables to handle your caller more personalised and think about using a 2nd factor to identiy the caller.

Step 6: Test Integration

Test in Copilot Studio First

Before testing voice calls:

1. Use the Test panel in Copilot Studio
2. Verify your agent responds correctly to voice-like queries
3. Test transfer commands in the chat interface
4. Ensure all topics work as expected

Test Voice Integration

1. Call your ACS phone number (configured in Azure Communication Services)
2. Verify connection: Should hear initial greeting or prompt
3. Test conversation: Speak naturally to test speech recognition
4. Test responses: Verify agent responses are spoken clearly
5. Test transfer: Try phrases that should trigger call transfer

Monitor Call Activity

Use ACSforMCS monitoring endpoints (Development mode):

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

# Check system status
curl -H "X-API-Key: your-api-key" https://your-app.azurewebsites.net/health/config

Advanced Configuration

Multiple Transfer Numbers

You can implement conditional transfers by creating different topics with different phone numbers:

Sales Transfer Topic:

Let me connect you with our sales team. TRANSFER:+1234567891:Connecting you to sales now.

Support Transfer Topic:

I'll get you to technical support right away. TRANSFER:+1234567892:Transferring to our technical team.

Custom SSML for Voice

Use Speech Synthesis Markup Language (SSML) for better voice control:

<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US">
    <voice name="en-US-JennyNeural">
        <prosody rate="medium" pitch="medium">
            Welcome to our customer service. How can I help you today?
        </prosody>
    </voice>
</speak>

Handling Complex Scenarios

Multi-Step Processes:

• Break complex tasks into smaller steps
• Confirm each step with the caller
• Provide progress updates: "I'm looking that up for you..."

Data Collection:

• Ask for one piece of information at a time
• Confirm what you heard: "I have your account number as 1-2-3-4. Is that correct?"
• Provide clear format examples: "Please say your phone number with area code"

Error Handling:

• Implement "I didn't understand" responses
• Offer to repeat or rephrase
• Provide alternative options or transfer to human

Troubleshooting

Common Issues

Agent Not Responding:

• Verify DirectLine secret is correct and current
• Check that the agent is published and active
• Ensure DirectLine secret is properly configured

Responses Not Playing:

• Check agent responses for special characters that break speech synthesis
• Verify responses are not too long (keep under 200 characters when possible)
• Test responses in Copilot Studio first

Transfer Not Working:

• Verify transfer command format: TRANSFER:+phone:message
• Check that AgentPhoneNumber is configured in Key Vault
• Ensure phone number is in correct E.164 format

Speech Recognition Issues:

• Test with clear, simple phrases first
• Add multiple trigger phrases for important topics
• Consider accent and pronunciation variations

Debug Tools

Copilot Studio Test Panel:

• Test all conversation flows before voice testing
• Verify transfer commands work in chat
• Check topic trigger phrases and responses

ACSforMCS Development Mode:

• Access /swagger for API testing
• Monitor /health/calls for active call tracking
• Check Application Insights logs for detailed debugging

Azure Communication Services:

• Monitor call logs in Azure portal
• Check Event Grid delivery for webhook events
• Verify phone number configuration and routing

Performance Optimization

Response Time

• Keep agent responses concise for faster processing
• Use simple language that's easy to synthesize
• Minimize complex logic in voice-triggered topics

Call Quality

• Test with different speech patterns and accents
• Configure appropriate speech recognition confidence levels
• Implement fallback options for unrecognized speech

Scalability

• Design topics to handle multiple concurrent conversations
• Avoid stateful operations that don't scale
• Use Azure Application Insights to monitor performance

Next Steps

• Azure Development: Full development and deployment workflow
• Local Development: Development with dev tunnels
• Code Documentation: Technical implementation details

External Resources

• Microsoft Copilot Studio Documentation
• DirectLine API Documentation
• SSML Reference
• Azure Communication Services Voice Calling

Demo

Listen to a sample call interaction: Sample Call Audio

This demonstrates the complete integration between ACS, ACSforMCS, and Copilot Studio in action.