Amazon Connect Workers

Type: Amazon Connect Worker

An Amazon Connect worker will route a conversation to a live agent in Amazon Connect. If messages come in outside of the configured business hours automated messages from connect will respond to the user. A connect worker can be created through the CLI or as part of a bot through the Amazon Connect Blueprint.

Note: Amazon Connect workers cannot be interacted with directly by users, they must be transferred to an agent on Amazon Connect through a flow worker first.

Secrets

An AWS cross-account role is required in order to access Amazon Connect. Please see cross-account roles for more information.

Below is an example policy containing the required permissions which should be attached to the cross account role to allow the AWS connect worker to function correctly.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "connect:UpdateContactAttributes",
                "connect:StartChatContact",
                "connect:GetCurrentMetricData"
            ],
            "Resource": [
                "arn:aws:connect:${AWS::Region}:${AWS::AccountId}:instance/${ConnectInstanceId}/contact/*",
                "arn:aws:connect:${AWS::Region}:${AWS::AccountId}:instance/${ConnectInstanceId}/contact-flow/${ContactFlowId}",
                "arn:aws:connect:${AWS::Region}:${AWS::AccountId}:instance/${ConnectInstanceId}/queue/*"
            ]
        }
    ]
}

You should replace the values surrounded by ${} with values relative to your aws account and region. Where the placeholder values in the policy above are as follows:

  • ${AWS::Region} - is the region your AWS Connect instance is deployed and the region you are creating the cross account role in.

  • ${AWS::AccountId} - is your AWS Account Id where the AWS Connect instance is deployed and the account you are creating the cross account role in.

  • ${ConnectInstanceId} - is the AWS Connect instance id the worker is interacting with.

  • ${ContactFlowId} - is the contact flow id within the connect instance.

Other Amazon Connect fields

  • ContactFlowId: Flow in amazon connect that will be initiated.
  • InitialConnectionMessage: Configuration needed for Amazon Connect. Do not change.
    • Default: "{\"topic\":\"aws/subscribe\",\"content\":{\"topics\":[\"aws/chat\"]}}"
  • InstanceId: Instance of amazon connect.
  • Region: Region where the Amazon Connect bot is configured.
  • Secret: Cross-account role secret.

Creating an Amazon Connect worker through cli

Save this json to a file and create a worker using the cli command sb-cli worker create file.json. Note to replace the values for Secret, Region, InstanceId, InitialConnectionMessage, and ContactFlowId.

{
  "Data": {
    "ContactFlowId": "GUID for Contact Flow ID",
    "InitialConnectionMessage": "{\"topic\":\"aws/subscribe\",\"content\":{\"topics\":[\"aws/chat\"]}}",
    "InstanceId": "GUID for Connect Instance ID",
    "Region": "us-east-1",
    "Secret": "srn:vault::ORG:aws-cross-account-role:SECRETALIAS",
    "ShortLinkConfig": {
      "Config": {
        "Api": "https://squeeze.prod.servismatrix.com/standard",
        "ApiKey": "srn:vault::ORG:secret:squeeze"
      },
      "Type": "Squeeze"
    },
    "EgressTranslationConfig": {
      "ConnectorAlias": "EgressTranslateBaas",
      "SourceLanguageCode": "en",
      "TargetLanguageCode": "es"
    },
    "IngressTranslationConfig": {
      "ConnectorAlias": "IngressTranslateBaas",
      "SourceLanguageCode": "es",
      "TargetLanguageCode": "en"
    },
    "SlashCommands": {
      "/welcome": {
        "actions": [{
            "type": "content",
            "value": "welcomewithname"
          },
          {
            //Another valid botnet action
          }
        ],
        "description": "A welcome message with the users name"
      }
    },
    "AutoDisconnectEvents": [
      {
        "Description": "Timer to send a message after 10 seconds",
        "SecondsAfterAgentMessage": 10,
        "Type": "WARNING",
        "UserMessage": "It has been a while since we heard from you. We will disconnect your chat after 20 seconds of inactivity",
        "AgentMessage": "It has been 10 sec since the last heard from the user. After 20 seconds of inactivity, the chat will disconnect"
      },
      {
        "Description": "Timer to send a message after 20 seconds",
        "SecondsAfterAgentMessage": 20,
        "Type": "DISCONNECT",
        "UserMessage": "The session has been disconnected due to inactivity",
        "AgentMessage": "The session has been disconnected due to inactivity"
      }
    ],
  },
  "Description": "Worker that routes to livechat agents",
  "Enabled": true,
  "Name": "ConnectOne",
  "Type": "amazon-connect-worker"
}

