In my prior post, A Short Experiment with the Amazon Connect User API, I created an Express web application to explore using the Amazon Connect User API. Since then, Amazon has released new API methods for updating contact attributes and viewing queue metrics. In this post, I update the Express app to demo these new methods.
Let’s start with the end product again. In addition to the existing a list of Connect users and a Connect user detail view, the app now has a form you can use to flag a prior call for follow-up and an auto-updating page to see the current metrics for your queues.
These new screens are shown below.
** The application code is available on GitHub at: https://github.com/phmiller/connect-api-express ***
Close your eyes to the styling, and let’s talk through what’s going on with each screen.
Update Contact Attributes
This page uses the updateContactAttributes method to add a new contact attribute to a Connect call. In this case a flag to indicate the call needs follow-up.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| app.post("/submit-updateAttributes", async (req, res) => { | |
| const contactId = req.body.contactId; | |
| const flagForFollowUpRaw = req.body.flagForFollowUp; // will equal "on" if checked, undefined if false | |
| const flagForFollowUp = flagForFollowUpRaw && flagForFollowUpRaw === "on"; | |
| var updateContactAttributesParams = { | |
| InstanceId: connectInstanceId, | |
| InitialContactId: contactId, | |
| Attributes: { | |
| FlaggedForFollowUp: flagForFollowUp.toString() | |
| } | |
| }; | |
| var updateContactAttributesPromise = connectClient | |
| .updateContactAttributes(updateContactAttributesParams) | |
| .promise(); | |
| var updateContactAttributesResult = await updateContactAttributesPromise; | |
| console.log("result", updateContactAttributesResult); | |
| res.render("submittedUpdateAttributes", { | |
| title: "Contact Attributes Updated" | |
| }); | |
| }); |
The updateContactAttributes method hangs off the connectClient object from the AWS SDK and I pass in the contact id, instance id and the new attribute(s).
You can see a before and after of the call’s Contact Trace Record below with the contact id and then the new attribute highlighted.
Using this API was straightforward, although it would be easier to write useful applications if there was a Connect API to retrieve current and past contacts, rather than having to find the contact id from the Admin Site or getting the contact id from an active call in a Streams API app.
Current Queue Metrics
This page gets all the current queue metrics for every queue in the Connect instance. It automatically reloads every two seconds to get the latest metrics (code for which is in the currentMetrics.pug and currentMetrics.js files on GitHub)
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| const qArns = [ | |
| "arn:aws:connect:…", | |
| "arn:aws:connect:…" | |
| ]; | |
| const metricsList = [ | |
| { | |
| Name: "AGENTS_AVAILABLE", | |
| Unit: "COUNT" | |
| }, | |
| { | |
| Name: "AGENTS_ONLINE", | |
| Unit: "COUNT" | |
| }, | |
| { | |
| Name: "AGENTS_ON_CALL", | |
| Unit: "COUNT" | |
| }, | |
| { | |
| Name: "AGENTS_ONLINE", | |
| Unit: "COUNT" | |
| }, | |
| { | |
| Name: "AGENTS_STAFFED", | |
| Unit: "COUNT" | |
| }, | |
| { | |
| Name: "AGENTS_AFTER_CONTACT_WORK", | |
| Unit: "COUNT" | |
| }, | |
| { | |
| Name: "AGENTS_NON_PRODUCTIVE", | |
| Unit: "COUNT" | |
| }, | |
| { | |
| Name: "AGENTS_ERROR", | |
| Unit: "COUNT" | |
| }, | |
| { | |
| Name: "CONTACTS_IN_QUEUE", | |
| Unit: "COUNT" | |
| }, | |
| { | |
| Name: "OLDEST_CONTACT_AGE", | |
| Unit: "SECONDS" | |
| }, | |
| { | |
| Name: "CONTACTS_SCHEDULED", | |
| Unit: "COUNT" | |
| } | |
| ]; | |
| app.get("/currentMetrics", async (req, res) => { | |
| var getCurrentMetricsParams = { | |
| InstanceId: connectInstanceId, | |
| Filters: { | |
| Channels: ["VOICE"], | |
| Queues: qArns | |
| }, | |
| CurrentMetrics: metricsList, | |
| Groupings: ["QUEUE"] | |
| }; | |
| var getCurrentMetricsPromise = connectClient | |
| .getCurrentMetricData(getCurrentMetricsParams) | |
| .promise(); | |
| var getCurrentMetricsResult = await getCurrentMetricsPromise; | |
| console.log("current metrics:", JSON.stringify(getCurrentMetricsResult)); | |
| res.render("currentMetrics", { | |
| title: "Current Queue Metrics", | |
| metricResults: getCurrentMetricsResult.MetricResults | |
| }); | |
| }); |
I got tripped up a bit by the syntax of this command. It is described reasonably well in the documentation, but I didn’t understand at first that I needed to specify every metric I wanted (metricsList variable) as well as the ARNs of every queue (qArns variable). It was a bit frustrating to dig through the Admin Site to get the queue ARN from the URL.
Once I got past those issues, the API behaved as I expected with one exception. Queues with no activity at all, i.e. no agents signed in and no calls, are not returned at all in the results. Rather than every metric being zero for the queue, it just is not there in the response.
My simple example doesn’t give you all that much, but I could see other uses like creating a small dashboard that lights up when certain thresholds are passed like too many calls in queue or not enough agents signed in.
Permissions
When I’m running this application from my machine, it’s using my AWS CLI credentials, which have access to everything. If you were running this code in a Lambda under an IAM role with lesser privileges, you’d have to manually assign permissions to the Connect API. For example, “connect:UpdateContactAttributes” targeting the Connect instance id in a custom policy.
Trying it out yourself
Please check out the code on GitHub at: https://github.com/phmiller/connect-api-express
References
- The Amazon Connect API is documented in several different places, the best resource for using it from JavaScript is in the AWS JavaScript SDK guide under Connect. For a reference that shows the HTTP requests and responses, see the Amazon Connect Service API reference
Thanks for reading. Any questions, comments or corrections are greatly appreciated.
To learn more about what we can do with Amazon Connect, check out Helping You Get the Most Out of Amazon Connect
I have been disappointed by the API. Things that should be really simple like “What is the current availability status of each of my agents?” or “What is the URL of the call recording for a given contact” do not appear to be in there? Am I missing something?
I would keep an eye out in the forums and from Amazon in general to see what new features are coming out.