# IVR Local Runbook

Use this runbook to validate both the preview IVR runtime and the live Asterisk-backed IVR staging path.

## What Track 5 adds

- `ivr-service` for IVR flow CRUD and DTMF runtime sessions
- one active IVR flow per voice queue
- `routing-service` support for `ivr_session_id`
- admin-side IVR preview flow in `/admin`

## Preview baseline vs live IVR

- Preview baseline: use the `/admin` IVR block to create flows, start sessions, send DTMF, and preview route overrides without telephony.
- Live Asterisk IVR: call `7200` on the lab PBX after `asterisk-bridge-service` is configured with `ASTERISK_IVR_FASTAGI_*` and the flow nodes have valid `prompt_audio_key` values.

## Create a flow

1. Open `http://localhost:8080/admin`
2. Go to the `IVR` block
3. Set:
   - `queue_id`
   - `entry_node_id` (`root`)
   - `flow_json`
4. Click `Create flow`

The flow JSON is validated before it is saved.

## Start a session

1. In the same `IVR` block, set:
   - `call_id`
   - `queue_id`
   - optional `interaction_id`
2. Click `Start session`

The response returns:

- `session_id`
- `current_node_id`
- current node prompt metadata

## Send DTMF

1. Enter a single digit (`0`-`9`)
2. Click `Send DTMF`

If the transition reaches a terminal node:

- the session becomes `completed`
- `outcome_code` is set
- `resolved_queue_id` is set
- `resolved_queue_code` is set
- a `voice_event` with `event_type="ivr.completed"` is written

## Preview route override

1. Keep the completed `session_id`
2. Click `Preview IVR route`

This calls `routing-service` with `ivr_session_id` and shows:

- `original_queue_id`
- `resolved_queue_id`
- `ivr_outcome_code`

## Demo seed

`scripts/prepare_demo.ps1` now seeds:

- one demo IVR flow
- one completed demo IVR session
- one route preview stored in `.local_stack/demo-seed-summary.json`

Backstage fields:

- `ivr_flow_id`
- `ivr_session_id`
- `ivr_outcome_code`
- `ivr_resolved_queue_id`

## Live Asterisk smoke

1. Enable:
   - `ASTERISK_BRIDGE_ENABLED=1`
   - `ASTERISK_IVR_FASTAGI_ENABLED=1`
   - `IVR_RUNTIME_TRUSTED_SERVICE_SUBJECTS=svc:asterisk-bridge`
2. Make sure `ASTERISK_QUEUE_MAP_JSON` contains `voice_lab_ivr`.
3. Provision the `prompt_audio_key` sound files in Asterisk.
4. Call `7200` and verify:
   - DTMF completes the IVR and transfers through `mvpcc-transfer`
   - silence triggers `ivr.step.no_input`
   - retry exhaustion abandons the IVR session and falls back to the human baseline

## Troubleshooting

- `404 No active IVR flow for queue`
  - create or activate a flow for the target queue first
- `400 Digit must be a single character 0-9`
  - send exactly one DTMF digit
- `400 IVR session is not completed` on route preview
  - finish the session with a terminal node before previewing routing