Once you have created the worker using the CLI, it will return an ID for you. You need to then update/create a bot and place the filter worker at the top with the id and the type of amazon-connect-worker.

Creating and setting up an Amazon Connect worker with a Blueprint

  1. Create a contact flow on AWS Connect

    1. Go to the Amazon Connect console.
    2. Select ‘Contact Flows’ under ‘Routing’ on the dropdown menu on the left.
    3. Click the ‘Create contact flow’ button.
    4. Create a contact flow such as the following:

  2. Build your bot

    1. Navigate to the Bot designer and click “Create Bot”.
    2. Select the “Amazon Connect Bot” Blueprint.
    3. Enter a name for the bot. This name will be given to the flow worker bot. The bot with the connect worker will have the same name with “ConnectBot” appended to it.
    4. Enter a description, which is given to both bots.
    5. Under “Amazon Connect Configuration”, enter a region, connect instance ID, a contact flow ID, and a secret.
      • The instance ID and contact flow ID can be found in the URL of the contact flow page from earlier.
      • E.g. …/instance/123a456b-123a-456b-789c-0123456789ab/contact-flow/987z654y-987z-654y-321x-9876543210zy
    6. Build it!

  3. Test and adjust your bot

    1. Find the flow bot (not the connect bot) that was created in Bot Army and open its test page.
    2. Go to Amazon Connect and click the phone button to open a chat window.
    3. Send the bot a message through its test page.
    4. If the flow triggers a human handover, a notification will appear in the Amazon Connect chat window, prompting the user to connect to the bot, and a conversation is started.

Sample Baas for translation

Below is an example of the inbound translate:

{
  "Persona": "/images/blueprints/amazon-comprehend.svg",
  "Headers": {
    "content-type": "application/json"
  },
  "Organization": "shane",
  "Description": "Translate Language",
  "RequestMapping": {
    "TargetLanguageCode": {
      "type": "requestBody",
      "requestBodyPath": "$.TargetLanguageCode",
      "inputPath": "$.TargetLanguageCode"
    },
    "Text": {
      "type": "requestBody",
      "requestBodyPath": "$.Text",
      "inputPath": "$.Text"
    },
    "SourceLanguageCode": {
      "type": "requestBody",
      "requestBodyPath": "$.SourceLanguageCode",
      "inputPath": "$.SourceLanguageCode"
    }
  },
  "ResponseMapping": {},
  "Type": "aws-sdk",
  "Body": {},
  "Created": 1585215907115,
  "Credentials": "srn:vault::YOURORG:secretdoc:translatesecret",
  "Method": "translateText",
  "Endpoint": "Translate",
  "Alias": "IngressTranslateBaas",
}

Sample baas that can be used as slash command to send an email

This requires the customer email to be set in context.

The example slash command would be:

"SlashCommands": {
  "/email": {
    "description": "Send an email to the customer",
    "actions": [
      {
        "type": "executeApi",
        "value": "sendEmail"
      }
    ]
  }
}

Baas Example:


{
  "Persona": "/images/blueprints/Amazon-Simple-Email-Service-SES.png",
  "Organization": "shane",
  "Description": "!Ref:::Parameters.baasDescription",
  "RequestMapping": {
    "Email": {
      "type": "requestBody",
      "requestBodyPath": "$.Destination.ToAddresses[0]",
      "inputPath": "$.email"
    }
  },
  "ResponseMapping": {},
  "Type": "aws-sdk",
  "Body": {
    "Message": {
      "Body": {
        "Text": {
          "Data": "body of the email"
        }
      },
      "Subject": {
        "Data": "Subject here"
      }
    },
    "Source": "YOUR_SOURCE@EMAIL.HERE"
  },
  "Created": 1585815972627,
  "Credentials": "srn:vault::YOURORG:cross-account-role:somesecret",
  "Method": "sendEmail",
  "Endpoint": "SES",
  "Alias": "sendEmail",
  "Updated": 1585818222020,
}

Auto Disconnection

