connect-kvs-connector

Status: Current | Last reviewed: 2026-09-29

Reads Kinesis Video Streams audio fragments from Amazon Connect and bridges them to ai-orchestrator.

POST /sessions accepts initialContactId alongside the current contactId. Both reach the orchestrator as named Connect metadata; valid UUIDs are persisted for a call-scoped Voice Agent → Copilot handoff. Missing initial identity defaults to the current contact. See Takeda.

Source

apps/connect-kvs-connector

Runtime

Aspect	Value
Language	Java
Protocol	KVS GetMedia
Port	:8093

Note: previously defaulted to :8090 and collided with catalog-builder. Moved to :8093 2026-05-12. See local-port-allocation table in .devcontainer/CLAUDE.md.

What it does

1. Amazon Connect publishes the in-call audio to a Kinesis Video Stream.
2. Connector reads MKV fragments via GetMedia.
3. Demuxes AUDIO_FROM_CUSTOMER and AUDIO_TO_CUSTOMER, interleaving them as stereo PCM16 at 8 kHz. The second track includes everything heard by the customer, including prompts and hold audio.
4. Declares assistant voice/text/A2UI modalities, waits for the orchestrator's ServerHello, and resamples the stereo source to its negotiated PCM16 rate. Supported rates are 8, 16, 24 and 48 kHz; other formats fail explicitly. The streaming FIR keeps channel histories separate and adds 2 ms of delay.

Enable both media directions in the flow. The current reader waits for data in both track buffers; a single-direction stream will not emit frames. The session-start Lambda passes the stream ARN, starting fragment, contact ID and TrueServe agent ID to POST /sessions. The Connect contact ID becomes the conversation ID.

This is read-only — Amazon Connect does not accept audio back through KVS. To inject TTS into a Connect call, use connect-scv-translator or a Connect Lex bot bridge instead.

Dependencies

Service	Purpose
ai-orchestrator	Session + audio
AWS KVS	Stream source
AWS credential provider chain	KVS credentials; optional per-request or CONNECT_KVS_AWS_* overrides

The Java reader does not currently resolve database integration credentials. Set CONNECT_KVS_INTERNAL_TOKEN to require the Lambda's X-Internal-Token header on session startup. Use at least 32 characters and a separate token for each environment. Without a configured token, the existing private-network mode is retained. A healthy /ready response checks capacity, not AWS permissions, flow wiring or successful audio consumption.

Environment selection

Set the contact attribute trueserveEnvironment before invoking the session-start Lambda. Its CONNECTOR_ENDPOINTS JSON configuration maps names such as dev and vanguard to trusted base URLs; CONNECTOR_TOKENS maps those names to separate authentication tokens. The same attribute may be supplied as a Lambda block parameter, which takes precedence.

Missing or blank environment preserves CONNECTOR_URL/CONNECTOR_TOKEN. Unknown environment values reject session startup. Raw URLs from contact attributes are not accepted, redirects are rejected and only HTTP 202 indicates that the connector accepted the request. Check the returned status in the flow; an error object does not itself take the Lambda block's invocation-error branch.

See the Lambda configuration for examples and Terraform settings.

Vanguard

overmind restart connect-kvs-connector

Production

Helm chart at charts/connect-kvs-connector.

See also

• connect-scv-translator
• SIP integrations
• Takeda Connect readiness

Salesforce parent Case context

parentCaseId is an optional session-start field. Lambda forwards the flow’s ParentCaseId; the connector accepts Salesforce Case ID syntax and persists it as salesforce_parent_case_id alongside the original Connect UUID. It is a reference, not an authorization grant. The Takeda handoff tool verifies the Salesforce graph and call identity before surfacing patients. The same Lambda supports the separate pre-voice initialize_case operation; see the Takeda runbook.