Let’s start with the concept and then look at how it turned out. Afterwards, I’ll take you through the nitty-gritty of how it all works, and the various trade-offs.

The concept

The journey is for my fictional Bookshop. When a customer wants to sell their books they’re offered the ability to talk to a realtime audio/video AI Assistant that will:

1. Scan their books

2. Quote the amount my library is willing to pay for them

3. Create a list of the books

Afterwards they can then continue their chat-based journey with the chosen books.

The Result

After many evenings of playing around with Genesys Cloud, Gemini Live API and Agent Development Kit the result was the following:

How it works

What you observed in the video can be broken into 2 concepts:

1. AI Video Assistant

2. Integrating it with a Genesys Cloud Digital Chatbot journey

I will start with AI at the core of this journey, then cover how it integrates into the Genesys Cloud flow.

Creating the Live Agent with Google ADK

The crux of this CX journey is leveraging two of Google’s technologies:

• Gemini Live API which allows low-latency, real-time voice and video interactions with Gemini Live

• Google Agent Development Kit which is a modular framework for the development, evaluation and deployment of AI agents

This solution was built around a single AI Agent, which we’ll look at more closely.

Book Pricing Agent

The Book Pricing Agent is designed to:

• Identify customer books by scanning their barcode

• Fetch a price we’d offer for the book

• Maintain a list of books the customer confirmed they’d sell

The definition of the Agent shows its instruction and tooling:

root_agent = Agent(
        name="coordinator_agent",
        model="gemini-live-2.5-flash-preview-native-audio-09-2025",
        instruction="""
You are an AI assistant for a library. Your purpose is to help customers who want to sell their books.

Your primary tasks are:
1.  Identify books by having the customer show you the barcode to scan
2.  Once a book is identified, tell the customer the book’s title and what the shop will offer for it.
3.  Keep a list of the books the customer wants to sell. You can add or remove books from this list based on the customer’s request.
4.  When the customer is ready, you will hand them back to a text-based chatbot to finalise the sale.

Important rules for your behaviour:
-   Always be helpful and professional.
-   When a book is scanned, refer to it by its title. Do not read out the ISBN or barcode number, and do not ask the customer to confirm it.
-   Use your tools to remember which books the customer wants to sell.
-   When the conversation is over, use the ‘transfer_conversation’ tool.
    """,
    tools=[
        # Scans the barcodes from video frames and returns book details
        scan_barcode,

        # Tools for remembering books
        remember_book_customer_is_selling,
        forget_book_customer_is_selling,
        retrieve_books_customer_is_selling,

        # End the conversation and transfer to Genesys Cloud
        transfer_conversation,
    ],
)

The tooling at the bottom of the definition is what the agent can use during a conversation to achieve its goal. They are…

Barcode scanning tool

The Gemini Live Flash model that the Agent is using is multimodal, so can understand what it is seeing as well as hearing. But it cannot read barcodes. So I had to create a tool for it detect and read the barcodes in the video frames it was receiving.

The video above shows a simplified view of the solution I created, which is to give the Agent a tool that when called will process the past 3 seconds worth of video frames to extract the ISBN from a barcode. It then searches for the relevant book’s details.

It works like this:

1. Agent’s multimodal model determines it is being shown a book

2. Agent calls the Scan Barcode tool

3. Scan Barcode tool with its access to last 3 seconds worth of video frames will:

   1. Send frames to my Barcode Scanner Service, which returns the ISBN encoded in the barcode

   2. Queries ISBN against Google’s Books API to get details about the book

   3. Calls the Book API to get a price my fictional library would pay for it

4. Scan Barcode tool returns to the Agent the ISBN, book’s details and an offer price

Excerpt of the Scan Barcode tool’s code:

async def scan_barcode() -> dict:
    """Returns information about a book based on its barcode.

       This tool reads from a buffer of recent video frames
       to find a barcode.
    """
    if not frame_buffer:
        return {"status": "Cannot read barcode."}

    frames = list(frame_buffer)
    tasks = [
        # Function below:
        # 1. Sends frame to Barcode Scanner API
        # 2. Searches for book details for ISBN in barcode
        _scan_frame_and_search_by_isbn(frame,
                                       video_frame_barcode_scanner,
                                       isbn_book_searcher)
        for frame in frames
    ]
    results = await asyncio.gather(*tasks)
    
    # ...
    
    matching_books = [
        {
            "isbn": b.isbn,
            "title": b.title,
            "authors": b.authors,
            "offerPrice": book_pricer.formatted_offer_price(b.isbn),
        }
        for b in deduped_books.values()
    ]

    return {"matching_books": matching_books} 

Originally, I’d relied on the browser’s native Barcode Detection API - as I’d shared on LinkedIn. However, it was only when I got an iPhone that I realised this API isn’t widely supported (nor working).

Memory tool

ADK does have a mechanism for memory, but I wanted the memory to be specific to the books being sold, and to have it drive the UI. What I came up with was a memory that consists of three tools:

• remember_book_customer_is_selling(isbn: str)

  • Saves book information and offer price by ISBN

  • Sends event to UI to add book to ‘Books to sell‘ section

• forget_book_customer_is_selling(isbn: str)

  • Removes book from memory by ISBN

  • Sends event to UI to remove book from ‘Books to sell‘ section

• retrieve_books_customer_is_selling()-> List[Book]

  • Retrieves all books customer is selling, with offer price totalled

This is what the UI looks like when the customer agrees on a book to sell:

Transfer to Chatbot tool

The last tool to be called is transfer_conversation. This tool allows the Agent to transfer control back to Genesys Cloud.

When this tool is called it causes the My API to instruct the front-end to replace the AI Assistant UI with the Web Messenger chat UI - covered more in the next section.

Integrating with Genesys Cloud

Now that we have covered the AI Video Assistant let’s look at how we integrate it into a Digital Chatbot in Genesys Cloud’s Web Messenger.

There are two sides to this interaction:

1. The customer is transferred from a Digital Chatbot Flow to the AI Assistant

2. The AI Assistant transfers the customer back to the Digital Chatbot Flow

Both sides are built to be resilient to failures.

Transferring to the AI Assistant

The customer starts their journey in Genesys Cloud’s Web Messenger UI, but even before they send their first message something important has happened...

The customer’s browser establishes a Websocket connection with My API, and associates that connection to a Customer’s Journey Session ID. This means two things:

1. The browser and My API have a bidirectional connection outside of the chat

2. My API has associated the customer’s browser with an ID that an Architect Flow also knows, allowing a flow to send messages to My API via a Data Action and have them forwarded to the customer’s browser

This is how it works:

1. The Customer Journey Session ID for the conversation is retrieved using the Messenger JavaScript SDK:

const channel = new BroadcastChannel("genesys-cloud-agent");

Genesys('subscribe', 'MessagingService.ready', () => {
    Genesys('subscribe', 'Conversations.started', function (event) {
        const journeySessionId = event?.data?.journeyContext?.customerSession?.id;
        
        channel.postMessage({
            type: "conversation_started",
            customerSessionId
        });
    });
});

2. This ID is then used in the URL when establishing the WebSocket connection:

const channel = new BroadcastChannel("genesys-cloud-agent");

channel.addEventListener("message", async (event) => {
    const messageType = event.data.type;
    switch (messageType) {
        case "conversation_started":
            //...
            connectToServer(event.data.customerSessionId);
            break;
        //...
    }
})

function connectToServer(customerJourneyId) {
    const websocket = new WebSocket(`wss://${serverUrl}/ws/${customerJourneyId}`);
    //...
}

When the Digital Chatbot flow wants to switch the customer’s UI to the AI Assistant it simply calls the relevant Data Action with the Customer Journey Session ID that the upstream Inbound Message flow passed to it.

Why a Customer Journey Session ID instead of the Conversation ID? Well, I was unable get the Conversation ID from the Messenger SDK. Do let me know if you know of a way…

Transferring back to the Digital Chatbot flow

I chose a different approach when transferring from the AI Assistant back to the chat:

1. Just after transferring the customer to the AI Assistant the Digital Chatbot sends a Quick Response message to the minimised chat window, asking if the customer has finished with the AI Assistant

2. When the AI Assistant has finished it calls the Transfer tool. This results in a command being sent to the customer’s browser.

3. The client-side code then:

   1. Closes the AI Assistant UI

   2. Maximises the Web Messenger UI

   3. Resumes the conversation by using the SendMessage command to response to the Quick Reply in step 1

function continueConversation(){
    Genesys('command',
        'MessagingService.sendMessage',
        {message: 'Finished'},
        (data) => { /* ... */ },
        (error) => { /* ... */ }
    );
}

This approach allows the customer to continue the conversation should the AI Assistant fail unexpectedly, and avoids any awkward polling of My API in the Architect flow.

Considerations

As with any solution, there are considerations you have to take into account. Here are 3 of the biggest with this solution.

Data split between multiple systems

