In this Use Case we're setting up a Virtual User to take customer questions and answer accordingly with Copilot-defined topics. To achieve this, we're going to cover the following topics in this Use Case: 

• How to use Microsoft Copilot Studio to set up your first AI Agent acting as a Virtual User.
• How to configure Nimbus in order to use the Virtual User in your workflows.
• How to set up the workflow and make service calls for further adjustments.

Preconditions

Azure Preconditions

Microsoft Services: In order to use AI-driven Bots in Nimbus, you will need access to Microsoft Cognitive Services. Azure Bot usage causes additional costs outside of your Nimbus subscription. Please note the licensing remarks below.

Use Case Overview

Details will be covered below in this Use Case. As a quick tl;dr, here is an overview of items you will need: 

¹ Note that behaviors, UI designs, and configuration details are subject to frequent changes by Microsoft and may mismatch from our use case descriptions. Feel free to contact our support to request an update to our use case documentation.

Step 1 - Copilot Setup

Agent creation

1. Sign in to Copilot Studio.
2. Go to Agents and Create a new Agent.
   1. Name: Give your Agent a descriptive name that signals the intended use, e.g. Insurance Bot, Attendant, Customer Data Requester.
   2. Description: Can be left empty. Only for listings in Copilot, not used by Nimbus. 
   3. General Instructions: Configure your Bot's directive and behavior. As an example: 
      As a telephony helpdesk assistant you help customers with accurate and helpful responses. Ensure answers are in between 2-3 sentences. Maintain a courteous and accurate communication style.
   4. Orchestration: Disabled
      💡Note that any generative events will be ignored in Nimbus Workflows. Your trigger phrases should be as specific and deterministic as possible to ensure a quick workflow routing experience.
3. Topics¹: Distinguished by System and Custom topics.
   1. System topics: The “Conversation Start” topic is the core focus point in this use case. This is how the Bot starts the conversation with the customer, even proactively if necessary. 
      💡We will get back to this later in the Nimbus Setup as our “Initial Message” in the Virtual User configuration below.
   2. ²Custom topics: This is where you define the competencies of your Bot. It primarily consists of trigger phrases (e.g. “Health service, Insurance service, Problem handling, Support request, Personal Assistance” that your Bot is supposed to react to with topics in specific or general replies. 
      Following the official chat bot topics documentation, you can also go into very specific cases here based on your most-frequented service inquiries such as “In which countries can I find branch offices of service X”).
4. Publish: Once everything is configured³, don't forget to publish your Bot.

Agent Authentication

Step 2 - Nimbus Setup

Configuring the Bot

✅ The Bot is your “mapping” to the Bot and API endpoint you configured above, including the authentication.

1. Head to Nimbus Administration > Configuration > Bots and create a new Bot.
2. Give your Bot a descriptive name. 
   💡This name is just for Nimbus UI purposes, and must not match Copilot. 
3. Define the Organization Unit under which this Bot will be selectable. 
   ☝ Note that any service on this OU or higher can access it (which may result in additional Azure cost).
4. Type is M365 Copilot Direct Line 3.0.
5. API Key: 🧠 Paste the Secret from the Copilot Setup above.
6. Endpoint: 🧠 https://directline.Botframework.com/v3/directline/conversations
7. Save and Close.

Configuring Bot Response Templates

{
	"type": "message",
	"id": "5ZASDrgTOO0GtNlVtdgEE2-uk|0000021",
	"timestamp": "2025-05-20T20:31:01.9981516Z",
	"serviceUrl": "https://directline.botframework.com/",
	"channelId": "directline",
	"from": {
		"id": "user1"
	},
	"conversation": {
		"id": "5ZASDrgTOO0GtNlVtdgEE2-uk"
	},
	"locale": "en-EN",
	"text": "Hello, this is my answer as a Bot"
}

