Skip to content

Commit 307c200

Browse files
author
Russ Williams
committed
Update component README
1 parent 8d5a7d3 commit 307c200

File tree

1 file changed

+78
-107
lines changed

1 file changed

+78
-107
lines changed

‎ACSConnector/README.md

+78-107
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,90 @@
1-
# ACS Agent Escalation
2-
This package
3-
4-
### <a name="Prerequisites"></a>Prerequisites
5-
6-
##### Ngrok
7-
Need to install ngrok
8-
9-
##### Azure CLI
10-
The deployment scripts require Azure CLI version 2.22.0 or newer (go [here](
11-
https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-windows?tabs=azure-cli) to install the latest Azure CLI).
12-
13-
##### Azure CLI Extensions
14-
You will need to insall a few CLI extension that are used by the deployment scripts.
15-
16-
###### Azure Communication Service
17-
18-
To install the Azure Communication Service extension, type the ```az communication create``` command in a PowerShell command
19-
window and the extension will prompt you to automatically install itself if its not currently installed.
20-
21-
![Required ACS CLI Extension](doc/RequiredACS_CLI_Extension.png)
22-
23-
###### Web PubSub
24-
To install the Web PubSub extension, type the ```az webpubsub``` command in a PowerShell command window
25-
and the extension will prompt you to automatically install itself if its not currently installed. The output
26-
of this command may be messy with a lot of diagnostics before it prompts to install the extension so be aware of that.
1+
# ACS Agent Hub
2+
The ACS Agent Hub package implements agent escalation and makes it extremely simple to
3+
add a human handoff capability to any bot.
274