Joining different systems may allow you to leverage the latest and greatest functionality, but unless these systems are closely integrated you’ll end up with data pertaining to a customer’s journey existing across them.

In this case the AI Assistant is completely separate to Genesys Cloud, so the conversation is not included in the Genesys Cloud’s transcript, nor included in any Speech and Text Analytics.

A2A will be a better way to integrate

With Genesys Cloud investing in Agentic CX, and Google investing heavily in their Agent Development Kit (ADK), one hopes it is only a matter of time until both platforms can be integrated over the Agent2Agent protocol.

However, at the time of creating this experiment A2A could not be used to integrate the two. Which explains the complexity needed in transferring between the systems.

When A2A is widely available I foresee marketplaces of specialised agents that can be leveraged for specific parts of a customer’s journey.

The result would be highly specialised agents all working together to deliver for a customer.

Safety

We’ve all heard the horror stories of freshly implemented AI chatbots running amok with a company’s reputation. So ensuring any AI Assistant is bounded to a particular task, grounded, extensively evaluated and restricted by sufficient guardrails is a must.

The Gemini Live API, which was freshly out of GA at the time of implementing this solution cannot be used with Google’s Model Armor, and I was unable to find any mature third-party guardrail solutions compatible with the Live API’s streaming architecture.

There is also little in way of evaluations that simulate audio/video to test an agent’s performance using the Gemini Live model. You can get part the way there though by switching to a text-based model to evaluate the reasoning part of the agent.

Anecdotally, the model did a great job of refusing to diverge from its task.

Conclusion

This project has provided a glimpse into what capabilities may be easily integrated into customer journeys of the future. However, for the time being with these two platforms workarounds are required to create a coherent flow.

Naturally there are also questions around whether this makes for a good CX journey anyway… I created the journey out of curiosity of the technologies and how they fit together, not based on CX research. But it sure was fun!

If you have any questions, or have suggestions on how I can improve the flow please do get in contact.

Subscribe now

I have created an open-source n8n Genesys Cloud community node. It allows you to leverage n8n, one of the world’s leading workflow automation platforms to easily create workflows that interact with Genesys Cloud to do tasks such as:

• Generating custom reports

• Automating user provisioning / syncing between environments

• Auditing user permissions

• Triggering alerting

• and much more…

What is n8n

For those who haven’t heard of n8n, it is one of the world’s leading workflow automation platforms. It offers, amongst other things:

• An exceedingly simple interface - where you visually connect actions to make a workflow

• Support for over 1k integrations, and an extensive range of community integrations.

• An incredibly supportive community

• The ability to create, maintain, share and execute workflows

Accessing n8n is possible by:

• Hosting n8n yourself

• Choosing a hosted plan

Creating a demonstration workflow

As always, let’s learn by doing…

We’ll use the Genesys Cloud community node to create a workflow that reports on User’s roles, Skills, Groups & Queues in your organisation. At the end we’ll then touch on how it could be extended to include data from the likes of Salesforce, MS Dynamics CRM 365, Zendesk etc

The workflow we’ll create will:

1. Get all the users in the organisation

2. Get the queues for each of the users

3. Format the data

4. Convert to a CSV

The resulting CSV will contain the User ID, Name, Email, State, Roles, Skills, Groups and Queues of all users.

Installing Genesys Cloud community n8n node

Assuming you now have access to n8n, you need to install the Genesys Cloud community node to n8n by:

1. Expanding the Settings

2. Clicking ‘Community nodes’

3. Clicking ‘Install a community node’

4. Under ‘npm Package name‘ put @makingchatbots/n8n-nodes-genesys-cloud

5. Check ‘I understand the risks…‘

6. Finally, click Install

Creating an OAuth Client

I’ll pre-emptively mention setting up credentials, which you will have to do in the next step. When you add your first action in a minute you will be presented with the ‘Credential to connect with’ box in red.

Add your Genesys Cloud org’s OAuth Client by:

1. Clicking the box and selecting ‘Create new Credential‘

2. Supplying your OAuth Client’s ID, Secret and Region

3. Clicking Save

Retrieve users and their assigned queues

We start the creation of the flow by attaching two Actions to a Schedule Trigger node:

1. Get many users - returns all users in the Genesys Cloud org

2. Get queues for a user - for each user return all their assigned queues

The video below shows the process of adding these nodes:

Transform data into a CSV report

Now we have all the data for our report (users and their assigned queues) I’ll show how, even though n8n allows for code-less automation, you can always add code if you want to.

I take the data amassed from the previous actions and use the Code In JavaScript node to collate it into a response that the next node will Convert to a CSV file:

The code that is used to collate the user data and their assigned queues is below:

const users = $items("Get many users");
const allQueues = $items("Get queues for a user");

// Helper to extract names from arrays like roles, skills, or groups
const formatNames = (arr) => (arr ? arr.map(i => i.name).join(', ') : '');

return users.map((userItem, index) => {
  const user = userItem.json;

  // Filter queues linked to this specific user index
  const queueNames = allQueues
    .filter(q => (Array.isArray(q.pairedItem) ? q.pairedItem[0].item : q.pairedItem?.item) === index)
    .map(q => q.json.name)
    .join(', ');

  return {
    json: {
      "User ID": user.id,
      "Name": user.name,
      "Email": user.email,
      "Title": user.title,
      "Department": user.department,
      "State": user.state,
      "Last Login": user.dateLastLogin,
      "Roles": formatNames(user.authorization?.roles),
      "Skills": formatNames(user.skills),
      "Groups": formatNames(user.groups),
      "Queues": queueNames
    }
  };
});

Running your workflow

Now we have created the entire workflow you can run it by clicking ‘Execute workflow’, or by adjusting the Schedule Trigger.

The output will be a CSV file like below attached to your Convert to File node:

You could next have a go at extending this workflow to email the CSV to you.

Integrating with other systems

I have shown a workflow that only extracts data from Genesys Cloud. However, that’s only scratching the surface of what’s possible with this node and n8n. There are many other systems that n8n integrates with, making it possible to collate data from across your company’s estate. Systems such as Salesforce, MS Dynamics CRM 365 and Zendesk are all supported.

Conclusion

This article has provided a whistle-stop tour demonstrating just how easy it now is to create workflows for Genesys Cloud by using my Genesys Cloud n8n community node.

I will be continually extending it to cater to as many use-cases as I can think of. If you have a use-case you would like it to support then I’d love to hear from you!

Also, please do share what you make with it. I love seeing the ingenuity of the Genesys community.

“Agents are reporting that no calls are coming through. Did you break something?”

Your heart sinks. But then you remember: you’re using CX as Code. With a single command you revert your changes, confirm agents are receiving calls again, and head home with a jaunty step.

The happy ending to this story is thanks to CX as Code. Without it, you’d be stuck in the drudgery of manually undoing your changes. In this article, I’ll explain what it is, how it works, and why it matters for your contact centre.

If you’d rather see it in action straight away, here’s my open-source project:

https://github.com/MakingChatbots/genesys-cloud-cx-as-code-demo

In future articles I’ll discuss creating an automated pipeline to test and deploy changes, so be sure to subscribe:

Subscribe now

What is CX as Code

CX as Code, also known as Infrastructure as Code (IaC) is the concept of representing parts (or even all) of your contact centre as code. Queues, flows, data tables, integrations, and more can all be defined this way.

This is what a queue looks like defined as code:

resource "genesyscloud_routing_queue" "book_refund_queue" {
  name                 = "Book Refund"
  description          = "Processes refunds for books"

  enable_transcription = true
  acw_timeout_ms       = 300000
  auto_answer_only     = false
}

CX as Code is made possible using a tool called Terraform, which has been extended by Genesys with their own Terraform provider.

As you’ll see later, with resources like this queue defined as code you’ll be able to use a single command to create, update or delete them against any of your organisations.

Why represent resources as code?

Amazing things start to happen when you represent your organisation as code:

• Disaster Recovery - You can redeploy your entire contact centre (or parts of it) at the tap of a button, should disaster befall you

• Tracking changes - If you store the code in source-control then you can audit every change

• Reliability - You can test changes to your contact centre’s development organisation then reliably deploy the same changes to your production organisation.

You can even bake all this into an automated process to test, peer-review and deploy changes between Genesys Cloud Organisations.

Demonstrating CX as Code

Now to the fun bit! Let’s create and deploy a simple journey using CX as Code.

The full solution for this journey is over on my GitHub.

What we will build

We will build a simple digital chatbot journey comprising of:

1. Messenger Deployment / Configuration

2. Inbound Message Flow

3. Digital Bot Flow

4. Transfer to existing queue

Then deploy it against two organisations:

1. Development - where we can test it

2. Production - where real users use it

Defining your resources as Terraform

As I mentioned previously, CX as Code is built upon a tool called Terraform, which Genesys have extended via their Terraform provider to be able to represent Genesys Cloud resources. Terraform can then deploy these against any of your organisations.

