Amazon Connect

Overview

The Amazon Connect integration connects an Amazon Connect contact flow directly to an agent in ElevenAgents over Amazon Connect’s third-party AI agent protocol, an extension of the open A2A protocol. Amazon Connect owns telephony, routing, and the queue; ElevenAgents owns the conversation. No SIP trunk, Twilio number, or middleware is required. AWS documents the feature under Agent-to-agent collaboration; this guide covers the ElevenLabs specifics and the AWS steps needed to reach an ElevenLabs agent.

The same flow serves inbound calls and outbound contacts started with StartOutboundVoiceContact. When the ElevenLabs agent finishes, Amazon Connect continues your contact flow and branches on the outcome it received.

How the integration works

1. A contact flow reaches a Get customer input block that invokes an Amazon Lex V2 bot with the AMAZON.QInConnectIntent intent.
2. Amazon Connect’s orchestration AI agent hands the conversation off immediately to the third-party application you registered for ElevenLabs.
3. Amazon Connect opens a WebSocket to the ElevenLabs endpoint in the application’s AccessUrl, authenticating with the API key stored in AWS Secrets Manager.
4. Amazon Connect signals that the caller’s channel is live, then Amazon Connect and ElevenLabs exchange 16-bit linear PCM audio as A2A messages. Amazon Connect proposes the sample rate and ElevenLabs adopts it, so no audio format changes are needed on the agent.
5. When the agent ends the call, ElevenLabs finishes the session with a Complete outcome and the flow continues from the Lex block. An Escalate outcome, which routes the caller to a human queue, is supported on the wire and will be exposed through the transfer tool; see Transferring to a human.

Requirements

Before you begin, ensure you have:

1. An Amazon Connect instance on the Connect Customer tier with third-party AI agent support enabled for the account and Region.
2. An Amazon Q in Connect assistant associated with the instance.
3. AWS permissions to create KMS keys, Secrets Manager secrets, AppIntegrations applications, Connect security profiles, Amazon Q in Connect AI agents, Lex V2 bots, and contact flows.
4. An ElevenLabs workspace with the Amazon Connect transport enabled.
5. An ElevenLabs agent and a dedicated API key.
6. AWS CLI v2 and awscurl (pip install awscurl) for the calls whose request shapes are not in released CLI versions yet.

Configure ElevenLabs

Register the ElevenLabs application in AWS

Everything in this section is an API call. Set the values you will reuse once:

export AWS_REGION=<REGION>          # Region of your Amazon Connect instance
export ACCOUNT_ID=<ACCOUNT_ID>
export INSTANCE_ID=<INSTANCE_ID>    # Amazon Connect instance ID
export INSTANCE_ARN=arn:aws:connect:$AWS_REGION:$ACCOUNT_ID:instance/$INSTANCE_ID
export AGENT_ID=<AGENT_ID>          # ElevenLabs agent ID

aws qconnect create-assistant --name elevenlabs-assistant --type AGENT --region $AWS_REGION
aws connect create-integration-association --instance-id $INSTANCE_ID \
  --integration-type WISDOM_ASSISTANT --integration-arn <ASSISTANT_ARN> --region $AWS_REGION

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AccountAdmin",
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::<ACCOUNT_ID>:root" },
      "Action": "kms:*",
      "Resource": "*"
    },
    {
      "Sid": "AllowConnectDecrypt",
      "Effect": "Allow",
      "Principal": { "Service": "connect.amazonaws.com" },
      "Action": ["kms:Decrypt", "kms:DescribeKey"],
      "Resource": "*"
    }
  ]
}

KMS_KEY_ID=$(aws kms create-key --description "ElevenLabs agent API key" \
  --policy file://kms-key-policy.json --region $AWS_REGION \
  --query KeyMetadata.KeyId --output text)
SECRET_ARN=$(aws secretsmanager create-secret --name elevenlabs/agent-api-key \
  --kms-key-id "$KMS_KEY_ID" --secret-string file://elevenlabs-api-key.txt \
  --region $AWS_REGION --query ARN --output text)
rm elevenlabs-api-key.txt

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowConnectRead",
      "Effect": "Allow",
      "Principal": { "Service": "connect.amazonaws.com" },
      "Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"],
      "Resource": "<SECRET_ARN>"
    }
  ]
}

aws secretsmanager put-resource-policy --secret-id "$SECRET_ARN" \
  --resource-policy file://secret-resource-policy.json --region $AWS_REGION

