> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Initial Amazon Connect configuration

Before your Ada team can enable the Amazon Connect integration, complete the following prerequisite steps in your AWS account and Amazon Connect instance. Once finished, share the collected information with your Ada representative.

> **Note**
>
> This integration uses [Amazon Connect chat message streaming](https://docs.aws.amazon.com/connect/latest/adminguide/chat-message-streaming.html). Most modern Amazon Connect instances support this out of the box.

## Collect your Amazon Connect identifiers

You'll need the following information from your Amazon Connect setup before proceeding.

**To collect your Amazon Connect identifiers:**

1. **AWS Region** — the region where your Amazon Connect instance is hosted (e.g. `us-east-1`).
2. **Amazon Connect Instance ID** — visible in the AWS Console under **Amazon Connect → Instances**. The instance ID is the UUID after `/instance/` in the instance ARN.

## Create an SNS topic for chat streaming

The integration receives agent messages and chat-ended events from Amazon Connect through an Amazon SNS topic. Create a Standard SNS topic in the same region as your Amazon Connect instance.

**To create the SNS topic:**

1. In the AWS Console, navigate to **Amazon SNS → Topics** and create a new **Standard** topic in the **same AWS region as your Amazon Connect instance**. Name it something recognizable (e.g. `ada-amazon-connect-chat-events`).
2. Note the topic's **ARN** (Amazon Resource Name) — it has the format `arn:aws:sns:<region>:<account-id>:<topic-name>`.
3. Add an **access policy** to the topic that allows Amazon Connect to publish to it. Use the following statement, replacing `<topic-arn>`, `<region>`, `<account-id>`, and `<instance-id>` with your values:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "connect.amazonaws.com" },
      "Action": "sns:Publish",
      "Resource": "<topic-arn>",
      "Condition": {
        "ArnLike": {
          "aws:SourceArn": "arn:aws:connect:<region>:<account-id>:instance/<instance-id>/*"
        }
      }
    }
  ]
}
```

## Add an HTTPS subscription to the SNS topic

Amazon SNS needs to know where to deliver chat events. Add an HTTPS subscription to the SNS topic pointing at Ada's webhook URL for your AI Agent's cluster.

**To add the HTTPS subscription:**

1. In the AWS Console, navigate to **Amazon SNS → Topics** and select the topic you just created.
2. Click **Create subscription**.
3. Set the following values:
   * **Protocol:** `HTTPS`
   * **Endpoint:** Ada's webhook URL, based on your AI Agent's cluster:
     * **US & CA:** `https://solutions.ada.support/messaging-connectors/amazon-connect/webhooks/sns`
     * **EU:** `https://solutions.eu.ada.support/messaging-connectors/amazon-connect/webhooks/sns`
   * Leave all other settings as their defaults.
4. Click **Create subscription**.

> **Note**
>
> The subscription will be in **Pending confirmation** status until your Ada team confirms it. The SubscriptionConfirmation token from SNS is valid for 72 hours — if not confirmed within that window, delete and re-add the subscription.

## Create an IAM role or user for the integration

The integration calls the Amazon Connect APIs on your behalf using either an IAM role (recommended) or an IAM user. Complete one option only.

### Option A: Create an IAM role (recommended)

Create a dedicated IAM role that the integration assumes to call the Amazon Connect APIs on your behalf. No access keys are shared. If you haven't created a role for a third party before, see the AWS guide [Creating a role to delegate permissions to an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html).

**To create the IAM role:**

1. Generate an **External ID**: a new, random UUID used only for this integration (for example, run `uuidgen` on macOS or Linux, or `New-Guid` in Windows PowerShell). Don't use a name, a word, or a value used for another integration.
2. In the AWS IAM console, create a new role (e.g. `ada-amazon-connect-integration`) with the following trust policy, replacing `<ada-role-arn>` with the Ada role for your AI Agent's cluster and `<external-id>` with your External ID:
   * **US & CA:** `arn:aws:iam::848837241100:role/ada-amazon-connect-mc-prod-us`
   * **EU:** `arn:aws:iam::848837241100:role/ada-amazon-connect-mc-prod-eu`

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "AWS": "<ada-role-arn>" },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<external-id>"
        }
      }
    }
  ]
}
```

3. Attach an inline policy with the following permissions, replacing `<region>`, `<account-id>`, `<instance-id>`, and `<topic-name>` with your values:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "connect:StartChatContact",
        "connect:StartContactStreaming",
        "connect:DescribeQueue",
        "connect:GetEffectiveHoursOfOperations"
      ],
      "Resource": [
        "arn:aws:connect:<region>:<account-id>:instance/<instance-id>",
        "arn:aws:connect:<region>:<account-id>:instance/<instance-id>/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "sns:ConfirmSubscription",
        "sns:Unsubscribe"
      ],
      "Resource": "arn:aws:sns:<region>:<account-id>:<topic-name>"
    }
  ]
}
```