{
  "type": "event",
  "id": "IG7NO2Am5RlIHU0Ufa3pEr-eu|0000005",
  "timestamp": "2025-07-04T11:26:07.9037389Z",
  "channelId": "directline",
  "from": {
	"id": "ca1f129e-77d9-1f5a-e4d4-83bdb379b763",
	"name": "Agent 1",
	"role": "bot"
  },
  "conversation": {
	"id": "IG7NO2Am5RlIHU0Ufa3pEr-eu"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-EN",
  "attachments": [],
  "entities": [],
  "channelData": "{\"data\":\"mydata\",\"event\":\"mycustomevent\",\"exit\":false,\"topic\":null}",
  "replyToId": "IG7NO2Am5RlIHU0Ufa3pEr-eu|0000000",
  "value": "Handover",
  "name": "Exit",
  "listenFor": [],
  "textHighlights": []
}

1. Head to Nimbus Administration > Configuration > Bot Response Templates and create a new template.
2. Give your template a descriptive name. 
   💡This name is just for Nimbus UI purposes.
3. Define the Organization Unit under which this Template is selectable. 
   💡Should ideally match the Bot OU so they can be made equally available in other Nimbus UIs. Of course you can pick a “higher” OU if you want to share this Template definition among similar services that expect the same kind of data in the reply.
4. “System Field Mappings” you can adjust as follows:

Example: Copilot DirectLine - System Field Mapping 

💡In the following we want to focus our attention to the values of “text” and “value” of the Copilot API JSON response. 

As Nimbus identifies parameter with a $-sign, you can map the response as follows:

1. Into the field Answer Raw map your type: $['text'].
    
2. Using “Copilot” Topics: 
   1. If are not working with Topics in Copilot, map your bot response $['text'] – "hello, bot" in our example above – to the Exit field in Nimbus. 
      ☝Note: that this raw text can be quite long and contain a lot of “extra fluff", so your Regular Expressions need to be complex enough to catch the response you are looking for.
   2. If you are working with Topics in Copilot, map the Exit to $['value'] - “Handover” in our example above – to the Exit field in Nimbus. 
      💡Good to know: Copilot topics trigger controlled responses can be followed with an event activity. The event consists of a name – e.g. “Exit” in our example above – and a value . Nimbus is exclusively interested in the value portion, the name 
3. The “Exit” field will use any values, e.g. $['value'] or $['text'] for the “Exit” condition check in your Conversation Handling Activities  > “Add Virtual User” activity. Regular Regular Expressions can be used to find the necessary words in a response, e.g. our “Handover” phrase.

Example: Copilot DirectLine - Custom Field Mapping

💡This part is optional, depending if you want to continue using the bot response for other purposes, e.g. for easier referencing in Nimbus Workflows or as Conversation Context.

1. Map the $['text'] field to a Custom Parameter for later usage, e.g. within your Flow Actions.
2. You can also map $['value'] from your Event activity if you want to work with the topic.
3. Repeat this for any other JSON field / value pairs you want to map to parameters.

Configuring the Virtual User

✅ Virtual Users combine the previous Bot and Template configuration. You can give them instructions to act as your Agent that will interact with the Customer.

1. Head to Nimbus Administration > Configuration > Virtual Users and create a new Virtual User.
2. Give your Virtual User a descriptive name, e.g. Service Desk Operator.
   💡This name is just for Nimbus UI purposes, e.g. for later selection in your Workflows → Next step.
3. Define the Organization Unit under which this Virtual User is selectable. 
   💡Should ideally match your intended Services and Workflows accessing this Virtual User. Of course you can pick a “higher” OU if you want to share this definition among similar Services that will use the same kind of Agent for Customer interaction.
4. The “Initial Message” acts as a "Topic” or “Query” for your bot. This field can also be used to force a bot response in case it is not configured to send an initial message by itself. 
   

   💡Note that this field is optional in Nimbus:

   Depending on your Bot configuration underlying AI may already engage with the Customer automatically. Optionally you can also this message to go directly into the first Conversation Topic¹, e.g. by using Parameters and starting right with the first inquiry.

   ---

   A possible example of an Initial Message could be:

   Hello, this is $(CustomContextParameters.DOC_ClientId) from $(Customer.Company) speaking. I have a question. What are my options?

   ¹🔎For Copilot as AI Agent, refer to System topics: > “Conversation Start” (MSFT documentation).

    
5. Check that Audio/Video modality is enabled and select a Speech Recognizers (Transcriber) 
   ✅ Speech Recognizer are configured to parse the language of the calling Customer into text for the bot to process. They can be configured multilingual, but are more effective when set to a specific language. 
6. If you want to use your Virtual user productively, ensure your Virtual User has a license applied. This license can either be applied directly in the Virtual User configuration steps below or - in bulk - via Admin > Licensing view. 
   ⮑ Applying the license enables usage of the “Add Virtual User” Workflow Activity.

Configuring your Nimbus Workflow

✅Last but not least you need to configure a new Workflows to handle the Audio/Video interaction between Customers and your new Virtual User.

1. Head to Nimbus Administration > Configuration > Workflows.
2. Design or adjust any existing workflows you want to repurpose. 
   💡 We recommend creating a copy of an existing Workflow so you can switch and test it with ease and return back should something not work as intended.
3. In your Workflow, Accept a call as normally, but do NOT add a queue it. Instead, start with an Announcement to prepare your calling Customer that they are speaking to a Virtual User (Virtual Customer Assistant).
4. Connect your Caller to the AI by using the “Add Virtual User” in your workflow. You can find it in the Conversation Handling Activities. Configure the “Add Virtual User” activity as follows:
   1. Virtual User: Select from your list of Virtual Users as previously configured in the Configuration above.
   2. Max Input Timeout: Define this to a reasonable time where no answer has been given by the Customer - e.g. 1 minute. → The activity will take the “Idle Timeout” exit.
   3. Text to Speech: determines the voice (and language) the Bot will be using for Text to Speech transcription. 
      ☝Note that the Bot may give very long answers if you haven't given it specific General Instructions in Copilot Studio, e.g. to limit itself to a few sentences only.
   4. Exits: will determine the exit node taken within your Workflow. 
      💡For example, if your Customer requests “I'd like to speak to someone in person”, the Bot may answer with “Of course! I'll have someone call you back as soon as possible” . In this case you need an “Callback” exit condition, evaluating the bot replies via Regular Expressions, for example: support|help|assist|speak|talk

      💡Prepare for all eventualities: Note that determinism of your bot highly relies on the “General Instructions” and especially on the “Topics” configuration in your Copilot setup. Make sure your “Failed” exit conditions are also covered, e.g. when no possible topic could be identified.

      💡Remember that in the Bot Response Templates $['text']is mapped to your Workflow “Exit” conditions, not the Customer's initial request or voice transcription.

       
5. Finally: 
   1. Don't forget to route your all your Activity exits, e.g. Failed/Idle conditions. 
   2. Route to Service Queues, Voicemail or Transfer where necessary.
   3. Don't forget the “Disconnect” activity at the end and to Save your workflow.

Known Limitations