So if we take our simple chatbot journey and represent it as Terraform resources in files it will look like below:

• deployment.tf - Contains the Messenger Deployment and Configuration

• flows.tf - Contains both Incoming Message and Digital Bot flows

Around the peripheries there are also other files that are necessary:

• provider.tf - Defines the providers Terraform must use, and how they should be configured

• variables.tf - Defines the variables that can be configured per environment

• terraform.tfvars - Defines the values for the variables in variables.tf. There is one of these for each org

Let’s go over the most important files above in more detail.

Provider configuration (provider.tf)

When we tell Terraform to deploy our Genesys Cloud resources it needs some way of knowing what they are and how to deploy them.

The provider.tf file tells Terraform:

• Exactly which version of Terraform can be used on this project

• That it should use the Genesys Cloud provider, and what version

• Where it should save the State of the resources it manages - for simplicity’s sake this project stores the state locally.

# provider.tf

terraform {
  required_version = "~> 1.12.2"

  required_providers {
    genesyscloud = {
      source  = "mypurecloud/genesyscloud"
      version = "~> 1.68.3"
    }
  }
  
  # Using local backend for 
  backend "local" {}
}

provider "genesyscloud" {
  # Credentials will be set via environment variables
}

Variable definitions (variables.tf)

When we run Terraform we can provide variables that it will use to define resources differently for each organisation.

The variables.tf in this project allow a different queue name to be used for each organisation:

# variables.tf

# ... 

variable "book_purchase_queue_name" {
  type        = string
  description = "Name of queue for book purchases"
}

Messenger Deployment (deployment.tf)

The deployment.tf file contains two resources:

• genesyscloud_webdeployments_configuration

• genesyscloud_webdeployments_deployment

Below is simplified version of the file in the repo that explains some important concepts:

# deployment.tf

resource "genesyscloud_webdeployments_deployment" "contact_us" {
  name    = "Bookshop Support"

  # References the flow resource the Messenger Deployment will use
  flow_id = genesyscloud_flow.inbound_message_flow.id

  configuration {
    # References the configuration resource above 
    id = genesyscloud_webdeployments_configuration.default.id
    #...
  }
}

resource "genesyscloud_webdeployments_configuration" "default" {
  name        = "Lucas' Bookshop Config"
  description = "Configuration for Contact Us page"
  #...
}

There is an important concept at work in this file:

One resource can reference a value of another resource - as is being done with the flow_id above. Terraform is clever enough to realise these dependencies and adjust the order that resources are created

Architect Flows (flows.tf)

The flows.tf file is where we will create our Incoming Message Flow and Digital Bot Flow. This is also where we will transfer to a queue that already exists in our organisation.

The definition for the flows themselves are defined in YAML. These are the YAML files that are exported from the Architect UI.

The flows.tf file contains a resource that is used by each flow:

• genesyscloud_flow

Each of these point to the flows’ definitions:

• inbound-msg.yaml

• digital-bot.yaml

# flows.tf

locals {
  # Locations of where the flows are defined
  inbound_msg_flow_filepath = "${path.module}/flows/inbound-msg.yaml"
  digital_bot_flow_filepath = "${path.module}/flows/digital-bot.yaml"
}

resource "genesyscloud_flow" "inbound_message_flow" {
  filepath = local.inbound_msg_flow_filepath

  # A unique has created to detect when the flow's YAML file changes
  file_content_hash = filesha256(local.inbound_msg_flow_filepath)

  # This is how you can configure your flow definition
  substitutions = {
    bot_flow_name = genesyscloud_flow.digital_bot_flow.name
  }
}

resource "genesyscloud_flow" "digital_bot_flow" {
  filepath = local.digital_bot_flow_filepath
  file_content_hash = filesha256(local.digital_bot_flow_filepath)
  
  substitutions = {
    book_purchase_queue = var.book_purchase_queue_name
  }
}

There’s an important concept at work here, called substitutions:

Substitutions allow values to be passed into the flow’s YAML definition. In our journey we are using them to pass in the name of the queue the flow will transfer to - which differs per organisation.

The flow’s YAML below shows the substitution {{book_purchase_queue}} being used.

# flows/digital-bot.yaml

digitalBot:
  name: Transfer To Queue
  bots:
    # ...
    actions:
      - transferToAcd:
        name: Transfer to ACD
        targetQueue:
          lit:
            name: "{{book_purchase_queue}}"

Deploying to an organisation

We now have our journey defined as code. Let’s now move on to how we deploy it to our dev organisation.

1. Initialising Terraform is the first thing we have to do. In this step we also tell it where we want it to save the state of what resources it manages, which is defined in the backend.hcl file.

   terraform init -backend-config=envs/dev/backend.hcl

2. Next we share the Client ID and Secret of the OAuth Client that Genesys’ Terraform Provider will use to access our dev organisation.

   export GENESYSCLOUD_REGION=<region>
   export GENESYSCLOUD_OAUTHCLIENT_ID=<OAuth Client ID>
   export GENESYSCLOUD_OAUTHCLIENT_SECRET=<OAuth Client Secret>

3. Finally we run Terraform’s apply command, and pass in the variables we have defined for the dev organisation.

   terraform apply -var-file=./envs/dev/terraform.tfvars

   When you run apply it will create a plan of what resources it needs to create, delete or update. You get a chance to check this plan and approve it.

Once we have tested and/or iterated on the deployment to the dev organisation, we can then deploy to our production org.

We follow the same steps, but this time with the OAuth Client for our production organisation and pointing to the production backend and variable files.

terraform init -backend-config=envs/prod/backend.hcl

export GENESYSCLOUD_REGION=<region>
export GENESYSCLOUD_OAUTHCLIENT_ID=<OAuth Client ID>
export GENESYSCLOUD_OAUTHCLIENT_SECRET=<OAuth Client Secret>

terraform apply -var-file=./envs/prod/terraform.tfvars

Once again you’ll be presented with the plan to confirm before any changes are made to your organisation.

That’s it! We’ve now used CX as Code to deploy a change reliably to our two organisations.

Taking control of existing resources

The journey we deployed across our organisations both referenced an existing Queue. But what if we also wanted to bring the Queue under the management of Terraform?

This is actually an easy task, and is made possible by either of the following options:

1. Terraform’s import block - great for specific resources you want to import

2. Genesys’s tf_export resource - great for a type of resource e.g. all queues, or all flows

Since we have a single resource we want to bring under the control of Terraform I will use option 1, Terraform’s import block.

To use the import block we create the following file, which contains two parts:

• The resource we’ll import the resource under ‘genesyscloud_routing_queue.book_purchase‘

• An import block where we provide the ID of the queue to import (taken from the queue’s URL in the Genesys Cloud org)

# queue.tf

import {
  # ID of the queue in Genesys Cloud, taken from the Queue's URL
  id = "5b1761c1-632a-402b-aa28-6e858ed520f9"
  
  # Resource to import the queue to (aka the resource below) 
  to = genesyscloud_routing_queue.book_purchase
}

resource "genesyscloud_routing_queue" "book_purchase" {
  name = "Book Purchase (${var.environment})"
}

Once defined you can run the import command (after the setup commands) to import the resource into your Terraform’s state:

terraform init -backend-config=envs/dev/backend.hcl

export GENESYSCLOUD_REGION=<region>
export GENESYSCLOUD_OAUTHCLIENT_ID=<OAuth Client ID>
export GENESYSCLOUD_OAUTHCLIENT_SECRET=<OAuth Client Secret>

terraform import

Terraform’s import command will import the name, ID and configuration of the queue in the dev organisation.

You should then import the Queue in the Production organisation using the same approach, being sure to replace the Queue’s ID in the import block.

import {
  id = "32bc2add-4e5e-4794-b281-8eb82780b552"
  ...
}
...

Once you’ve completed the above steps then both queues will be controlled by Terraform.

Conclusion

In this article we covered:

• What CX as Code is

• How you can use it to reliably deploy resources across your organisations

• How to reference existing resources

• Finally, how to import those resources into CX as Code

My hope is that you will have come away from reading this article with a new found enthusiasm for what is possible with CX as Code, and how you might apply it to your organisation. As David Gwartney, an AI Solutions Architect at Genesys reminded me, you don’t necessary have to implement this wholesale. It can help even if wanting to iterate quickly on a small project.

Enjoyed this article? Follow me on LinkedIn and subscribe to this newsletter to keep up to date.

Once we’ve finished you’ll be able to ask AI questions about your contact centre, and even have it produce ad-hoc reports like below:

Before we dive into the setup let’s discuss how it works.

How it works

Claude Desktop is Claude’s official desktop app that lets you interact with their latest and greatest generative models (colloquially called AI). The feature we’ll be leveraging is its ability to be extended using MCP Servers (like mine), which give it access to tools that can interact with external systems, in our case a Genesys Cloud organisation.

The grossly oversimplified process is as follows:

1. You ask a question, such as “Which queue has the most agents assigned to it?“

