answering-machine

Amazon Connect Answering Machine for superluminar.io. Greets callers in German; press 1 to leave a voicemail (recorded → transcribed → posted to Slack #sales-marketing), press 2 to be forwarded to a managing director.

Architecture

Three CDK stacks:

• AnsweringMachineGithubActionsStack — OIDC role for CI (deployed once, by hand).
• AnsweringMachineConnectStack — Amazon Connect instance, claimed phone number, S3 recordings bucket, Slack secret, SSM parameters. Slow to redeploy.
• AnsweringMachineFlowStack — Contact flow, Lambdas, EventBridge rules. Fast iteration.

See docs/superpowers/specs/2026-05-04-answering-machine-design.md for the full design.

First-time setup

1. Create the Slack app

1. Go to https://api.slack.com/apps → Create New App → From scratch → "Answering Machine", superluminar workspace.
2. OAuth & Permissions → add Bot Token Scopes:
   • chat:write
   • files:write
   • chat:write.public (or invite the bot to #sales-marketing after install)
3. Install to Workspace → copy the Bot User OAuth Token (xoxb-…).

2. Deploy

npm install
STAGE=prod npx cdk bootstrap         # only the very first time per account/region

# OIDC role for CI
STAGE=prod npx cdk deploy AnsweringMachineGithubActionsStack
npm run set-github-role-arn       # reads CFN output, runs `gh variable set`

# Slow stack (Connect instance, number, bucket, etc.)
STAGE=prod npx cdk deploy AnsweringMachineConnectStack

# Populate secrets
npm run set-slack-secret    # paste xoxb-…
npm run set-md              # E.164 number + name

# Fast stack (flow, lambdas)
STAGE=prod npx cdk deploy AnsweringMachineFlowStack

3. Phone number

The target is a DE DID. While we wait for AWS regulatory approval (2–6 weeks, up to 60 days), Stack A claims a US toll-free as an interim number; a 1&1 line forwards to it so callers see a DE number on the website.

Interim (active by default)

Stack A's CfnPhoneNumber is configured countryCode: 'US', type: 'TOLL_FREE'. Stack B's PhoneNumberFlowAssociation custom resource binds it to the answering-machine-main flow. After both stacks deploy, the TFN is in the CFN output PhoneNumberAddress and ready to receive calls.

Then, in the 1&1 control center:

1. Rufumleitung on the published DE line → unconditional → target = the TFN in E.164 (+1XXXXXXXXXX).
2. Test-call the 1&1 number from a third phone.

Watch for: 1&1 may replace caller ID with the 1&1 number itself. If Slack shows the same number on every call, that's why — passing CLI through requires a SIP-trunk-tier setup, not basic Rufumleitung.

Target (DE DID)

1. AWS Support Console → Create case → Service: Connect (Number Management), Category: Special Phone Number Request. State: 1× DE local DID for instance <ARN>, business address in DE.
2. AWS replies with a secured S3 link. Upload the HRB-Auszug (issued in the last 6 months) there — do not attach it to the case.
3. Wait. AWS quotes 2–6 weeks; up to 60 days in some cases.
4. Once approved, switch over: in src/stacks/answering-machine-connect-stack.ts change countryCode: 'US' → 'DE' and type: 'TOLL_FREE' → 'DID'. Redeploy Stack A (replacement — the TFN is released, the DE number is claimed) then Stack B (re-runs the flow association). Disable 1&1 forwarding.

See AWS docs: Region requirements and Request numbers.

4. Smoke test

Call the number from your phone. Expect:

• "Willkommen bei superluminar…" greeting.
• Press 1 → "Bitte sprechen Sie nach dem Ton…" → record a short message → "Vielen Dank…" → hangup. Within ~1 minute, a Slack message lands in #sales-marketing with the transcript and audio.
• Press 2 → "Sie werden verbunden…" → MD's phone rings. While ringing, a forward notification appears in Slack.

Operations

Update the MD number / name

npm run set-md

(Takes effect on the next call; no redeploy.)

Update the Slack channel

aws ssm put-parameter --name /answering-machine/slack-channel --value "#new-channel" --overwrite

Rotate the Slack token

npm run set-slack-secret

Development

npm test          # all tests
npm run build     # tsc only
STAGE=prod npx cdk diff AnsweringMachineFlowStack
STAGE=prod npx cdk deploy AnsweringMachineFlowStack