6 min read

Amazon Connect Integration

An adapter that embeds your organisation's Amazon Connect softphone in ArkCloud and opens the caller's patient account when a call arrives. You bring the Amazon Connect instance; ArkCloud does not provide telephony. It is off until both the deployment and your organisation are configured.

Amazon Connect softphoneNeeds an external connection

Built: an embedded softphone that opens the caller's account. It needs an Amazon Connect instance and is not set up on the hosted service, so the Call Center menu does not appear.

Requires: An Amazon Connect instance, configured for the deployment.

What it does

Embedded softphone (CCP)

The Call Center Console (/dashboard/call-center) embeds your instance's Contact Control Panel, so agents answer and place calls with Amazon's own softphone inside ArkCloud. Agents still sign in to Amazon Connect.

Screen-pop to the caller's account

When a contact arrives, the console opens the matching patient account: directly when the contact flow sets an account_id contact attribute, otherwise by looking the caller's number up. Several matches show a picker; no match shows a notice.

Call disposition

After a call the agent records a disposition code and notes, and optionally a promise-to-pay amount and date or a follow-up date, against the call and the account.

Contact events

A signed receiver records contact events (initiated, connected to agent, disconnected, contact-flow events) as call interactions. See the setup notes below: it needs a signer you provide.

Connection test, queues and flows

Phone Settings can test the credentials and read queues, contact flows and routing profiles from your instance through the AWS SDK.

What it does not do

Outbound dialing started by ArkCloud: no click-to-dial, no predictive, power or preview dialer, no automated reminder or collection calls. The Outbound Campaigns screen does not place calls.

IVR self-service: no payments, balance lookups, payment plans or scheduling by phone.

Call recording list and transcripts inside ArkCloud. Any recording is configured and kept in your Connect instance.

Transcription, Contact Lens, sentiment analysis or speech analytics.

Skills-based routing, callbacks or queue configuration from ArkCloud. Routing is whatever your contact flows do in Amazon Connect.

Live contact-centre figures. Phone Dashboard, Live Calls, Agent Status, Inbound Queues, Outbound Campaigns and the operating-hours screen do not read from Amazon Connect yet: each shows a "not connected" notice describing what it will show, and no figures.

Sending messages or editing contact flows from ArkCloud. Messaging lists recorded messages and templates and has no send or edit controls; on Call Flows, buttons that have no action behind them are disabled and say why.

Setup

1. Deployment (whoever operates ArkCloud)

The Call Center section of the sidebar appears only when the environment variables AWS_CONNECT_INSTANCE_ID and AWS_CONNECT_REGION are both set. They switch the screens on; they do not hold credentials.

To receive contact events, the deployment also needs CONNECT_WEBHOOK_SECRET. Without it the receiver at /api/webhooks/connect answers 503.

2. Your organisation (administrator)

In Call Center → Phone Settings (/dashboard/connect/settings), enter your instance ID, region, CCP URL and an AWS access key ID and secret for an IAM user that may read your Connect instance, then turn the integration on. Saving needs the ADMIN or SUPERVISOR role; the Test connection button needs ADMIN.

These credentials belong to your organisation and are stored with its configuration, separately from any other organisation's.

3. Amazon Connect side

Allow-list the ArkCloud origin for the embedded CCP in your instance's approved origins. For a direct screen-pop, set an account_id contact attribute in your contact flow; otherwise the caller's number is looked up.

Contact events must arrive at /api/webhooks/connect with an HMAC-SHA256 signature of the body in an x-signature header, keyed with CONNECT_WEBHOOK_SECRET. Amazon EventBridge does not sign requests this way, so you need an intermediary (for example API Gateway with a Lambda) that signs and forwards them. None is provided with ArkCloud. Each event must carry its EventBridge id and time: an event older than 24 hours (or more than 5 minutes in the future) is refused, and an event ID already processed is not applied twice.

Phone Settings shows the one endpoint to use - POST /api/webhooks/connect on your ArkCloud address.

Security

Calls, recordings and contact data stay in your Amazon Connect instance and AWS account, under your own AWS agreements, including any business associate agreement you hold with AWS.

The AWS secret access key you enter is encrypted (AES-256-GCM) before it is stored with your organisation's configuration. A key saved before 2026-10-02 is still read, and is stored encrypted once you enter it again in Phone Settings. Give the IAM user the narrowest read permissions on your Connect instance and rotate the key if you stop using the integration.

Twilio Integration Email Providers Communication Webhooks

Setting up Amazon Connect?

Contact Support