2. The AI understands that it needs a tool to answer the question, and retrieves a list of tools from the configured MCP Server.

   1. Each tool has a name, description and parameters.

3. AI uses these to determine the best tool, and then calls that tool

4. The response from the tool is then used to derive an answer

Like I say, that is an oversimplification, but it adequately explains the roles of the various parts that we’ll setup in the next section…

Setup

The setup consists of two parts:

1. Creating an OAuth Client in your Genesys Cloud organisation

2. Installing Claude Desktop and configuring it to use the Genesys Cloud MCP Server, along with the OAuth Client configuration

Step 1: Create an OAuth Client

When configuring the Claude to use the Genesys Cloud MCP Server you need to provide OAuth Client Credentials so the MCP Server can access your organisation.

Follow Genesys’ guide for creating an OAuth Client with Client Credentials.

Then assign a role with the following permissions:

• Routing > Queue > View

• Analytics > Conversation Detail > View

• Analytics > Speech and Text Analytics Aggregates > View

• Speech and Text Analytics > Data > View

• Recording > Recording > View

Alternatively, if you only want to assign permissions for a subset of the tools then you can find permissions per tool in the docs.

Step 2: Configure Claude Desktop to use MCP Server

Now we’ll set up Claude Desktop to use the Genesys Cloud MCP Server, along with the previously created OAuth Client’s credentials.

1. Install Claude Desktop (and create a free account if necessary)

2. Follow the official guide for opening the config file claude_desktop_config.json

3. Insert the configuration below:

{
  "mcpServers": {
    "genesys-cloud": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@makingchatbots/genesys-cloud-mcp-server"],
      "env": {
        "GENESYSCLOUD_REGION": "<PUT REGION HERE>",
        "GENESYSCLOUD_OAUTHCLIENT_ID": "<PUT OAUTHCLIENT ID HERE>",
        "GENESYSCLOUD_OAUTHCLIENT_SECRET": "<PUT OAUTHCLIENT SECRET HERE>"
      }
    }
  }
}

Make sure you replace the placeholders with your Client Credentials created in the previous section.

It’s now all done. You can now open a new chat within Claude Desktop and ask a question of your contact centre’s data. Like asking it to analyse a transcript for a disgruntled customer to understand where it all went wrong:

Conclusion

There are few areas more important in a business than the point at which a customer contacts you. So being able to leverage AI to better understand the customer in this space can only be a good thing, and hopefully this article has helped with that.

The Genesys Cloud MCP Server I’ve created, and referenced throughout this article, has a growing set of tools that I’m building and refining based on feedback from the Genesys community.

If you have any thoughts or suggestions, I’d love to hear from you. Feel free to connect with me (and follow me) on LinkedIn.

The Slack message above shows what is automatically sent when a new version of a flow in Genesys Cloud is published. I included all the details I thought would be useful:

• Name of the updated flow

• Flow Description

• New Version

• Who made the change

• Link to conversations using the flow

How it works

The solution, diagrammed above is as simple as I could make it. It consists of 3 parts:

1. Amazon EventBridge Integration used to trigger a Lambda when flows in Genesys Cloud are updated

2. Triggered Lambda uses details in the event to create a Slack message

3. Lambda calls Slack Webhook URL to send the message

Let’s go into each point in more detail.

1. Detecting when a flow is updated

Detecting when a flow has been updated is possible by configuring Genesys Cloud’s Amazon EventBridge Integration to publish notifications for the v2.flows.{id} topic.

These notifications are filtered by an EventBridge Rule to only trigger the Lambda when a flow has been successfully published:

{
  "detail-type": ["v2.flows.{id}"],
  "detail": {
    "eventBody": {
      "currentOperation": {
        "actionStatus": ["SUCCESS"],
        "actionName": ["PUBLISH"]
      }
    }
  }
}

2. Create Slack message from event

When I created the tool I made the conscious decision to keep it simple by using only the details in the v2.flow.{id} notification, and not going off to other Platform API endpoints.

Thankfully the notification contained all the information I needed. The code below is that of the Lambda’s handler, and shows it extracting all the relevant fields:

/* handler.ts */

async function handler(
  event: EventBridgeEvent<typeof v2FlowsEventDetailType, v2FlowsEvent>
): Promise<void> {
  const flowPublished = transformEvent(event.detail);

  await slackClient.sendMessage(
    flowUpdatedMessage({
      flow: {
        name: event.detail.eventBody.name,
        description: event.detail.eventBody.description,
        version: event.detail.eventBody.publishedVersion.id,
      },
      editor: {
        name: flowPublished.editor.name,
        profile: flowPublished.editor.profileUrl,
      },
      flowInteractionsPage: performanceInteractionLinkBuilder(
        event.detail.eventBody.id
      ),
    })
  );
}

/* transformEvent.ts */

export function transformEvent(
  { eventBody }: v2FlowsEvent
): FlowUpdatedEvent {
  let editor: EditorDetails;

  if (eventBody.currentOperation.user) {
    const userDetails = eventBody.currentOperation.user;
    editor = {
      type: "user",
      id: userDetails.id,
      name: userDetails.name,
      profileUrl: profileLinkBuilder(userDetails.id),
    };
  } else if (eventBody.currentOperation.client) {
    const clientDetails = eventBody.currentOperation.client;
    editor = {
      type: "oauth",
      id: clientDetails.id,
      name: clientDetails.name,
      profileUrl: oauthClientLinkBuilder(clientDetails.id),
    };
  } else {
    editor = {
      type: "unknown",
    };
  }

  return {
    editor,
    flow: {
      name: eventBody.name,
      description: eventBody.description,
      version: eventBody.publishedVersion.id,
    },
  };
}

3. Sending the Slack message

After the details have been extracted we transform them into a message schema for Slack’s Block Kit UI schema. This schema allows more complex messages than just a block of text.

Once the Block Kit UI’s JSON has been created then it’s simply a case of sending it in the body of a POST request to the preconfigured Webhook URL.

/* flowUpdatedMessage.ts */

export function flowUpdatedMessage({
  flow,
  editor,
  flowInteractionsPage,
}: {
  flow: {
    name: string;
    description: string | undefined;
    version: string;
  };
  editor: { name: string; profile: URL };
  flowInteractionsPage: URL;
}): SlackMessage {
  return {
    build(): string {
      return JSON.stringify({
        text: `Flow updated: ${flow.name}`,
        blocks: [
          {
            type: "section",
            text: {
              type: "mrkdwn",
              text: "A *flow was updated!*",
            },
          },
          {
            type: "section",
            fields: [
              {
                type: "mrkdwn",
                text: `*Name:*\n${flow.name}`,
              },
              ...(!flow.description
                ? []
                : [
                    {
                      type: "mrkdwn",
                      text: `*Description:*\n${flow.description}`,
                    },
                  ]),
              {
                type: "mrkdwn",
                text: `*By:*\n<${editor.profile.href}|${editor.name}>`,
              },
              {
                type: "mrkdwn",
                text: `*Version:*\n${flow.version}`,
              },
            ],
          },
          {
            type: "context",
            elements: [
              {
                type: "mrkdwn",
                text: `<${flowInteractionsPage.href}|Latest conversations using this flow>`,
              },
            ],
          },
        ],
      });
    },
  };
}

/* AxiosSlackClient.ts */

export class AxiosSlackClient implements SlackClient {
  private readonly axiosInstance: AxiosInstance;

  public constructor(
    webhookUrl: string,
    axiosInstanceFactory: Pick<typeof axios, "create"> = axios
  ) {
    this.axiosInstance = axiosInstanceFactory.create({
      baseURL: webhookUrl,
      headers: {
        "Content-Type": "application/json",
      },
    });
  }

  public async sendMessage(message: SlackMessage): Promise<void> {
    await this.axiosInstance.post(undefined, message.build());
  }
}

The result is the message below being published to the Slack Channel configured against the Webhook URL:

What’s next…

I have always seen this tool, whilst useful, as a stepping stone to a much more audacious project: Tracking every flow change in GitHub!

Having changes committed to GitHub would open up the ability to do some pretty cool things:

• Lint flow evaluations

• Publish notifications to Slack (with patch-sets, change descriptions)

• Auto-generate diagrams for living documentation

• Easily identify who changed a specific part of a flow (e.g. Git Blame)

Follow me on LinkedIn if you’d like to track my progress on this.

Conclusion

This was a straightforward tool to build but proved very useful. It is also a great project for someone to try out who may not have built anything using Genesys Cloud’s EventBridge Integration before.

If you do build it, or already have then I’d love to hear about your experiences. Just ping me on LinkedIn.

I set out to add a real-time transcript (which was enriched in real-time too) into a UI that already had a Genesys Cloud softphone, backed by Genesys’s Embedded Framework.

It's worth mentioning that although Agent Assist displays a live transcript, you cannot enrich it within the UI e.g. tracking real-time sentiment, personalised entity extraction, etc. This was one of the reasons I built a custom implementation.

