Amazon Connect chat handoff

Hand off a live webchat or SMS conversation from your PolyAI agent to an Amazon Connect chat agent. PolyAI calls the Connect StartChatContact API and then proxies messages between the end user and the Connect agent for the rest of the session.

Prerequisites

• An Amazon Connect instance with chat enabled.
• A chat contact flow in Connect that routes the conversation to the queue you want PolyAI to escalate into.
• An IAM role PolyAI can assume that grants connect:StartChatContact and the matching session policies. The role’s trust policy must allow sts:AssumeRole and sts:TagSession from the PolyAI worker account (PolyAI uses IRSA, which adds session tags on the assume-role call).

1. Configure Amazon Connect

1. In the AWS console, open Amazon Connect and note the Instance ID for the instance you want PolyAI to hand off into.
2. Open or create the chat contact flow that should receive PolyAI’s handoff and note the Contact flow ID. Make sure the flow routes to a queue that has live agents assigned.
3. Create or reuse an IAM role for PolyAI (for example PolyAIAccessConnect) and note the Role ARN.

2. Connect from Studio

In Agent Studio, open Integrations and click Connect on the Amazon Connect tile. Paste:

3. Write the handoff function

The handoff payload can include the Connect configuration inline. This is useful for testing or when different topics hand off to different Connect instances:

def transfer_to_connect(conv: Conversation):
    return {
        "utterance": "No problem, I'll transfer you to one of our agents now.",
        "handoff": {
            "text_chat": {
                "amazon_connect_integration": {
                    "instance_id": "12345678-aaaa-bbbb-cccc-1234567890ab",
                    "contact_flow_id": "abcdef12-3456-7890-abcd-ef1234567890",
                    "role_arn": "arn:aws:iam::123456789012:role/PolyAIAccessConnect",
                }
            }
        }
    }

You can also pass an optional user_display_name to set the name the live agent sees for the user.

4. Assign the function to a topic

Open the Knowledge topic that should escalate, add an Action, and select transfer_to_connect. The same function can be called from any flow step or directly via conv.call_handoff() for dynamic routing.

5. Verify

1. Start a session in your webchat widget and steer the conversation into the topic you wired the handoff to.
2. Confirm a new chat contact appears in the Amazon Connect agent workspace (Contact Control Panel) for the queue the contact flow routes to.
3. Reply from Connect and confirm the message is delivered back to the user inside the same widget.
4. End the contact from Connect and confirm the widget shows the conversation as closed.

If you see ResourceNotFoundException, the region is almost certainly wrong – set aws_region on the integration. If you see assume-role errors, confirm the trust policy allows both sts:AssumeRole and sts:TagSession from the PolyAI worker account.

Related pages