{
  "Name": "elevenlabs-agent",
  "Namespace": "elevenlabs-agent",
  "Description": "ElevenLabs agent over the Amazon Connect A2A extension",
  "ApplicationType": "A2A_SERVER",
  "ApplicationSourceConfig": {
    "ExternalUrlConfig": {
      "AccessUrl": "wss://api.elevenlabs.io/v1/convai/conversation/amazon-connect/<AGENT_ID>"
    }
  },
  "AuthConfig": {
    "AuthType": "API_KEY",
    "CredentialProviderIdentifier": "<SECRET_ARN>"
  }
}

awscurl --service app-integrations --region $AWS_REGION -X POST \
  -H 'Content-Type: application/json' --data @create-application.json \
  "https://app-integrations.$AWS_REGION.amazonaws.com/applications"

aws appintegrations get-application --arn "$APPLICATION_ARN" --region $AWS_REGION

awscurl --service connect --region $AWS_REGION -X PUT -H 'Content-Type: application/json' \
  --data "{\"IntegrationArn\": \"$APPLICATION_ARN\", \"IntegrationType\": \"APPLICATION\"}" \
  "https://connect.$AWS_REGION.amazonaws.com/instance/$INSTANCE_ID/integration-associations"
aws connect list-integration-associations --instance-id $INSTANCE_ID \
  --integration-type APPLICATION --region $AWS_REGION

SECURITY_PROFILE_ID=$(aws connect create-security-profile --instance-id $INSTANCE_ID \
  --security-profile-name elevenlabs-a2a --permissions QConnectAIAgents.View Wisdom.View \
  --region $AWS_REGION --query SecurityProfileId --output text)
awscurl --service connect --region $AWS_REGION -X POST -H 'Content-Type: application/json' \
  --data "{\"AllowedAIAgents\": [{\"Arn\": \"$APPLICATION_ARN\", \"Type\": \"THIRD_PARTY\"}]}" \
  "https://connect.$AWS_REGION.amazonaws.com/security-profiles/$INSTANCE_ID/$SECURITY_PROFILE_ID"

{
  "name": "elevenlabs-handoff",
  "type": "ORCHESTRATION",
  "visibilityStatus": "PUBLISHED",
  "configuration": {
    "orchestrationAIAgentConfiguration": {
      "connectInstanceArn": "<INSTANCE_ARN>",
      "locale": "en_US",
      "multiAgentConfigurations": [
        {
          "handoffAgentConfiguration": {
            "agentTarget": { "applicationId": "<APPLICATION_ARN>" },
            "instruction": {
              "instruction": "Immediately hand off every voice conversation to the ElevenLabs agent."
            },
            "audioStreamingEnabled": true,
            "immediateHandoff": true
          }
        }
      ]
    }
  }
}

awscurl --service wisdom --region $AWS_REGION -X POST -H 'Content-Type: application/json' \
  --data @create-ai-agent.json \
  "https://wisdom.$AWS_REGION.amazonaws.com/assistants/<ASSISTANT_ID>/aiagents"
aws qconnect create-ai-agent-version --assistant-id <ASSISTANT_ID> \
  --ai-agent-id <AI_AGENT_ID> --region $AWS_REGION

for ARN in <AI_AGENT_ARN> <AI_AGENT_ARN>:1; do
  aws connect associate-security-profiles --instance-id $INSTANCE_ID --entity-arn "$ARN" \
    --entity-type AI_AGENT --security-profiles Id=$SECURITY_PROFILE_ID --region $AWS_REGION
done

Build the contact flow

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["wisdom:CreateSession", "wisdom:GetAssistant"],
      "Resource": ["<ASSISTANT_ARN>", "<ASSISTANT_ARN>/*"]
    },
    {
      "Effect": "Allow",
      "Action": ["wisdom:SendMessage", "wisdom:GetNextMessage"],
      "Resource": "arn:aws:wisdom:<REGION>:<ACCOUNT_ID>:session/<ASSISTANT_ID>/*"
    }
  ]
}

aws connect associate-bot --instance-id $INSTANCE_ID \
  --lex-v2-bot AliasArn=<LEX_ALIAS_ARN> --region $AWS_REGION

aws connect associate-phone-number-contact-flow --instance-id $INSTANCE_ID \
  --phone-number-id <PHONE_NUMBER_ID> --contact-flow-id <CONTACT_FLOW_ID> --region $AWS_REGION

aws connect start-outbound-voice-contact --instance-id $INSTANCE_ID \
  --contact-flow-id <CONTACT_FLOW_ID> --destination-phone-number <E164_NUMBER> \
  --source-phone-number <YOUR_CONNECT_NUMBER> --region $AWS_REGION