So, the first question was how I was going to access the transcript...

Approaches to accessing a real-time transcript

Genesys Cloud has two methods for accessing a real-time transcript, both easy to integrate with, but each designed for different use-cases. In my case the Notifications API was an obvious fit, as I will explain below.

AWS EventBridge Integration

Genesys Cloud’s Amazon EventBridge integration can deliver real-time data, from an ever growing list of topics, to EventBridge in your AWS account. From there you can filter and route data wherever you like.

This approach is great if you want to process utterances in near real-time for analytical tasks (and other fun use-cases) but wasn't the right fit for what I was doing.

Notifications API

The Notifications API, with its support for delivering real-time events via WebSockets was perfect for my use-case, as it offers:

• Events scoped to the agent that is authenticated

• Low-latency. In my experience, this latency seemed to improve to 2 to 4 seconds around the same time Agent Assist was introduced - though this may be coincidental.

Iteration 1. Utilising the Embeddable Framework

After having made the decision to focus on the Notification API for streaming the real-time transcript of the agent/customer call, I prototyped the simplest solution based on the existing setup.

The simplest prototype I could come up with was:

1. Agent navigates to the UI

2. Genesys Cloud's Embedded Framework authenticates the agent against an OAuth Client

3. The auth token from the Embedded Framework is shared with my UI

4. My UI uses this token to talk to Genesys Cloud's Notification API and establish a WebSocket connection

5. It then listens for Conversation Started events from the Embedded Framework to determine when an agent starts a call that needs to be transcribed

6. Upon a call starting, my code requests the channel subscribe to the call’s live transcript

Iteration 2. Decoupling authentication

In the first iteration I chose to share the token for the Embedded Framework with my UI's code. But this is problematic...

The problem

In this initial prototype there were two problems, which had to be fixed before moving forward:

• I'd coupled my solution's authentication flow to Genesys Embedded Framework

• I had to share the token from Genesys Embedded Framework to my code (cross-origin), which increased the risk of it being exposed

At the code level this involved acquiring the token from getAuthToken inside the framework.js, then posting it to the window, which my UI could then receive:

window.PureCloud.subscribe([{
  type: "UserAction",
  callback: function(category) {
    if (category === 'login') {
      window.PureCloud.User.getAuthToken(function(accessToken) {
        // Security risk
        window.parent.postMessage({accessToken}, targetOrigin);
      });
    }
  }
}]);

Implementing this outside of the prototype could have exposed the access token to any JavaScript running in the parent window, along with other security concerns.

The solution

Both decoupling the auth flow and sharing the token were solved by having my solution manage its own authentication.

Implementing your own login flow for Genesys Cloud is as easy as creating an OAuth Client and calling their Platform API Client SDK:

const apiClient = platformClient.ApiClient.instance;  
apiClient  
  .loginPKCEGrant(clientId, redirectUri)  
  .then((authData) => {
    // ...
  }).catch((error) => {
    // ...
  })

Iteration 3. Preventing refreshes from losing utterances

One interesting problem I encountered was that transcription events were missed when agents refreshed their browser.

The reason was simple, during the page refresh the WebSocket connection to the Notification API was closed, then in spite of me promptly reestablishing it on the page loading there is a brief window where I am not subscribed to the topic. Any utterance sent during this period is lost, with no way of being replayed.

The solution happened to be a popup window…

Having wondered how the Genesys softphone maintained its audio connection I realised the obvious, it has a popup window, which survives any refresh of the page containing the softphone.

The code refactor for this change was big, and involved me shifting all the logic for authentication and Notification API subscription into the popup window.

The UI was now very thin, and was just receiving utterances emitted from the popup window via a Broadcast Channel - possible since they're in the same origin:

/* Within popup */

// Create channel
const channel = new BroadcastChannel("transcription-events");

// ...

// Post events from Notification API to channel 
this.ws.onmessage = (event: any) => {
  // ... validate and transform payload ... 
  
  channel.postMessage({
    type: "transcription-updated",
    data: transcriptionUpdate
  });
};

There was also logic written to monitor whether a popup window was already open, so I didn't open multiple of them.

What if my UI and Popup were on different domains?

The Broadcast Channel above only works because the UI and popup are on the same domain. If they weren't then they would be considered 'cross-origin', resulting in a lot more restrictions by the browser in how they can communicate. In this case I would have relied on the much inferior postMessage call.

/* Within UI */

// Open popup
const popupRef = window.open(
  popupUrl,
  popupName,
  'width=450px,height=450px,status,opener',
);

// Send message to popup
popupRef.postMessage(event, origin);

// Receive messages from popup
window.addEventListener('message', (event: MessageEvent) => {
  // ... Validate event.origin ...
  // ... Validate payload ...
  
  processMessageFromPopup(event);
});

Conclusion

This was a fairly brief look into the iterations that went into building a resilient and secure real-time transcript feature based on Genesys Cloud's Notification API.

I hope that in spite of its brevity, it was of some interest. It was certainly cathartic to write!

If anything here sparked an idea or improvement then I'd love to know! I’m also very happy to answer any questions you may have, just ping me on LinkedIn.

My end-to-end tests have three stages:

1. Automate a call to a phone number setup in a Genesys Cloud org and simulate a customer speaking

2. Answer the call in the softphone and simulate an agent speaking

3. Assert the feature I’ve developed behaves as expected

If the assertions pass then I know my feature is correctly integrated and using Genesys Cloud’s Notification API, Embedded Framework and Softphone. This reduced feedback loop allows me to develop the UI feature much faster, and with greater confidence than if I relied solely on manual testing.

Tools I use

Below are the tools I use for my tests, and what they were used for:

1. Puppeteer - Opening the website containing my feature and giving me control of the page to do step 2 and 3

2. MediaStream API Mocker - Overriding the MediaStream API so I could receive the audio the agent would hear and stream audio simulating the agent speaking

3. Softphone UI POM - Simplifying the control of Genesys Cloud’s Softphone in the website, making it easy to answer a call the way an agent would and ensuring the same events are fired from the Embedded Framework as you’d expect in the real scenario

4. IVR Tester - Phones the agent and pretends to be the customer

How the tests work

Opening the website under test

The website containing my feature, and the softphone are controlled via a Puppeteer test script. The first step of this test script is to launch the browser and point it to my website:

const browser = await puppeteer.launch({
  headless: false,
  userDataDir: "./user_data",
  defaultViewport: null,
  args: [
    "--use-fake-device-for-media-stream",
    "--disable-features=site-per-process",
    "--allow-file-access",
    "--no-sandbox",
    "--autoplay-policy=no-user-gesture-required"
  ],
});

const page = await browser.newPage();
await page.goto("http://localhost:8080");

The following two parameters from above ensure I can manually perform the browser-based auth required by the softphone, and persist the token for future tests:

headless: false,
userDataDir: "./user_data",

Although I prefer to login manually for the first test, and have the token reused for future tests until it expires, you could just automate the login process too.

Impersonating an agent over the softphone

The confidence that my feature will work comes from the fact the tests are as realistic as possible, and one facet of this is simulating the agent speaking over the sofphone.

To achieve this I override the Browser’s MediaStream API which is the mechanism through which the softphone receives audio from the agent’s headset. This allows me to:

• Capture the audio coming from the softphone

• Stream my own audio that goes to the softphone

Overriding the MediaStream API

Firstly, there is an option available when opening the browser to specify an audio file that it will play over a Media Device (below), however this is simply played on repeat. I want to control what is said and when.

--use-file-for-fake-audio-capture=<PATH-TO-FILE>

The solution I use is Puppeteer’s .evaluate(...) function. This function allows me to run code inside any browser window, which means I can run code inside the softphone’s iframe that replaces the MediaStreams API with a mock. I can then control the audio coming in and out of this mock:

// 1. Read in the JS code for mocking the MediaStreams API
const mockMediaDevicesScript = readFileSync(
"https://gist.githubusercontent.com/SketchingDev/00128173c26dae841a5057803fa4503a/raw/fea356b4117c6981693e8ac9eea2f3c52261ac45/mocked_media_stream.bundle.js",
"utf8");

// 2. Get IFrame for WebRTC phone
const webRtcFrame = await browser.waitForTarget((page) =>
   page.url().includes("/crm/webrtc.html"),
);

// 3. Run the script within the WebRTC frame to replace the MediaStream API
await webRtcFrame.evaluate(mockMediaDevicesScript);

// 4. Run a JavaScript function within the IFrame when you want to play an audio file against the MediaStream
webRtcFrame.evaluate((fileNameIn) => {
    window.mockMediaDevice.playAudio(fileNameIn);
}, `http://localhost:8080/${filename}`);

See my full guide on mocking the MediaStream API.

Phoning as the customer

IVR Tester is an open-source project I built that uses Twilio to automate a customer calling a phone number. The code (based on an ongoing project rewrite) to call the agent’s queue looks like:

