Configure the Amazon Connect handoff

After you complete the initial configuration and share your credentials, your Ada team will set up the backend integration. When that is complete, the Amazon Connect app will appear in Config → Apps in your AI Agent dashboard, and you can begin configuring the handoff block.

Your Ada team will complete the backend integration setup. Contact your Ada representative to confirm when this step is finished before proceeding.

Add the Amazon Connect block

Each handoff in Amazon Connect creates a Chat Contact routed through the Contact Flow you specify, with the conversation transcript sent as the initial message.

To add the Amazon Connect handoff block:

In your handoff answer, add the Amazon Connect block with action Handoff to a human agent.
The two required Ada ID fields — ada_conversation_id and ada_user_id — are pre-populated by the block automatically.
Fill in the required Amazon Connect Contact Flow ID (see How do I find the Contact Flow ID? in the FAQ below).
Optionally fill in any of the additional fields documented in the table below.

When a handoff successfully connects to Amazon Connect, the following meta-variables are set on the conversation and can be used for troubleshooting or reporting:

agent_system_amazon_connect_conversation_id — the Amazon Connect Contact ID
agent_system_amazon_connect_agent_id — the Amazon Connect ParticipantId of the agent (set when the agent sends their first message)

Handoff input fields

The Amazon Connect block accepts the following input fields.

Field	Required	Description
`ada_conversation_id`	Yes	Conversation ID. Populated by `@oauth/conversation_id`.
`ada_user_id`	Yes	End user ID. Populated by `@oauth/end_user_id`.
`amazon_connect_contact_flow_id`	Yes	The Amazon Connect Contact Flow ID that handles chat routing for this handoff.
`first_name`	No	End user first name. Combined with `last_name` to set the participant display name shown to the Amazon Connect agent.
`last_name`	No	End user last name. Combined with `first_name` to set the participant display name. If both are blank, the display name defaults to `Anonymous`.
`attributes`	No	JSON object of additional Amazon Connect Contact Attributes to set on the chat (e.g. `{"key1": "value1"}`). These can be referenced inside the Contact Flow for routing logic.
`transcript_summary`	No	Summary text appended after the conversation transcript when starting the Amazon Connect chat contact.

Test the integration

After your Ada team confirms the installation is complete, walk through the following sequence to verify the integration end-to-end.

To test the integration:

In AWS, navigate to Amazon SNS → Subscriptions and confirm that the subscription on your topic has status Confirmed. If it is still Pending, contact your Ada representative before continuing.
Trigger a test handoff from the AI Agent (for example, via a sandbox conversation that escalates to the new handoff answer).
In Amazon Connect, verify a new contact appears in the Contact Control Panel (CCP), routed through the Contact Flow you specified.
As the agent, send a reply to the contact. The message appears in the conversation.
End the contact in Amazon Connect (or wait for the configured chat duration to expire). The conversation resumes, allowing the end user to continue chatting with the AI Agent.

Frequently asked questions

Common questions about configuring and operating the Amazon Connect handoff are answered below.

How do I find the Contact Flow ID?

In the Amazon Connect admin UI, navigate to Routing → Contact Flows, click on the Contact Flow you want chats to route through, and copy the ID from Show additional flow information in the flow editor. Alternatively, the ID is the UUID after /contact-flow/ in the URL.

How are Contact Attributes passed through the handoff?

Use the attributes field for ad-hoc per-conversation Contact Attributes (a JSON object), or work with your Ada team to define custom named fields that appear as labeled inputs in the block. Both routes end up as Amazon Connect Contact Attributes on the resulting chat. See Custom contact attributes for details.

How long does the chat stay active?

The chat lifetime is governed by the chat duration value set during installation (between 60 and 10,080 minutes). If unset, Amazon Connect uses its default. When the duration is reached, Amazon Connect ends the contact and the handoff closes.

Does the handoff create or update a Customer Profile record in Amazon Connect?

No — Amazon Connect’s chat model does not have a persistent Customer Profile record. (Amazon Connect refers to individual conversations as Contacts, which is why each handoff is a new Chat Contact.) Each handoff sets the participant display name from first_name + last_name, and Contact Attributes from attributes and any custom fields. Mapping these values to a Customer Profile in Amazon Connect is done within the Contact Flow.