Adding AutoDisconnectEvent to your connect worker allows you to send messages and disconnect users N seconds after the agent has sent the customer a message.

   "AutoDisconnectEvents": [
      {
        "Description": "Timer to send a message after 10 seconds",
        "SecondsAfterAgentMessage": 10,
        "Type": "WARNING",
        "UserMessage": "It has been a while since we heard from you. We will disconnect your chat after 20 seconds of inactivity",
        "AgentMessage": "It has been 10 sec since the last heard from the user. After 20 seconds of inactivity, the chat will disconnect"
      },
      {
        "Description": "Timer to send a message after 20 seconds",
        "SecondsAfterAgentMessage": 20,
        "Type": "DISCONNECT",
        "UserMessage": "The session has been disconnected due to inactivity",
        "AgentMessage": "The session has been disconnected due to inactivity"
      }
    ]
  • Supported Types:
    • WARNING: Sends a message to the user/agent or both depending on configuration
    • DISCONNECT: Sends a message to the user/agent or both depending on configuration and then ends the conversation

Failover Region Configuration

Adding Failover Region Configuration to your worker allows you to specify additional Amazon Connect configurations for Amazon Connect instances in other AWS regions which can be used in the event of a failover.

"FailoverRegionConfig": {
      "ActiveFailoverRegion": "us-west-2-oregon",
      "FailoverRegions": [
        {
          "Secret": "srn:vault::acme:aws-cross-account-role:call-deflection-failover",
          "Region": "us-west-2",
          "InstanceId": "618c435d-1330-45a5-9834-285c5422de81",
          "ContactFlowId": "8949fcc8-9d49-4e97-8bb5-eba4a847f1a1",
          "Name": "us-west-2-oregon",
          "QueueId": "4f565c31-f091-4114-9ca0-c4751a166bf8"
        },
        {
          "Secret": "srn:vault::acme:aws-cross-account-role:call-deflection-failover",
          "Region": "us-west-3",
          "InstanceId": "6gdtuyjyc435d-1330-45a5-9834-285c5h22de81",
          "ContactFlowId": "894sdgrfcc8-9d49-4e97-8bb5-ebf4a847f1a1",
          "Name": "us-west-3-oregon",
          "QueueId": "5f565c31-f091-4114-9ca0-c4751a166bf8"
        }
      ]
    }

The properties are as follows:

  • FailoverRegionConfig: Optional, an optional object that contains failover region configurations

    • ActiveFailoverRegion: Optional, if provided this must match the Name of one of the failover region configurations to start using that failover configuration. If the Name does not match any of the failover region configuration names the primary region configuration will be used.

    • FailoverRegions: A list of failover region configurations which the worker can failover to.

      • Name: Required, the name of the failover configuration. The ActiveFailoverRegion references the active failover region by this name.
      • Secret: Required, a cross account role secret SRN with IAM permissions to interact with the failover connect instance.
      • Region: Required, the AWS Region the failover connect instance is in.
      • InstanceId: Required, the Amazon Connect failover instance id to use.
      • ContactFlowId: Required, the Amazon Connect failover contact flow id to use.
      • QueueId: Optional. the Amazon Connect failover queue id to use to obtain queue metrics from the failover region.

    • To activate a failover region set ActiveFailoverRegion to match the Name of one of the failover regions in the FailoverRegions list and update your worker. Once the worker is updated and the ActiveFailoverRegion points to a valid failover region your worker will start to communicate with the failover region.

    • To disable a failover region remove the ActiveFailoverRegion attribute from your worker and update the worker. Once the worker has been updated, your worker will being to communicate with the primary region Amazon Connect instance. In this case “primary region” refers to the amazon connect configuration at the root level of your worker configuration.

Returning from Transfer

When you return to the original Bot after being transferred to a bot containing an Amazon Connect Worker there are certain items available in context

  • SessionEndReason

Contains the reason the session with the connect worker has ended. Current values:

  1. UserLeft
  2. AgentLeft
  3. Error
  • LastKnownAgent

Contains the last known agent in the conversation in the form of

{ AgentName: "Agent" }
  • ParticipantId

This is the ID of the participant as Amazon Connect knows the user. This can be used to find a conversation in the Amazon Connect interface

  • SessionAutoDisconnected

Contains a boolean value determining whether the conversation was auto disconnected - true if so, false otherwise.

Setting a custom name for the customer

If you want to change the default name that comes out to agent on connect for the customer. You need to set the name in context. What ever name is set to in context will appear as the customers name and if no name is set, it defaults to the bot name. So say you wanted to use something like name-reference you can do something like follows

  1. Use a function with the following
msg.payload.user.name = msg.payload.context.FirstName + ' - ' + msg.payload.context.Reference
return msg;
  1. Add a setContext node and set the name to msg.payload.user.name this will then make the name appear in connect like botty - sb2314211