const result = await ivrTester.run(
  { from: "0123 456 789", to: process.env.GENESYS_PHONE_NUMBER },
  openAiWhisperChat("You are a customer wanting to ....")
)

I’ve not gone into detail on this part as I would like to dedicate a blog article to demonstrating how to make AI-driven calls for testing. Subscribe, or follow me on LinkedIn to know when I post the article.

Subscribe now

Answering as the agent

Answering a call via the softphone is done by simulating clicks within the softphone’s UI. Here is the code that uses a Page Object Model I created to simplify answering the call by waiting for a call and then clicking the Answer button:

// 1. Find the softphone page
const frame = await page.waitForFrame((frame) =>
  frame.url().includes("/crm/embeddableFramework.html"),
);

// 2. Pass that into the softphone helper
const softphone = await webRtcSoftphone(frame);

// 3. Waits at most 30 seconds for a call to answer
await softphone.waitForCallThenAnswer(30000);

I have shared the code for the Page Object Mode in GitHub.

Listening to the simulated customer

It would have been sufficient for my purposes to have the simulated customer and agent speaking across each other with phrases my feature was designed to pick up on. However, where would the fun be in that, so I instead leveraged Genesys Cloud’s transcription topic to get the agent to respond with a sensible reply, allowing the agent and customer to converse thanks to OpenAI’s APIs.

Asserting the UI behaviour

As the test conversation progressed I checked my feature was behaving as expected. Here’s an example of some of the code checking that the customer’s name was correctly extracted:

const customerFullName = await page.$eval(
  "input#staticFullName",
  (input) => input.value,
);

assert.strictEqual(customerFullName, "Mr Test");

It is possible to integrate Puppeteer into Jest, allowing you to take advantage of existing Jest assertions.

Conclusion

Hopefully breaking down each part of my automated tests has shown how easy they are to setup. With these tests I can quickly iterate on my feature with confidence that it is behaving as expected.

It’s worth pointing out that end to end tests should be used sparingly, as they take longer to run and usually become flaky over time. The testing pyramid offers a sensible breakdown of the ratio of each type of test.

Undoubtedly there are many improvements to be made, and if you find any I’d love to hear about them!

Let’s jump straight in and install the tool!

Installing Genesys Cloud Chatbot Tester

Genesys Cloud Chatbot Tester is a command-line application you install on your machine. It’s free, open-source, works on Windows, Mac and Linux and is versatile enough to be integrated into automated pipelines, as well as run locally on your machine.

Although we’ll be creating an AI-based test, you can also use it to write more conventional dialogue based tests.

To install it just open the command-line and run:

npm install -g @makingchatbots/genesys-cloud-chatbot-tester-cli

If your computer complains that you don’t have NPM or Node.js then you can download the installer at nodejs.org.

Creating an API key for OpenAI

The testing tool leverages OpenAI’s ChatGPT to realistically converse with your chatbots during the tests. However, to be able to use OpenAI’s API you will need an API key.

Getting an API key is as easy as:

1. Going to OpenAI and creating an account (if you don’t already have one)

2. Following their instructions for creating an API key

3. Following their guide to set your API Key on the same computer as the testing tool

Whilst my tool is free, using OpenAI’s API is not - although its pricing seems reasonable, and is usage based.

Writing our automated AI test

Now the fun part, writing our test. A test is defined in a file (a YAML formatted file to be precise) and contains 3 notable parts:

1. deploymentId - The ID of our Web Messenger Deployment that we want to test

2. prompt - The Prompt used to instruct ChatGPT how we want it to interact with our bot (more on this below)

3. terminatingPhrases - The phrases we want the testing tool to look out for that indicate whether the test passed or failed

We can see these 3 parts in the config file for our test:

config:
  deploymentId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  region: xxxx.pure.cloud
  ai:
    provider: chatgpt
scenarios:
  "Chatbot recognises ISBN numbers":
    setup:
      prompt: |
        I want you to play the role of a customer talking to a company's
        online chatbot. You must not break from this role, and all of
        your responses must be based on how a customer would
        realistically talk to a company's chatbot.

        To help you play the role of a customer consider the following 
        points when writing a response:
          * Respond to questions as a customer would to a chatbot
          * Answer with the exact word when given options e.g. if asked
            to answer with either 'yes' or 'no' answer with either 'yes'
            or 'no' without punctuation, such as full stops

        As a customer you would like to get more information for a book,
        based on its ISBN.
        Provide the ISBN 0141439513 and if the title is Jane Austen's
        Pride and Prejudice then say 'PASS' else say 'FAIL' along with
        the reason why you failed.

        If you have understood your role and the purpose of your
        conversation with the company's chatbot then say the word
        'Hello' and nothing else.
      terminatingPhrases:
        pass: ["PASS"]
        fail: ["FAIL"]

Instructing ChatGPT on what to test

The prompt section instructs ChatGPT of the role it will be playing when conversing with our chatbot, and what we want it to achieve.

Getting the prompt just right for your tests can involve a bit of trial and error, but there are plenty of guides to help you.

Deciding when a test passes or fails

The terminatingPhrases are what my tool is looking out for during the conversation. Depending on which one it sees in the response from ChatGPT it will either pass or fail the test.

In the test above the prompt is instructing ChatGPT to use the words PASS or FAIL.

Running the test

With the tool installed, OpenAI’s key set and a test file defined we can now run the test! This is as easy as running the command below and pointing it at the test file we defined above:

genesys-cloud-chatbot-tester ai test.yaml

It’s that simple! If you end up using this tool I’d love to hear how you got on, or what improvements you think could be made to the tool.

Like what you read? Follow me on LinkedIn to be notified of future articles.

So far the tool has:

• Alerted us to major incidents within seconds of the first customer being affected

• Provided a realtime insight into customer behaviour across flows and chatbots

• Measured the success of A/B testing

• Detected unexpected behaviour, allowing us to pinpoint the external factors influencing customers

• Allowed all the above to be correlated to services across the business e.g. aiding us in pinpointing the service that is causing slowdown in a flow

Here’s an example dashboard that leverages the metrics produced by the tool:

How does it work?

The tool is very simple. It captures specially formatted Participant Data attributes set in flows and uses these to indicate metrics that it pushes to our observability/monitoring platform, DataDog. Once in DataDog we can create dashboards, detect anomalies, correlate metrics with other OVO services and much more…

Under the hood, the tool uses Genesys Cloud’s EventBridge Integration to capture AttributeUpdated events which it processes with Lambdas. The Lambdas filter out these ‘metric’ attributes, determines which have changed using DynamoDB then pushes a custom metric to DataDog - although it could be configured to push the metrics anywhere.

It takes approx 40 seconds between capturing a new/updated attribute to the metric appearing on a dashboard. It can process over 4.5 million events a month for $40.

Why I didn’t use:

Flow Milestones

Genesys Cloud already has a method of capturing custom metrics within a flow called Flow Milestones. However I didn’t use them because:

• All our services that the Architect flows depend on also use DataDog, so being able to consolidate and correlate metrics in one place allows us to quickly detect patterns and diagnose issues

• Participant Attributes are visible Genesys Cloud’s Conversation UI, so we can use these ‘metric’ attributes in to debug errors

• DataDog has many many features for monitoring, graphing and exploring metrics that we can now use

Data Actions

Data Actions are the obvious choice for pushing data out of a flow, but they were’t suitable for this tool for two reasons:

• They have limits which apply to the whole organisation so shouldn’t be overused

• They’re visually noisy, so placing them all over your flows would create some very messy looking flows

A deeper dive into how it works

Let’s break apart the solution and provide a little more detail on how it works…

‘Encoding’ metrics in Participant Data Attributes

It all starts with the flow setting specially formatted Participant Data attributes. The format of these Attributes’ names allows my code (which we’ll discuss later) to discern them from the non-metric attributes:

Format: <Flow Name>Metric_<Metric Name>(<DateTime in UTC>)
Example: CustomerRoutingMetric_Unknown(2023-03-05T08:18:04.568Z)

If an attribute matches this format then it extracts the:

• Flow & Metric Name - The combination of which is unique to a flow preventing duplications across flows

• DateTime - This ensures the attribute’s name is unique, so the same metric can be set multiple times in a conversation

The value of the attribute is ignored, as the solution only counts the occurrences of metrics within time intervals.

Capturing when Attributes are set

For my code to know that a Participant Attribute has been set, updated or deleted, I’ve configured Genesys Cloud’s EventBridge Integration to produce AttributeUpdated events. Upon EventBridge receiving these events it will invoke my Lambda function - more on Lambdas in the next section.

The AttributeUpdated event that my code processes contains the Conversation’s ID and all the attributes associated to it, even those that didn’t change since the last event.

{
  // ...
  eventBody: {
    // ...
    conversationId: "12341234-1234-1234-1234-123456789012",
    attributes: {
      "CustomerRoutingMetric_Unknown(2023-03-05T08:18:04.568Z)": "1",
      "AccountID": "0-000000"
      }
  }
}