5+
### Prerequisites
6+
Successful use of this package requires the installation of a set of prerequisites so if you haven't installed them
7+
yet, browse the the [ACS Agent Hub Prerequisites](http://aka.ms/acshub#prerequisites) and install them
288

299
### <a name="GettingStarted"></a>Getting Started
3010

31-
After taking care of the [prerequisites](#Prerequisites), do the following:
11+
Getting started couldn't be easier. Simply clone the ACS Agent Hub repo and run a single deployment script and
12+
you're ready to run add escalation to your bot. There are a variety of escalation scenarios you can support and
13+
we've captured a number of them in this [short video](http://add-demo-here) you can watch to get a sense of how things work.
3214

33-
1) **Clone the GitHub Repo**
15+
1) **To Clone the ACS Agent Hub Repo**
16+
Open PowerShell and run the following command:
3417
```
35-
git clone https://github.com/managedcoder/ContactCenter
18+
git clone https://github.com/managedcoder/ACSAgentHub
3619
```
37-
1) **Deploy ACS Agent Hub**
38-
Open PowerShell and change the current directory to the root solution folder (i.e., the one that contains the ContactCenter.sln
39-
file). The Run the deploy.ps1 script using the following relative path: <br/><br/>
20+
2) **To Get Everything Setup, Run the Deployment Script**
21+
In PowerShell, change the current directory to the root solution folder (i.e., the one
22+
that contains the ACSAgentHub.sln file). Then run the following script to deploy and
23+
configure all the services required by the ACS Agent Hub:
4024
```
41-
.\Deployment\Scripts\deploy_acs_agent_hub.ps1 -botName <name of bot> -location <region>
25+
.\Deployment\Scripts\deploy_and_configure.ps1 -hubName <hub name> -resourceGroup <resource group> $ngrokFullPath <ngrok path> -location <location name> -NuGetFullPath <nuget path>
4226
```
43-
<br/><br/>This script deploys and configures all the services required by the agent hub.
44-
2) **Start bot and Agent Hub Service**
45-
In VS, right-click **Solution** in the Solution Explorer and select **Properties**. Select **Startup** tab in left nav and
46-
then click the **Select multiple projects** radio button and set the **Action** to **Start** for ACSAgentHub and
47-
ContactCenterVABot propjects and then launch the debugger (F5)<br><br>
48-
![Solution Property Pages Dialog](doc/VSMultipleStartupProjectDialog.png)
49-
50-
3) **Create Agent**
51-
In the PowerShell window you opened, create an agent in Azure Storage by running the Curl command below. You'll need to add at least one agent to be able to sign in to the agent-portal.<br><br>
52-
**Note:** The syntax for the version of Curl that distributes with Windows requires special quoting that would need to
53-
be modified to run this with a non-Windows version of Curl
27+
where:
28+
- **\<hub name>** is the name of your agent hub which will also be used as part of the name of
29+
other services created by this script
30+
- **\<resource group>** is the name of the resource group that services will be deployed to
31+
- **\<ngrok path>** is the full path to the ngrok.exe (e.g., c:\nuget\ngrok.exe)
32+
- **\<location name>** is the Azure location name of the region that services will be deployed in
33+
- **\<nuget path>** is the full path to the nuget.exe (e.g., c:\nuget\nuget.exe)
34+
35+
### <a name="ExploreEscalationScenarios"></a>Explore Escalation Scenarios
36+
To make it easy for you to quickly experiment with the ACS Agent Hub we've included sample applications that are all
37+
ready to go. All you need to do to try it out is to open the Bot Framework Composer and select the **Open** link on
38+
the Home tab and open the ComposerExample that's in the root folder of the solution. This is a very simple bot with
39+
an Escalate trigger that you can look at to see how to code an escalation and then try it out by using the
40+
**Start bot** command. After the bot starts, choose the **Open Web Chat** option in the flyout menu that appears
41+
when the bot finishes it's startup processing. Type, _**talk to human**_ to start an escalation experience. There's
42+
a short [demo video](http://add-demo-here) you can watch that shows all these steps and various escalation and agent
43+
management scenaios you can replicate using this sample app.
44+
45+
### <a name="AddingEscalationToYourBot"></a>Adding Escalation to Your Bot
46+
The sample is nice for quickly experimenting with escalation and taking a look at how it's coded, but it doesn't
47+
address how to add escalation to bots. The good news is that adding agent escalation to a Composer bot is very
48+
simple and only involves a few steps. The following steps are shown in a very short video
49+
[here](http://adding-escalation-=video) that you might find easier to follow.
50+
51+
1) **Install Agent Hub Package** - First, create a local feed and set its URL property to the full path of the
52+
.\ACSConnector\localFeed folder so Composer will know where find the package and second, add the ACSConnector package
53+
to your bot as shown in the following screen shots, respectively<br>
54+
![High-level Subsystem Overview](doc/CreatingLocalFeed.png)<br>
55+
![High-level Subsystem Overview](doc/InstallingACSConnector.png)
56+
2) **Set App Setting** - Paste the following at the top of the bot's appsettings.json file:<br>
5457
```
55-
curl -X POST http://localhost:7071/api/agents `
56-
-H "Content-Type:application/json" `
57-
-d '{
58-
\"id\": \"1\",
59-
\"name\": \"Agent 1\",
60-
\"status\": 1,
61-
\"skills\": [ \"skill 1\", \"skill 2\", \"skill 3\" ]
62-
}'
58+
"ACSConnector": {
59+
"acsAgentHubBaseAddress": "http://localhost:7071"
60+
},
6361
```
64-
4) **Create Tunnel to Agent Hub**
65-
Open a Command Prompt and run the following command to create a tunnel for use later when you subscribe message events:<br><br>```c:\ngrok\ngrok http 7071 -host-header=localhost:7071```<br><br>
66-
**Note:** You'll want to open a separate Command Promt for this since the ngrok command does not return since it's tied
67-
up listening for endpoint traffic. The endpoint that ngrok exposes will be live and accessible as long as that Command
68-
Prompt is open.
69-
70-
5) **Subscribe to ACS Message Event**
71-
Open PowerShell and change the current directory to the root project folder (i.e., the one that contains the
72-
ContactCenter.sln file. Run the following script and pass the ngrok endpoint (the https version) to have Event Grid
73-
call the bot's messaging webhook when agents chat<br><br>
74-
```.\Deployment\Scripts\update_webhook.ps1 -botName <bot name> -endpoint "https://<############>.ngrok.io/api/agenthub/messagewebhook"```<br><br>
75-
Where \<bot name\> is the same name you passed as the **-name** parameter earlier when you ran the deploy.ps1 script.
62+
![High-level Subsystem Overview](doc/AppSettings.png)
7663

77-
6) **Install npm Packages**
78-
Open a new command prompt window and from the agent-portal's project folder (the one that contains package.json), run the following command:<br><br>
79-
```npm install```
80-
81-
7) **Launch Agent-Portal**
82-
In the command prompt window you opened in the previous step, run the following command:<br><br>
83-
```npm start```<br><br>
84-
It will take a minute or two for npm to build the agent-portal and start it in the browser but when it does you'll be able to sign
85-
in as one of the agents in the list. Once you've successfully signed in you'll see an empty list of conversations and the window
86-
will look something like this:<br><br>
87-
![Initial Agent Portall](doc/InitialAgentPortal.png)
88-
89-
8) **Add ACS Agent Escalation to Your Bot (optional)**
90-
You can add ACS agent escalation to your existing bot or create a new bot using the bot template of your choice and then add
91-
escalation to it. Alternatively, you can use one of the ready-made bot examples (ComposerExample or VATemplateExample) which
92-
already has escalation integrated and skip past this step.
93-
94-
For a detailed explanation of how to add escalation to an new or existing bot, see the XXX section in this README.
95-
96-
9) **Launch Bot Emulator and Escalate to Agent**
97-
Launch bot emulator and select **File | New Bot Configuration** and enter a name for the emulator profile then enter
98-
http://localhost:3978/api/messages in the **Endpoint URL** field. You'll also need to enter the **Microsoft App ID** and **password**
99-
from the appsettings.json file in the root folder for the VATemplateExample project. When you've entered those values, click the
100-
**Save and connect** button and, for convience, save the profile in the VATemplateExample's project folder (it's gitignored).<br><br>
101-
![New bot configuration dialog](doc/NewBotEmulatorConfigDialog.png)<br><br>
102-
After you've successfully launched the bot emulator and you've seen the Welcome prompt, type the following into the bot emulator's
103-
message field:<br><br>```talk to human```<br><br>
104-
Follow the conversational prompts to escalate conversation.
105-
106-
10) **Accept the Escalation**
107-
After you have successfully escalated to an agent in the bot emulator, switch to agent portal and click the green answer button to
108-
accept the escalation request and take ownership of the conversation.
109-
110-
11) **Chat Back and Forth**
111-
Type messages in the agent-portal and the bot emulator and when finished click the hangup button
112-
113-
### <a name="AddingAgentEscalationToNewOrExistingBot"></a>Adding Agent Escalation to New or Existing Bot
114-
[ToDo: Finish this section]
115-
1) **Deploy Bot**
116-
Open PowerShell and change the current directory to the VATemplateExample project folder (i.e., the one that contains the
117-
VATemplateExample.csproj file). The Run the deploy.ps1 script using the following relative path:<br><br>```.\Deployment\Scripts\deploy.ps1 -name <name of bot> -location <region> -appPassword <password> -createLuisAuthoring -luisAuthoringRegion westus``` <br/><br/>This script deploys and configures all the services required by the virtual assistant. The name of the bot must be
118-
Internet-unique and the location is a region name line **eastus** and the password must be 16 characters long and the
119-
-luisAuthoringRegion parameter must be **westus** for US deployments.
64+
3) **Add an Escalation Action** - Add a _**Send handoff activity**_ action to any dialog and at wherever point makes
65+
sense for your bot<br>
66+
![High-level Subsystem Overview](doc/EscalateAction.png)
67+
4) **Set Escalation Action Properties** - Paste the following escalation payload into the **Context** property of escalation action and set **Transcription**
68+
to ```=null```:<br>
69+
```
70+
{
71+
"Skill": "offshore accounts",
72+
"Name": "Test Name",
73+
"CustomerType": "vip",
74+
"WhyTheyNeedHelp": "lost order"
75+
}
76+
```
77+
The properties and values above are defined by the agent hub you're escalating to. So, for example, the payload
78+
is unique to LivePerson or Omnichannel and you'd check their documentation to find out what the payload should
79+
look like for those agent hub solutions but, for the ACS Agent Hub you'll use the above payload and replace the
80+
hardcoded sample values with the appropriate values (use the values above if you are just experimenting).
81+
82+
Currently,
83+
the **Skill** and **CustomerType** properties are not being used by the ACS Agent Hub and can be set to whatever
84+
you like or left empty. The **Name** and **WhyTheyNeedHelp** properties are used in the agent-portal and the
85+
ComposerExample shows a nice way to gather and set those properties. When you're finished, it should look like
86+
this:<br>
87+
![High-level Subsystem Overview](doc/EscalationProperties.png)
88+
89+
That's it! You now ready to start your bot and trigger an escalation and explore/repeat the escalation scenarios
90+
shown in this [short demonstration](http://add-demo-here)

0 commit comments

Comments
 (0)