Test the integration

aws logs filter-log-events --log-group-name /aws/connect/<INSTANCE_ALIAS> \
  --start-time $(( $(date +%s) - 600 ))000 --region $AWS_REGION \
  --query 'events[].message' --output text | tr '\t' '\n' | grep -o '"Results": *"[A-Za-z_]*"'

Dynamic variables

Amazon Connect sends the contact’s system attributes with every session. ElevenLabs exposes them, together with the session identifiers, as dynamic variables:

On Amazon Connect sessions system__caller_id is always the customer and system__called_number is always the Amazon Connect number, for both inbound and outbound contacts.

Every other member of the contact context Amazon Connect sends is exposed the same way: nested names are joined with underscores and converted to snake case under the amazon_connect_ prefix. Custom contact attributes set in your flow with Set contact attributes are not part of the context Amazon Connect currently sends, even when the AI agent’s security profile can view contact attributes; if AWS starts including them, they will appear automatically under the same prefix. You cannot choose which contact data Amazon Connect shares; AWS passes a fixed set of context.

To pass additional context, use the conversation initiation webhook. For Amazon Connect sessions the webhook is called before the agent speaks with caller_id set to the customer’s number, called_number set to the Amazon Connect number, and call_id set to the Amazon Connect contact ID, so a Lambda in your flow can store contact attributes keyed by contact ID and the webhook can return them as dynamic variables and configuration overrides.

Transferring to a human

Amazon Connect routes a contact to a human queue when the ElevenLabs session ends with an Escalate outcome, which your flow’s Escalate branch handles with Set working queue and Transfer to queue. Any queue treatment, whisper flow, or agent selection is handled by Amazon Connect.

The End call tool produces a Complete outcome. Post-call analysis and the post-call webhook run as usual after either outcome.

Only the outcome type and a reason string travel back to Amazon Connect. To hand routing data to the flow, give the agent a webhook tool that calls Amazon Connect’s UpdateContactAttributes API with amazon_connect_contact_id and the values to store, and instruct the agent to call it before ending the call. The flow can then read those attributes with a Check contact attributes block after the Lex block. The post-call webhook fires after the flow has already continued, so it suits CRM updates rather than routing decisions.

Traces

Amazon Connect requires external agents to send trace data for every collaboration. When Amazon Connect subscribes to tracing on the session, ElevenLabs sends an OpenTelemetry trace for each agent turn containing the caller’s transcript, the agent’s response, each tool call with its result, and per-span timing. Amazon Connect stores these traces with the contact; see AI agent traces for how to view them. Transcripts and tool results in these traces are subject to the same redaction settings as the rest of your contact data in Amazon Connect, so review your data-handling requirements before enabling the integration. Like post-call webhooks, traces are delivered to your own systems: agents in zero retention mode still send them, because zero retention governs what ElevenLabs stores, not what your Amazon Connect instance receives.

Audio

Amazon Connect proposes 16-bit mono linear PCM at 8, 16, or 24 kHz on each session and ElevenLabs adopts the proposal, so the agent’s configured audio formats are not used for Amazon Connect sessions. Caller barge-in is detected by ElevenLabs and reported to Amazon Connect so buffered playback is flushed immediately. Keypad input collected by Amazon Connect is delivered to the agent as DTMF digits. Amazon Connect’s own silence marker is ignored; use the agent’s turn timeout to re-prompt a quiet caller.

Limitations and unsupported features

• Client tools and the Play keypad touch tone system tool are not supported. Transfer to number does not yet support Amazon Connect; human handoff arrives as an Amazon Connect transfer type in that tool.
• Data collection results are not returned to the flow, and Amazon Connect decides which contact data it shares. Use the conversation initiation webhook keyed by amazon_connect_contact_id for additional context, a webhook tool that calls UpdateContactAttributes for routing data, and the post-call webhook for everything else.
• Configuration overrides such as system__override_first_message cannot be passed from the flow. Return them from the conversation initiation webhook instead.
• Voice sessions require immediate hand-off. The Amazon Connect chat channel, text streaming, and behind-the-scenes (delegateAgentConfiguration) collaboration are not supported yet.
• Traces sent to Amazon Connect cover the caller’s transcript, the agent’s responses, tool calls with their results, and timing. Tool call parameters are not included.
• Amazon Connect’s third-party agent support is only available where AWS has enabled it and may incur additional AWS charges.

Troubleshooting