103 lines
2.7 KiB
Markdown
103 lines
2.7 KiB
Markdown
# 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
|