Extracting the Metrics from Attributes

When the Lambda function is invoked with an Attribute Updated event (which is per conversation) my code will:

1. Extract only attributes representing metrics, based on the previously mentioned format

2. Determine which metric attributes have changed by comparing them to the previous event for the conversation, which are saved in a key-value store called DynamoDB

3. Push custom metrics to DataDog. The name of these metrics is based on the name of the metric attribute

4. Save the event to DynamoDB for determining what attributes have changed in the next event

I just mentioned two technologies, which I’ve described below for those who don’t know them:

• AWS Lambda is a ‘serverless, event-driven compute service that lets you run code for virtually any type of application or backend service without provisioning or managing servers’

• AWS DynamoDB is a ‘fast, flexible NoSQL database service for single-digit millisecond performance at any scale’

Both of these technologies are pay-per-use, so we’re only charged when they’re being used. They can also scale automatically to handle traffic throughout the day.

DataDog

The Lambda function uses DataDog’s Lambda Layer to push Custom Metrics to DataDog. This layer handles the complexity of collecting and sending metrics from concurrent Lambda invocations.

The power and simplicity of DataDog does come at a price though, with custom metrics costing approx $5 per 100 custom metrics - with a custom metric being the combination of name and tags.

Conclusion

Thanks to Genesys Cloud’s increasing integrations to other tooling, I’ve been able to quickly build a solution which has allowed me to continue my aim of bringing the development and monitoring of our Flows and Bots closer to that of building software.

You can read my other articles on this subject here:

• Automating development of Genesys chatbots

• Automate testing Genesys’ Web Messenger

Like what you read? Follow me on LinkedIn to be notified of future articles.

The automated pipeline, known formally as a CI/CD pipeline is triggered against every change and will:

1. Automatically deploy the bot and its dependencies to test environments

2. Run a suite of automated tests to assert the behaviour of the new functionality, and catch any regressions in existing functionality

3. Enforce that tests pass and changes are peer-reviewed before being able to progress

4. Once approved it automatically deploys changes to a User Acceptance Testing (UAT) environment

5. Notifies a QA Engineer to perform exploratory testing

6. Once approved by a QA Engineer then automatically deploy changes to production

The more obvious benefits of this are:

• Reducing the feedback loop from hours/days to seconds/minutes

• Deployments of chatbots and their dependencies that are identical across environments. If it works in UAT, it will work in Prod.

• Assurance of quality through automated tests. Every change, no matter how small is subjected to over 40 end-to-end tests - and since they are run concurrently they take less than 2 mins

Implementation

Let’s break down the pipeline and examine each part of it…

Source-control

All the flows, chatbots, dependencies, tests, and even the definition of the pipeline itself live in source-control - which for OVO is GitHub. This git repository forms the source of truth.

When an update or revert occurs against anything in the repository then it is tracked (by virtue of it being in source-control) and the automated pipeline is triggered. Only when all the pipeline’s checks pass will the change make its way to production.

Pipeline

The pipeline is defined in the human-readable language YAML and is executed by CircleCI. It defines what each step does and the order they do it.

# Job definitions redacted

workflows:
  development:
    jobs:
      - terraform-autoapply-dev:
          filters: *ignore-main-branch
          context:
            - aws-dev
            - genesys-dev
      - test-web-messaging:
          filters: *ignore-main-branch
          requires:
            - terraform-autoapply-dev
      - test-ivr-flow:
          filters: *ignore-main-branch
          requires:
            - terraform-autoapply-dev
  main:
    jobs:
      - terraform-autoapply-uat:
          filters: *only-main-branch
          context:
            - aws-uat
            - genesys-uat
      - manual-testing:
          type: approval
          requires:
            - terraform-autoapply-uat
      - terraform-apply-prod:
          filters: *only-main-branch
          context:
            - aws-prod
            - genesys-prod
          requires:
            - manual-testing

Deploy using Terraform

Terraform offers a way to declaratively define resources that you want it to deploy. This way you know that the deployments will always match what is in source-control.

Since many providers support Terraform we can define everything in one place; from chatbots, flows, data-actions to their backend services. Here’s an example of a Terraform definition:

resource "genesyscloud_integration_action" "create_survery_data_action" {
  # Prevent any change that creates a new UUID
  lifecycle {
    prevent_destroy = true
  }
  name           = "Create Survey (created via Terraform)"
  category       = "Web Services Data Actions"
  integration_id = var.integration_id
  secure         = false
  config_request {
    // ...
  }
  config_response {
    // ...
  }
  contract_input = <<DEFINITION
        // ...
        DEFINITION
  contract_output = <<DEFINITION
        // ...
        DEFINITION
}

resource "genesyscloud_flow" "flow" {
  filepath          = var.flow_file
  file_content_hash = filesha256(var.flow_file)

  substitutions = {
    flow_name     = "${var.flow_name} - (created via Terraform)"
    flow_division = var.flow_division
    data_action_name = genesyscloud_integration_action.create_survery_data_action.name
  }
}

data "genesyscloud_webdeployments_configuration" "config" {
  name = var.web_deployments_configuration
}

resource "genesyscloud_webdeployments_deployment" "survey_deployment" {
  name              = "Survey - (created via Terraform)"
  flow_id           = genesyscloud_flow.flow.id
  allow_all_domains = true

  configuration {
    id      = data.genesyscloud_webdeployments_configuration.config.id
    version = data.genesyscloud_webdeployments_configuration.config.version
  }
}

Automated testing

The tools we use at OVO to automate the testing of chatbots are written by me, and as such are open-source:

• Web Messenger Tester for testing Inbound Message flows via a Web Messenger Deployment

  • Since the WhatsApp integration uses Incoming Message Flows it means we can also test WhatsApp-specific chatbots with this tool

• IVR Tester for testing IVR flows

  • This can test our IVR-based chatbots flows by impersonating a customer calling OVO, interpreting what it hears, and responding accordingly to traverse the journey. Any unexpected response is flagged

Both tools define their tests in files that can be stored alongside the chatbots in source-control and act as living documentation:

scenarios:
  "Customer asked to score experience if they say yes":
    - say: Thank you, bye
    - waitForReplyContaining: Before you go could you answer a quick survey?
    - say: yes
    - waitForReplyContaining: Overall, how satisfied or dissatisfied are you with our company?
    - say: "10"
    - waitForReplyContaining: We thank you for your time spent taking this survey. Your response has been recorded.
  "Conversation ended if they say no":
    - say: Thank you, bye
    - waitForReplyContaining: Before you go could you answer a quick survey?
    - say: no
    - waitForReplyContaining: We hope you have a nice day, goodbye

Conclusion

This has been a whistle-stop tour of the pipeline and the benefits it brought us. Hopefully, it has provided enough information for you to get started with your own pipelines.

Like what you read? Follow me on LinkedIn to be notified of future articles.

In this article I will guide you through how to write automated tests for Genesys’ Web Messenger using a tool I wrote (in the absence of any others) aptly named Genesys Cloud Chatbot Tester. As an aside, we use this tool at OVO as part of a CI/CD process to test our chatbots before they’re deployed to production.

If you want to see the tool and its code head on over to Genesys Cloud Chatbot Tester on GitHub, or check out its documentation.

Writing automated tests

The tool I’ve written uses Web Messenger’s guest API to simulate a customer talking to a Web Messenger Deployment. Once the tool starts an interaction it follows instructions defined in a file called a ‘test-script’, which tells it what to say and what it should expect in response. If the response deviates from the test-script then the tool flags the test as a failure, otherwise the test passes.

It’s all pretty straight forward, and as a bonus, because the test-script looks a lot like a transcript (as you’ll see later) it can be shared with the wider business as documentation on how your messenger flow works from a customer’s perspective.

Now we have an overview let’s press on with installing the tool and writing a test for a highly contrived chatbot…

1. Install the prerequisites

Firstly, we need to download and install the Node.js runtime. This will allow you to install and run the testing tool.

2. Install the tool

Next install the Genesys Cloud Chatbot Tester tool by running the following in Command Prompt for Windows, or Terminal for Mac/Linux:

npm install -g @makingchatbots/genesys-cloud-chatbot-tester-cli

Once installed you can run the command genesys-cloud-chatbot-tester --help to see how to use the tool.

$ genesys-cloud-chatbot-tester --help
Usage: index [options] <filePath>

Arguments:
  filePath                             Path of the YAML test-script file

Options:
  -id, --deployment-id <deploymentId>  Web Messenger Deployment's ID
  -r, --region <region>                Region of Genesys instance that hosts the Web Messenger Deployment
  -o, --origin <origin>                Origin domain used for restricting Web Messenger Deployment
  -p, --parallel <number>              Maximum scenarios to run in parallel (default: 1)
  -h, --help                           display help for command

3. Write a Test-Script

We are now ready to write a test-script for a Web Messenger Deployment.