4. Note the role's **ARN**. It has the format `arn:aws:iam::<account-id>:role/<role-name>`.

> **Note**
>
> Use the Ada role for your **AI Agent's cluster** (the same cluster as the webhook URL above), not the AWS region of your Amazon Connect instance.

### Option B: Create an IAM user

Use this option only if you can't create an IAM role. Skip it if you completed Option A.

Create a dedicated IAM user that the integration uses to call the Amazon Connect APIs on your behalf.

**To create the IAM user:**

1. In the AWS IAM console, create a new user (e.g. `ada-amazon-connect-integration`).
2. Attach an inline policy with the following permissions, replacing `<region>`, `<account-id>`, `<instance-id>`, and `<topic-name>` with your values:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "connect:StartChatContact",
        "connect:StartContactStreaming",
        "connect:DescribeQueue",
        "connect:GetEffectiveHoursOfOperations",
        "connect:GetAttachedFile",
        "connect:StartAttachedFileUpload"
      ],
      "Resource": "arn:aws:connect:<region>:<account-id>:instance/<instance-id>/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "sns:ConfirmSubscription",
        "sns:Unsubscribe"
      ],
      "Resource": "arn:aws:sns:<region>:<account-id>:<topic-name>"
    }
  ]
}
```

3. Generate an **Access Key ID** and **Secret Access Key** pair for the user via **Security credentials → Create access key**.

## Forward queue events (optional)

The integration can record which Amazon Connect queue a chat entered, and when, on the conversation.

> **Note**
>
> This step is optional and needs no IAM role or user changes. Without it, the handoff works normally and the queue fields are left empty.

To enable this, create an Amazon EventBridge rule that forwards queue events to the SNS topic created above. Reuse that topic rather than creating a new one.

**To forward queue events:**

1. In the AWS account and region where your Amazon Connect instance lives, navigate to **Amazon EventBridge → Rules → Create rule**. Name it (e.g. `ada-amazon-connect-queue-events`) and leave the event bus set to **default**.
2. Choose **Custom pattern (JSON editor)** and paste the following event pattern. Keep it exactly as written. A broader pattern sends unrelated Amazon Connect events to the integration.

```json
{
  "source": ["aws.connect"],
  "detail-type": ["Amazon Connect Contact Event"],
  "detail": { "eventType": ["QUEUED"], "channel": ["CHAT"] }
}
```

3. Set the target type to **AWS service**, then **SNS topic**, and select the SNS topic created above.
4. Click **Create rule**.
   Selecting the topic as the target adds the permission EventBridge needs to publish to it. If you create the rule via Terraform or the CLI instead, add a statement to the topic's access policy allowing `events.amazonaws.com` to `sns:Publish`.
5. To confirm it works, run a test chat through a handoff, then open that conversation in Ada and select **Variables**.
   Under **Meta variables**, the following appear as the chat reaches the queue:
   * `agent_system_amazon-connect_queue_id`: the ID of the queue the chat entered
   * `agent_system_amazon-connect_queue_enqueued_at`: when the chat entered the queue

## Share with your Ada team

Once the prerequisites above are complete, share the following with your Ada representative. Your Ada team will complete the remaining backend configuration.

**If you created an IAM role:**

1. **AWS Region** (e.g. `us-east-1`)
2. **Amazon Connect Instance ID**
3. **SNS Topic ARN**
4. **Role ARN**
5. **External ID**: share this securely, not in a shared channel
6. *(Optional)* **Chat Duration** in minutes: sets the maximum lifetime of each chat session, between 60 and 10,080 minutes. If unset, Amazon Connect uses its default of 25 hours (1,500 minutes).

**If you created an IAM user:**

1. **AWS Region** (e.g. `us-east-1`)
2. **Amazon Connect Instance ID**
3. **SNS Topic ARN**
4. **AWS Access Key ID**
5. **AWS Secret Access Key** — share this securely, not in a shared channel
6. *(Optional)* **Chat Duration** in minutes: sets the maximum lifetime of each chat session, between 60 and 10,080 minutes. If unset, Amazon Connect uses its default of 25 hours (1,500 minutes).

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).