The highly contrived chatbot that we’ll use as the subject of our test does the following:

1. Asks the customer for their name

2. Greets them by their name and asks how it may help

The test-script for such as simple bot is equally simple:

# test-script.yaml

config:
  deploymentId: 12345c7d-123a-123a-1f3d-a104e02a86a7
  region: usw2.pure.cloud
scenarios:
  "Customer is greeted by the name they provide":
    - say: hi
    - waitForReplyContaining: what is your name?
    - say: Lucas
    - waitForReplyContaining: Hello Lucas, how may I help you today?

The test-script is written in a format known as YAML, and consists of two sections:

Config

This section contains the attributes necessary for the tool to find the Messenger Deployment it will test:

• deploymentId - ID for the messenger deployment taken from the Messenger Deployment page

• region - Region of the Genesys instance that manages the Messenger Deployment (see your region in the Genesys URL)

Scenarios

This section contains a list of scenarios that you want to test, along with the instructions of what to say/expect beneath each of them. In this case there is only one scenario, but in reality you’d have many more.

4. Run the test

The final and most satisfying part is now upon us, running the tests! It’s pretty straightforward, you just point the Web Messaging Tester tool at the test-script file:

genesys-cloud-chatbot-tester test-script.yaml

Then watch it test the deployment:

Conclusion

Hopefully this article has shown how easy it is to test Web Messenger Deployments, along with the advantages that come with automation! However, automated testing doesn’t have to stop here… I’m working on another tool for automating the testing of call flows which I’d like to blog about soon.

Lastly, if you have any questions about the tool discussed in this article then checkout the documentation or message me on LinkedIn.

WARNING: The tool used below should never be used to spy on Data Actions that are used by real customers. It terminates after a fixed period of time, has limited bandwidth and may leak secrets.

Overview

We will intercept a Data Action’s requests by configuring the Data Action to point at a tunnel created by a tool called ngrok. This tunnel will forward requests to the Data Action’s original URL, and importantly will allow us to inspect any request that passes through it.

Installing ngrok

Creating the tunnel will require ngrok to be installed locally by following the steps:

1. Follow the official instructions to install ngrok

2. Sign up for a free account. You’ll need this to be able to configure the proxy

3. Configure ngrok with an auth token from the account you set up above

Creating a tunnel

Create the tunnel by running the following command, configured with the host from the Data Action’s URL

ngrok http -host-header=<host> <host>:<port>

• -host-header=<host> - Set the host-header switch to the host of the Data Action’s current URL

• <host>:<port> - Set this to the host and port of the Data Action’s current URL

Example

If the Data Action’s URL is

https://example.com/account/${input.AccountId} 

Then the command will be:

ngrok http -host-header=example.com example.com:443

Port 443 = HTTPS

Configuring the Data Action

When you run the ngrok command in the previous step you’ll be presented with the output below. Contained within this output is the randomly generated forwarding address. We will configure our Data Action to use this URL.

ngrok by @inconshreveable                                                                                                                                                                   (Ctrl+C to quit)

Session Status                online
Account                       xxxx@xxxx.com (Plan: Free)
Version                       2.3.35
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://12abc-12abc-12abc.ngrok.io -> https://example.com:443

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Update the Data Action’s URL

1. Take the forwarding address from output, which in the example above is:

   https://12abc-12abc-12abc.ngrok.io
   

2. Update the Request URL Template in the Data Action to use the forwarding address:

   https://12abc-12abc-12abc.ngrok.io/account/${input.AccountId}
   

Inspect requests

Now ngrok is running and your Data Action is pointing at ngrok’s forwarding address (aka tunnel) you can inspect HTTP(S) traffic going through it.

Navigate to http://127.0.0.1:4040/inspect/http to see the traffic, or follow the official guide.

Cleanup

When you close ngrok it will also close the tunnel (which is unique each time), so you’ll have to revert your Data Action’s URL after inspecting the traffic.

Like what you read? Follow me on LinkedIn to be notified of future articles.

Having recently helped develop such IVR flows, I’ve been surprised by the lack of freely available tooling to automate testing them. I’ve instead been subjected to manually calling the flow each time I wanted to test a change - a slow and erroneous process.

To ease my suffering, I’m creating IVR Tester, a tool that automates calling IVR flows and traversing them based on what it hears. The benefits of such a tool are:

• Customers get value quicker. Those developing flows don’t have to waste time manually calling them each time they them want to regression test it (reducing cycle time)

• Synthetic testing can be set up to routinely test that production call flows are working as expected from the customer’s perspective

• End-to-end tests can test flows and their integrations, as part of a continuous delivery pipeline

Developing this tool has been an interesting journey and one I’d like to share with you from a high-level (hopefully non-technical) perspective. You can read IVR Tester’s documentation for a more technical overview.

Let us begin by observing a human interacting with a call flow…

How a human interacts with an IVR call flow

From the customer’s perspective they:

1. Call the number from their phone

2. Hear a (often computer generated) voice asking a question, e.g. “Press 1 to make an appointment or press 2 to …”

3. Respond by either speaking a word, or more likely by pressing a key on the keypad

4. Repeat from step 2 until their query is resolved, they’re forwarded to a human, or they hang up in frustration

Simulating a human interacting with an IVR call flow

Let’s tackle each step and build out our application as we go. We start with a blank application that runs on any computer.

Calling the IVR flow

Calling a phone number is a complicated business, but thankfully companies like Twilio abstract away this complexity. In Twilio’s case, they offer their MediaStream API, which can call a phone number and then establish a bi-directional audio stream with our application. Our application is then capable of listening to a call’s audio, and responding with its own audio.

Once plumbed in, it is a 3-step process to establish a call:

1. Our application requests that Twilio makes the phone call for us

2. Twilio does the complicated business of making the call

3. Twilio then establishes the bi-directional audio stream with our application

If you’re interested, you can see what the code looks like to achieve this: TwilioCaller.ts

We now have our call. The next problem is trying to understand what the IVR call flow is asking us…

Hearing the IVR flow

Millions of years of evolution and a basic education means that us humans can understand the flow’s audio prompts with ease, however computers haven’t been so fortunate. To provide the application with a basic recognition capability, we’re going to transcribe the audio, as text is much easier to perform matches against (which we’ll do later on).

The two main providers for transcribing audio streams are Google’s Speech-to-Text and Amazon’s Transcribe. Although both APIs are very similar, Google’s is more geared towards telephony, as it allows you to provide the telephony standard audio format of 8-bit PCM mono uLaw (8Khz sampling rate) and has a model pre-trained for phone calls.

Once again, here’s the code if you’re interested: GoogleSpeechToText.ts

Now when we establish a call we can forward the audio to Google’s Speech-to-Text service and receive a transcription like below:

Please enter the numbers from your post code. For example, if your post code is a 12 8 B c. He would enter 12 indeed. Please. Breath has when you are finished

The observant amongst you will have noticed the last part makes no sense at all, and herein lies the Achilles heel of this approach. Transcriptions aren’t perfect (although they can be trained), so we have to be lenient to these mistakes, e.g. by matching on the section of text, “Please enter the numbers from your postcode”.

Responding to a question

Navigating a call flow is more reliably performed using your phone’s keypad - we’ve all had a frustrating experience with voice-recognition. Pressing your keypad works by producing a tone within the voice-frequency band that is unique to each key - known as DTMF or touch tones.

Producing them programmatically is beyond my expertise, however creating audio files that can be played back isn’t. These audio files can be easily created using Sound eXchange (SoX):

# Generates tone for '1' by combining 1209 Hz and 697 Hz sine waves
sox -n -r 8000 -t raw -e u-law -c 1 -b 8 1.raw synth 0.5 sin 1209 sin 697 pad 0 0.5

The application can now push the contents of these files onto the call’s audio stream to simulate a phone’s keypad being pressed.

When to play a response

Our application can now establish calls, transcribe their audio and simulate a keypad being pressed. However, it doesn’t yet know how to recognise an instruction in the transcription and what it should respond with - without this it cannot traverse an IVR flow.

Naturally, we don’t want to entangle these instructions within the application since they’ll be different for each flow, so instead we’ll create external files that define how our application should traverse a flow, like so:

const test = {
  name: "Customer is asked for their account number",
  instructions: inOrder([
    {
      whenPrompt: contains("please enter your account number"),
      then: press("1234567"),
    },
    // ...
  ]),
}

This example ‘definition file’ tells our application that when the call’s transcription contains “please enter your account number”, it should then simulate pressing the keys ‘1234567’ on the keypad. Hopefully our definition is also fluent enough to act as documentation for the flow too!

Putting it all together

After gluing it all together, and adding a few bells and whistles, you end up with something like IVR Tester.

Conclusion

This article has focused on just one of many interesting problems which come with making a tool like this. However, the most exciting of these will be integrating it into the testing of call flows used by hundreds of customers - a process that I will be sure to blog about!

Like what you read? Follow me on LinkedIn to be notified of future articles.